NuPay | DEUNA Docs

On this page

Get started with NuPay
Requirements
Integration steps
Testing and integration data

Get started with NuPay#

This page provides a comprehensive guide to successfully integrating NuPay with DEUNA.

NuPay is an advanced platform owned by Nubank. NuPay streamlines online payments and financial transactions, offering a secure and reliable solution for your payment processing needs.

Requirements#

The following content lists all the requirements for a successful integration.

Your NuPay sandbox and production credentials must be requested directly from your NuBank account manager.

Environments:

Sandbox: https://api.sandbox.deuna.io
Production: https://api.deuna.io

Postman collection:

https://www.postman.com/deunaonline/workspace/deuna/folder/30572503-42f68d9b-0763-4002-ba5f-7d1168462e59?action=share&source=copy-link&creator=36841419&ctx=documentation

Integration steps#

Now that the technical requirements are set, you can start the integration.

1. Create an `order_token`

To make a purchase, you must create a DEUNA order.

Make a request to the Create an Order endpoint.

The API returns an order_token that is used throughout the entire flow.

Request

JSON

{
  "order": {
    "order_id": "{{$randomUUID}}", // this can be updated using the "1.2 Update order"
    "store_code": "all", // very important is "all"
    "currency": "BRL",
    "items_total_amount": 1,
    "tax_amount": 0,
    "sub_total": 13000,
    "shipping_amount": 0,
    "payment_method": "wallet", // required for NuPay
    "shipping_tax_amount": 0,
    "total_tax_amount": 0,
    "total_amount": 13000,
    "discounts": [],
    "items": [
      {
        "id": "{{$randomUUID}}",
        "name": "Papas",
        "description": "Papas fritas con paprica",
        "total_amount": {
          "original_amount": 2100,
          "amount": 2050,
          "total_discount": 100,
          "currency": "BRL",
          "currency_symbol": "R$"
        },
        "unit_price": {
          "amount": 1050,
          "currency": "BRL",
          "currency_symbol": "R$"
        },
        "tax_amount": {
          "amount": 50,
          "currency": "BRL",
          "currency_symbol": "R$"
        },
        "quantity": 2,
        "image_url": "https://media-cdn.tripadvisor.com/media/photo-s/1a/e2/c6/68/porcion-de-papas-a-la.jpg",
        "taxable": true
      },
      {
        "id": "{{$randomUUID}}",
        "name": "Refresco",
        "description": "Coca-cola Sprite",
        "total_amount": {
          "original_amount": 75,
          "amount": 90,
          "total_discount": 0,
          "currency": "BRL",
          "currency_symbol": "R$"
        },
        "unit_price": {
          "amount": 75,
          "currency": "BRL",
          "currency_symbol": "R$"
        },
        "tax_amount": {
          "amount": 15,
          "currency": "BRL",
          "currency_symbol": "R$"
        },
        "quantity": 1,
        "image_url": "https://media-cdn.tripadvisor.com/media/photo-s/1a/e2/c6/68/porcion-de-papas-a-la.jpg",
        "taxable": true
      }
    ],
    "shipping_address": {
      "id": "{{$randomInt}}",
      "first_name": "Pablo",
      "last_name": "Murillo",
      "email": "johndoe@deuna.com",
      "identity_document": "58188896454", // required for NuPay
      "identity_document_type": "CPF", // required for NuPay
      "address1": "Praia de Botafogo St.,",
      "address2": "3o. Andar",
      "zipcode": "22251-050",
      "city": "Rio de Janeiro",
      "state_name": "Rio de Janeiro",
      "country_code": "BRA",
      "phone": "+551146733466",
      "lat": -22.943934,
      "lng": -43.182984,
      "additional_description": "confirmar",
      "address_type": "home"
    },
    "billing_address": {
      "id": "{{$randomInt}}",
      "first_name": "Jean",
      "last_name": "Roldan",
      "email": "jroldan@deuna.com",
      "identity_document": "58188896454", // required for NuPay
      "identity_document_type": "CPF", // required for NuPay
      "address1": "Rua Capote Valente",
      "address2": "Pinheiros",
      "zipcode": "05409-002",
      "city": "São Paulo",
      "state_name": "SP",
      "country_code": "BRA",
      "phone": "+5521988939196",
      "lat": -23.555425,
      "lng": -46.677048,
      "address_type": "home"
    },
    "metadata": {
      "origin": "core"
    },
    "browser_details": {
      "screen_height": 1000,
      "screen_width": 2000
    }
  }
}

Response

JSON

{
  "token": "dca264ff-f608-4e0e-99b1-6fed95ddaaae",
  "order_type": "DEUNA_CHECKOUT",
  "order": {
    "order_id": "adb1ef51-e073-49f5-ba3b-a7e42344fd15",
    "store_code": "all",
    "currency": "BRL",
    "tax_amount": 0,
    "display_tax_amount": "BRL 0,00",
    "shipping_amount": 0,
    "display_shipping_amount": "BRL 0,00",
    "items_total_amount": 1,
    "display_items_total_amount": "BRL 0,01",
    "sub_total": 13000,
    "display_sub_total": "BRL 130,00",
    "total_amount": 13000,
    "display_total_amount": "BRL 130,00",
    "items": [
      {
        "id": "8791e81b-5c20-414d-a1ae-3d5ad29bd477",
        "name": "Papas",
        "description": "Papas fritas con paprica",
        "options": "",
        "total_amount": {
          "amount": 2050,
          "original_amount": 2100,
          "display_amount": "BRL 20,50",
          "display_original_amount": "BRL 21,00",
          "currency": "BRL",
          "currency_symbol": "R$",
          "total_discount": 100,
          "display_total_discount": "BRL 1,00"
        },
        "unit_price": {
          "amount": 1050,
          "display_amount": "BRL 10,50",
          "currency": "BRL",
          "currency_symbol": "R$"
        },
        "tax_amount": {
          "amount": 50,
          "display_amount": "BRL 0,50",
          "currency": "BRL",
          "currency_symbol": "R$"
        },
        "quantity": 2,
        "uom": "",
        "upc": "",
        "sku": "",
        "isbn": "",
        "brand": "",
        "manufacturer": "",
        "category": "",
        "color": "",
        "size": "",
        "weight": {
          "weight": 0,
          "unit": ""
        },
        "image_url": "https://media-cdn.tripadvisor.com/media/photo-s/1a/e2/c6/68/porcion-de-papas-a-la.jpg",
        "details_url": "",
        "type": "",
        "taxable": true,
        "discounts": [],
        "included_in_subscription": false,
        "subscription_id": "00000000-0000-0000-0000-000000000000",
        "item_details": []
      },
      {
        "id": "d4ee0dd0-22f2-44c8-9603-7a9c29a20afa",
        "name": "Refresco",
        "description": "Coca-cola Sprite",
        "options": "",
        "total_amount": {
          "amount": 90,
          "original_amount": 75,
          "display_amount": "BRL 0,90",
          "display_original_amount": "BRL 0,75",
          "currency": "BRL",
          "currency_symbol": "R$",
          "total_discount": 0,
          "display_total_discount": "BRL 0,00"
        },
        "unit_price": {
          "amount": 75,
          "display_amount": "BRL 0,75",
          "currency": "BRL",
          "currency_symbol": "R$"
        },
        "tax_amount": {
          "amount": 15,
          "display_amount": "BRL 0,15",
          "currency": "BRL",
          "currency_symbol": "R$"
        },
        "quantity": 1,
        "uom": "",
        "upc": "",
        "sku": "",
        "isbn": "",
        "brand": "",
        "manufacturer": "",
        "category": "",
        "color": "",
        "size": "",
        "weight": {
          "weight": 0,
          "unit": ""
        },
        "image_url": "https://media-cdn.tripadvisor.com/media/photo-s/1a/e2/c6/68/porcion-de-papas-a-la.jpg",
        "details_url": "",
        "type": "",
        "taxable": true,
        "discounts": [],
        "included_in_subscription": false,
        "subscription_id": "00000000-0000-0000-0000-000000000000",
        "item_details": []
      }
    ],
    "discounts": [],
    "shipping_address": {
      "id": 994,
      "user_id": "",
      "first_name": "Pablo",
      "last_name": "Murillo",
      "phone": "+551146733466",
      "identity_document": "58188896454",
      "lat": -22.943934,
      "lng": -43.182984,
      "address1": "Praia de Botafogo St.,",
      "address2": "3o. Andar",
      "city": "Rio de Janeiro",
      "zipcode": "22251-050",
      "state_name": "Rio de Janeiro",
      "country_code": "BRA",
      "additional_description": "confirmar",
      "address_type": "home",
      "is_default": false,
      "created_at": "0001-01-01T00:00:00Z",
      "updated_at": "0001-01-01T00:00:00Z",
      "identity_document_type": "CPF"
    },
    "shipping_options": {
      "type": "",
      "details": {
        "store_name": "",
        "address": "",
        "address_coordinates": {
          "lat": 0,
          "lng": 0
        },
        "contact": {
          "name": "",
          "phone": ""
        },
        "additional_details": {
          "pickup_time": "0001-01-01T00:00:00Z",
          "stock_location": ""
        }
      }
    },
    "user_instructions": "",
    "metadata": {
      "origin": "core"
    },
    "status": "pending",
    "payment": {
      "data": {
        "amount": {
          "amount": 0,
          "currency": ""
        },
        "metadata": {},
        "from_card": {
          "card_brand": "",
          "first_six": "",
          "last_four": "",
          "bank_name": "",
          "country_iso": ""
        },
        "updated_at": "0001-01-01 00:00:00 +0000 UTC",
        "method_type": "",
        "merchant": {
          "store_code": "",
          "id": ""
        },
        "created_at": "0001-01-01 00:00:00 +0000 UTC",
        "id": "",
        "processor": "",
        "customer": {
          "email": "",
          "id": "",
          "first_name": "",
          "last_name": ""
        },
        "status": "",
        "reason": "",
        "external_transaction_id": "",
        "merchant_payment_processor_name": "",
        "authorization_code": "",
        "installment_interest_calculations": null
      }
    },
    "gift_card": [],
    "redirect_url": "",
    "webhook_urls": null,
    "total_discount": 0,
    "display_total_discount": "BRL 0,00",
    "shipping": {
      "original_amount": 0,
      "total_discount": 0,
      "discounts": []
    },
    "cash_change": 0,
    "shipping_method": {
      "code": "",
      "name": "",
      "min_delivery_date": "",
      "max_delivery_date": "",
      "cost": 0,
      "display_cost": "",
      "tax_amount": 0,
      "display_tax_amount": "",
      "scheduler": []
    },
    "shipping_methods": [],
    "timezone": "",
    "scheduled_at": "",
    "billing_address": {
      "id": 688,
      "user_id": "",
      "first_name": "Jean",
      "last_name": "Roldan",
      "phone": "+5521988939196",
      "identity_document": "58188896454",
      "lat": -23.555425,
      "lng": -46.677048,
      "address1": "Rua Capote Valente",
      "address2": "Pinheiros",
      "city": "São Paulo",
      "zipcode": "05409-002",
      "state_name": "SP",
      "country_code": "BRA",
      "additional_description": "",
      "address_type": "home",
      "is_default": false,
      "created_at": "0001-01-01T00:00:00Z",
      "updated_at": "0001-01-01T00:00:00Z",
      "email": "jroldan@deuna.com",
      "identity_document_type": "CPF"
    },
    "payment_link": "",
    "display_shipping_tax_amount": "BRL 0,00",
    "display_total_tax_amount": "BRL 0,00",
    "shipping_tax_amount": 0,
    "total_tax_amount": 0,
    "user_id": "",
    "include_payment_options": [],
    "redirect_urls": {
      "success": "",
      "pending": "",
      "error": "",
      "fallback": "",
      "close": ""
    },
    "created_at": "2024-07-16 14:22:00.336911694 +0000 UTC",
    "updated_at": "",
    "payer_info": null,
    "discount_amount": 0,
    "shipping_discount_amount": 0,
    "device_fingerprint": "",
    "expired_at": "",
    "version": "0",
    "fraud": null,
    "total_interest_amount": 0,
    "display_total_interest_amount": "BRL 0,00",
    "payment_method": "",
    "token": "",
    "statement_descriptor": ""
  },
  "custom_fields": [],
  "checkout_modules": []
}

2. Get order information

Make a request to the Get Order endpoint.

Use this token for the next steps.

Response

JSON

{
  "token": "dca264ff-f608-4e0e-99b1-6fed95ddaaae",
  "order_type": "DEUNA_CHECKOUT",
  "order": {
    "order_id": "adb1ef51-e073-49f5-ba3b-a7e42344fd15",
    "store_code": "all",
    "currency": "BRL",
    "tax_amount": 0,
    "display_tax_amount": "BRL 0,00",
    "shipping_amount": 0,
    "display_shipping_amount": "BRL 0,00",
    "items_total_amount": 1,
    "display_items_total_amount": "BRL 0,01",
    "sub_total": 13000,
    "display_sub_total": "BRL 130,00",
    "total_amount": 13000,
    "display_total_amount": "BRL 130,00",
    "items": [
      {
        "id": "8791e81b-5c20-414d-a1ae-3d5ad29bd477",
        "name": "Papas",
        "description": "Papas fritas con paprica",
        "options": "",
        "total_amount": {
          "amount": 2050,
          "original_amount": 2100,
          "display_amount": "BRL 20,50",
          "display_original_amount": "BRL 21,00",
          "currency": "BRL",
          "currency_symbol": "R$",
          "total_discount": 100,
          "display_total_discount": "BRL 1,00"
        },
        "unit_price": {
          "amount": 1050,
          "display_amount": "BRL 10,50",
          "currency": "BRL",
          "currency_symbol": "R$"
        },
        "tax_amount": {
          "amount": 50,
          "display_amount": "BRL 0,50",
          "currency": "BRL",
          "currency_symbol": "R$"
        },
        "quantity": 2,
        "uom": "",
        "upc": "",
        "sku": "",
        "isbn": "",
        "brand": "",
        "manufacturer": "",
        "category": "",
        "color": "",
        "size": "",
        "weight": {
          "weight": 0,
          "unit": ""
        },
        "image_url": "https://media-cdn.tripadvisor.com/media/photo-s/1a/e2/c6/68/porcion-de-papas-a-la.jpg",
        "details_url": "",
        "type": "",
        "taxable": true,
        "discounts": [],
        "included_in_subscription": false,
        "subscription_id": "00000000-0000-0000-0000-000000000000",
        "item_details": []
      },
      {
        "id": "d4ee0dd0-22f2-44c8-9603-7a9c29a20afa",
        "name": "Refresco",
        "description": "Coca-cola Sprite",
        "options": "",
        "total_amount": {
          "amount": 90,
          "original_amount": 75,
          "display_amount": "BRL 0,90",
          "display_original_amount": "BRL 0,75",
          "currency": "BRL",
          "currency_symbol": "R$",
          "total_discount": 0,
          "display_total_discount": "BRL 0,00"
        },
        "unit_price": {
          "amount": 75,
          "display_amount": "BRL 0,75",
          "currency": "BRL",
          "currency_symbol": "R$"
        },
        "tax_amount": {
          "amount": 15,
          "display_amount": "BRL 0,15",
          "currency": "BRL",
          "currency_symbol": "R$"
        },
        "quantity": 1,
        "uom": "",
        "upc": "",
        "sku": "",
        "isbn": "",
        "brand": "",
        "manufacturer": "",
        "category": "",
        "color": "",
        "size": "",
        "weight": {
          "weight": 0,
          "unit": ""
        },
        "image_url": "https://media-cdn.tripadvisor.com/media/photo-s/1a/e2/c6/68/porcion-de-papas-a-la.jpg",
        "details_url": "",
        "type": "",
        "taxable": true,
        "discounts": [],
        "included_in_subscription": false,
        "subscription_id": "00000000-0000-0000-0000-000000000000",
        "item_details": []
      }
    ],
    "discounts": [],
    "shipping_address": {
      "id": 994,
      "user_id": "",
      "first_name": "Pablo",
      "last_name": "Murillo",
      "phone": "+551146733466",
      "identity_document": "58188896454",
      "lat": -22.943934,
      "lng": -43.182984,
      "address1": "Praia de Botafogo St.,",
      "address2": "3o. Andar",
      "city": "Rio de Janeiro",
      "zipcode": "22251-050",
      "state_name": "Rio de Janeiro",
      "country_code": "BRA",
      "additional_description": "confirmar",
      "address_type": "home",
      "is_default": false,
      "created_at": "0001-01-01T00:00:00Z",
      "updated_at": "0001-01-01T00:00:00Z",
      "identity_document_type": "CPF"
    },
    "shipping_options": {
      "type": "",
      "details": {
        "store_name": "",
        "address": "",
        "address_coordinates": {
          "lat": 0,
          "lng": 0
        },
        "contact": {
          "name": "",
          "phone": ""
        },
        "additional_details": {
          "pickup_time": "0001-01-01T00:00:00Z",
          "stock_location": ""
        }
      }
    },
    "user_instructions": "",
    "metadata": {
      "origin": "core"
    },
    "status": "pending",
    "payment": {
      "data": {
        "amount": {
          "amount": 0,
          "currency": ""
        },
        "metadata": {},
        "from_card": {
          "card_brand": "",
          "first_six": "",
          "last_four": "",
          "bank_name": "",
          "country_iso": ""
        },
        "updated_at": "0001-01-01 00:00:00 +0000 UTC",
        "method_type": "",
        "merchant": {
          "store_code": "",
          "id": ""
        },
        "created_at": "0001-01-01 00:00:00 +0000 UTC",
        "id": "",
        "processor": "",
        "customer": {
          "email": "",
          "id": "",
          "first_name": "",
          "last_name": ""
        },
        "status": "",
        "reason": "",
        "external_transaction_id": "",
        "merchant_payment_processor_name": "",
        "authorization_code": "",
        "installment_interest_calculations": null
      }
    },
    "gift_card": [],
    "redirect_url": "",
    "webhook_urls": null,
    "total_discount": 0,
    "display_total_discount": "BRL 0,00",
    "shipping": {
      "original_amount": 0,
      "total_discount": 0,
      "discounts": []
    },
    "cash_change": 0,
    "shipping_method": {
      "code": "",
      "name": "",
      "min_delivery_date": "",
      "max_delivery_date": "",
      "cost": 0,
      "display_cost": "",
      "tax_amount": 0,
      "display_tax_amount": "",
      "scheduler": []
    },
    "shipping_methods": [],
    "timezone": "",
    "scheduled_at": "",
    "billing_address": {
      "id": 688,
      "user_id": "",
      "first_name": "Jean",
      "last_name": "Roldan",
      "phone": "+5521988939196",
      "identity_document": "58188896454",
      "lat": -23.555425,
      "lng": -46.677048,
      "address1": "Rua Capote Valente",
      "address2": "Pinheiros",
      "city": "São Paulo",
      "zipcode": "05409-002",
      "state_name": "SP",
      "country_code": "BRA",
      "additional_description": "",
      "address_type": "home",
      "is_default": false,
      "created_at": "0001-01-01T00:00:00Z",
      "updated_at": "0001-01-01T00:00:00Z",
      "email": "jroldan@deuna.com",
      "identity_document_type": "CPF"
    },
    "payment_link": "",
    "display_shipping_tax_amount": "BRL 0,00",
    "display_total_tax_amount": "BRL 0,00",
    "shipping_tax_amount": 0,
    "total_tax_amount": 0,
    "user_id": "",
    "include_payment_options": [],
    "redirect_urls": {
      "success": "",
      "pending": "",
      "error": "",
      "fallback": "",
      "close": ""
    },
    "created_at": "2024-07-16 14:22:00.336911694 +0000 UTC",
    "updated_at": "",
    "payer_info": null,
    "discount_amount": 0,
    "shipping_discount_amount": 0,
    "device_fingerprint": "",
    "expired_at": "",
    "version": "0",
    "fraud": null,
    "total_interest_amount": 0,
    "display_total_interest_amount": "BRL 0,00",
    "payment_method": "",
    "token": "",
    "statement_descriptor": ""
  },
  "custom_fields": [],
  "checkout_modules": [],
  "refunds": []
}

Check the customer's consent while they authorize the payment in their account.

Sample the status by polling until the status changes.

Consent statuses:

pending
success
failed

Response

JSON

{
  "id": "f9c35e61-d2ff-444a-9b3b-ce3c8e9f0597",
  "type": "transaction.authentication.pending",
  "created": "1721140413",
  "callback_url": "",
  "data": {
    "request_id": "",
    "order": {
      "order_token": "dca264ff-f608-4e0e-99b1-6fed95ddaaae",
      "transaction_id": "adb1ef51-e073-49f5-ba3b-a7e42344fd15",
      "external_transaction_id": ""
    },
    "consent": {
      "id": "020f896d-15f8-48c1-8358-01d50b70d5a9",
      "status": "pending",
      "expires_at": "2024-07-16T14:43:33.435273111Z",
      "authorization_id": "BzxEmevjvSU8D4_GI6CJeZzY9IcS4lDaP4Dmwr8WQSg"
    },
    "error": null
  }
}

To get the current status, make a GET request using the order token.

Check that the field status now contains the value “success”.

Get the customer consent while they authorize the payment in their account.

Request

curl --location '{{base_url}}/merchants/orders/{{order_token}}/consent' \
--header 'X-API-KEY: {{merchant_private_key}}' \
--header 'Content-Type: application/json' \
--header 'X-Request-Id: xxxxx' \
--header 'Authorization: {{user_token}}'

const response = await fetch("{{base_url}}/merchants/orders/{{order_token}}/consent", {
  method: "GET",
  headers: {
    "X-API-KEY": "{{merchant_private_key}}",
    "Content-Type": "application/json",
    "X-Request-Id": "xxxxx",
    "Authorization": "{{user_token}}"
  }
});

if (!response.ok) throw new Error(`Request failed: ${response.status}`);
const data = await response.json();

import requests

response = requests.request(
    "GET",
    "{{base_url}}/merchants/orders/{{order_token}}/consent",
    headers={
        "X-API-KEY": "{{merchant_private_key}}",
        "Content-Type": "application/json",
        "X-Request-Id": "xxxxx",
        "Authorization": "{{user_token}}"
    },
)
response.raise_for_status()
data = response.json()

<?php
$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "{{base_url}}/merchants/orders/{{order_token}}/consent",
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => [
    "X-API-KEY: {{merchant_private_key}}",
    "Content-Type: application/json",
    "X-Request-Id: xxxxx",
    "Authorization: {{user_token}}"
  ]
]);

$response = curl_exec($curl);
curl_close($curl);

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

public class Example {
  public static void main(String[] args) throws Exception {
    HttpRequest request = HttpRequest.newBuilder()
      .uri(URI.create("{{base_url}}/merchants/orders/{{order_token}}/consent"))
      .header("X-API-KEY", "{{merchant_private_key}}")
      .header("Content-Type", "application/json")
      .header("X-Request-Id", "xxxxx")
      .header("Authorization", "{{user_token}}")
      .method("GET", HttpRequest.BodyPublishers.noBody())
      .build();

    HttpResponse<String> response = HttpClient.newHttpClient().send(
      request, HttpResponse.BodyHandlers.ofString()
    );
    System.out.println(response.body());
  }
}

package main

import (
  "fmt"
  "io"
  "net/http"
)

func main() {
  request, err := http.NewRequest("GET", "{{base_url}}/merchants/orders/{{order_token}}/consent", nil)
  if err != nil { panic(err) }
  request.Header.Set("X-API-KEY", "{{merchant_private_key}}")
  request.Header.Set("Content-Type", "application/json")
  request.Header.Set("X-Request-Id", "xxxxx")
  request.Header.Set("Authorization", "{{user_token}}")

  response, err := http.DefaultClient.Do(request)
  if err != nil { panic(err) }
  defer response.Body.Close()

  body, _ := io.ReadAll(response.Body)
  fmt.Println(string(body))
}

Response

JSON

{
  "id": "75a2a589-ffe6-4d75-b3b3-6c4950f9fd6d",
  "type": "transaction.authentication.updated",
  "created": "1721140820",
  "callback_url": "",
  "data": {
    "request_id": "4e72819f-dec6-4d1d-b474-1f47e2ca24ba",
    "order": {
      "order_token": "dca264ff-f608-4e0e-99b1-6fed95ddaaae",
      "transaction_id": "adb1ef51-e073-49f5-ba3b-a7e42344fd15",
      "external_transaction_id": ""
    },
    "consent": {
      "id": "020f896d-15f8-48c1-8358-01d50b70d5a9",
      "status": "success",
      "expires_at": "2024-07-31T14:33:59.015219Z",
      "authorization_id": "BzxEmevjvSU8D4_GI6CJeZzY9IcS4lDaP4Dmwr8WQSg"
    },
    "error": null
  }
}

5. Get payment methods

Confirm the payment methods to obtain the NuPay configuration.

Make a request to the Get Payment Methods endpoint.

The response contains:

The payment methods available for the purchase.
The number of installments that the customer can use.

Correct responses for method_type" include:

"nupay_credit"
"nupay_debit"
"nupay_credit_with_additional_limit"

Response

JSON

{
  "@type": "type.googleapis.com/external_merchant_api.v1.GetPaymentMethodsResponse",
  "data": [
    {
      "enabled": true,
      "method_type": "nupay_credit",
      "processor_name": "nupay",
      "specific_fields": null,
      "input_schema": [],
      "labels": {
        "es": ""
      },
      "exclude_cvv": false,
      "excluded_franchises": [],
      "extra_params": {},
      "installments": [
        {
          "installments": 1,
          "installments_amount": 13000,
          "display_installments_amount": "130.00",
          "installment_rate": 0,
          "display_installment_label": "",
          "plan_option_id": "c397a748-eda8-4878-a5b2-953415b51fad",
          "installment_total_amount": "13000",
          "amount_percentage": 10.0,
          "total_amount_percentage": 10.0,
          "installment_plan_additional_limit": 10.0,
          "installment_tax": [
          {
            "id": "INTERESTS",
            "rate": 0.05,
            "tax_amount": 1250
          },
          {
            "id": "IOF",
            "rate": 0.0038,
            "tax_amount": 125
          },
          {
            "id": "CET",
            "rate": 0.054,
            "tax_amount": 0
          }
         ]
        },
        {
          "installments": 2,
          "installments_amount": 6500,
          "display_installments_amount": "65.00",
          "installment_rate": 0,
          "display_installment_label": "",
          "plan_option_id": "cc39c974-5650-468e-ae1e-1a57b369fc74",
          "installment_total_amount": "6500",
          "amount_percentage": 10.0,
          "total_amount_percentage": 10.0,
          "installment_plan_additional_limit": 9.0,
          "installment_tax": [
          {
            "id": "INTERESTS",
            "rate": 0.05,
            "tax_amount": 1250
          },
          {
            "id": "IOF",
            "rate": 0.0038,
            "tax_amount": 125
          },
          {
            "id": "CET",
            "rate": 0.054,
            "tax_amount": 0
          }
         ]
        }
      ],
      "credentials": {
        "public_api_key": "",
        "external_merchant_id": ""
      }
    }
  ]
}

6. Make a purchase

Make a request to the Purchase V2 endpoint and process the payment.

Response

JSON

{
  "order": {
    "cash_change": 0,
    "currency": "USD",
    "discounts": [],
    "display_items_total_amount": "",
    "display_shipping_amount": "",
    "display_sub_total": "",
    "display_tax_amount": "",
    "display_total_amount": "",
    "display_total_discount": "",
    "gift_card": [],
    "items": [
      {
        "brand": "",
        "category": "",
        "color": "",
        "description": "Papa Fritas",
        "details_url": "",
        "discounts": [],
        "id": "001",
        "image_url": "https://images-staging.getduna.com/95463fb5-6279-4ec3-8ff9-fe07aacd2142/cd928351d12c6b96_domicilio_316_744x744.png?d=600x600",
        "isbn": "",
        "manufacturer": "",
        "name": "Papa Fritas",
        "options": "",
        "quantity": 1,
        "size": "",
        "sku": "",
        "tax_amount": {
          "amount": 44,
          "currency": "USD",
          "currency_symbol": "$",
          "display_amount": ""
        },
        "taxable": false,
        "total_amount": {
          "amount": 594,
          "currency": "USD",
          "currency_symbol": "$",
          "display_amount": "",
          "display_original_amount": "",
          "display_total_discount": "",
          "original_amount": 0,
          "total_discount": 0
        },
        "type": "",
        "unit_price": {
          "amount": 550,
          "currency": "USD",
          "currency_symbol": "$",
          "display_amount": ""
        },
        "uom": "",
        "upc": "",
        "weight": {
          "unit": "",
          "weight": 0
        }
      },
      {
        "brand": "",
        "category": "",
        "color": "",
        "description": "Hamburguesa ",
        "details_url": "",
        "discounts": [],
        "id": "002",
        "image_url": "https://images-staging.getduna.com/95463fb5-6279-4ec3-8ff9-fe07aacd2142/cd928351d12c6b96_domicilio_51330_744x744_1646338877.png?d=600x600",
        "isbn": "",
        "manufacturer": "",
        "name": "Hamburguesa",
        "options": "",
        "quantity": 2,
        "size": "",
        "sku": "",
        "tax_amount": {
          "amount": 88,
          "currency": "USD",
          "currency_symbol": "$",
          "display_amount": ""
        },
        "taxable": false,
        "total_amount": {
          "amount": 3088,
          "currency": "USD",
          "currency_symbol": "$",
          "display_amount": "",
          "display_original_amount": "",
          "display_total_discount": "",
          "original_amount": 0,
          "total_discount": 0
        },
        "type": "",
        "unit_price": {
          "amount": 1500,
          "currency": "USD",
          "currency_symbol": "$",
          "display_amount": ""
        },
        "uom": "",
        "upc": "",
        "weight": {
          "unit": "",
          "weight": 0
        }
      }
    ],
    "items_total_amount": 3682,
    "metadata": {
      "key1": "NO REQUERIDO",
      "key2": "NO REQUERIDO"
    },
    "order_id": "order116",
    "payment": {
      "data": {
        "amount": {
          "amount": 3770,
          "currency": "USD"
        },
        "authorization_3ds": {
          "html_content": "<div></div>",
          "url_challenge": "",
          "version": "1.1.1"
        },
        "authorization_code": "TEST00",
        "created_at": "2022-07-22 20:22:48.408419489 +0000 UTC",
        "customer": {
          "email": "jhondoe@deuna.com",
          "id": "xxxxxx-0eb3-450f-8b26-4ff23208470f"
        },
        "from_card": {
          "card_brand": "Visa",
          "first_six": "411111",
          "last_four": "1111"
        },
        "id": "order116",
        "installments": {
          "installment_amount": 5999,
          "installment_rate": 0.12,
          "installment_type": "MCI",
          "installments": 3,
          "plan_id": "7471ed27-094d-44c4-a62d-225644b782f7",
          "plan_option_id": "87309ea8-3942-4fdf-95ec-ce29a792aff2"
        },
        "merchant": {
          "id": "9a85e296-cc3d-454b-b591-208d6e538126",
          "store_code": "all"
        },
        "metadata": {
          "authorization_code": "TEST00"
        },
        "method_type": "credit_card",
        "processor": "paymentez",
        "reason": "",
        "status": "processed",
        "updated_at": "2022-07-22 20:22:48.408809765 +0000 UTC"
      }
    },
    "redirect_url": "",
    "scheduled_at": "",
    "shipping": null,
    "shipping_address": {
      "additional_description": "Piso 9",
      "address_type": "home",
      "address1": "Av. de los Incas 15-33, Ambato 180202, Ecuador",
      "address2": "Av. de los Incas 15-33, Ambato 180202, Ecuador",
      "city": "Ambato",
      "country_code": "EC",
      "created_at": "0001-01-01T00:00:00Z",
      "first_name": "Jhon",
      "id": 0,
      "identity_document": "146565656",
      "is_default": true,
      "last_name": "Doe",
      "lat": -1.2480678792202227,
      "lng": -78.62532788804577,
      "phone": " 946565665",
      "state_name": "Tungurahua",
      "updated_at": "0001-01-01T00:00:00Z",
      "user_id": "xxxxx4e2-xxxx-xxxx-xxxx-xxxxx5b7b2e",
      "zipcode": "180202"
    },
    "shipping_amount": 0,
    "shipping_method": null,
    "shipping_methods": [],
    "shipping_options": {},
    "status": "succeeded",
    "store_code": "",
    "sub_total": 3550,
    "tax_amount": 132,
    "timezone": "",
    "total_amount": 3770,
    "total_discount": 0,
    "user_instructions": "Piso 9",
    "webhook_urls": null
  },
  "order_token": "0b98dbe8-d265-49bc-b80d-536cea46509c"
}

Testing and integration data#

This section provides testing data and response information for a successful integration with NuPay.

Payment installments

It is required that the installment object is filled with the plan_option_id attribute. For one payment, use 1 installment.

Request

JSON

{
    "transaction_id": "{{transaction_id}}",
    "amount": {{total_amount}},
    "device_id": "{{$randomUUID}}",
    "order_token": "{{order_token}}",
    "payer_info": {
        "email": "eposada@deuna.com" // email of the purchaser
    },
    "payment_source": {
        "method_type": "nupay_credit",
        "processor": "NUPAY",
        **"installment": {
            "plan_option_id": "{{plan_option_id}}" // Here you must send the plan_option_id for 1x installment, for debit or credit.
        }
    }
}

Response

JSON

{
  "order_type": "DEUNA_CHECKOUT",
  "order_token": "dca264ff-f608-4e0e-99b1-6fed95ddaaae",
  "order": {
    "order_id": "adb1ef51-e073-49f5-ba3b-a7e42344fd15",
    "store_code": "all",
    "currency": "BRL",
    "tax_amount": 0,
    "display_tax_amount": "",
    "shipping_amount": 0,
    "display_shipping_amount": "BRL 0,00",
    "items_total_amount": 1,
    "display_items_total_amount": "BRL 0,01",
    "sub_total": 13000,
    "display_sub_total": "BRL 130,00",
    "total_amount": 13000,
    "display_total_amount": "BRL 130,00",
    "items": [
      {
        "id": "8791e81b-5c20-414d-a1ae-3d5ad29bd477",
        "name": "Papas",
        "description": "Papas fritas con paprica",
        "options": "",
        "total_amount": {
          "amount": 2050,
          "original_amount": 2100,
          "display_amount": "BRL 20,50",
          "display_original_amount": "BRL 21,00",
          "currency": "BRL",
          "currency_symbol": "R$",
          "total_discount": 100,
          "display_total_discount": "BRL 1,00"
        },
        "unit_price": {
          "amount": 1050,
          "display_amount": "BRL 10,50",
          "currency": "BRL",
          "currency_symbol": "R$"
        },
        "tax_amount": {
          "amount": 50,
          "display_amount": "BRL 0,50",
          "currency": "BRL",
          "currency_symbol": "R$"
        },
        "quantity": 2,
        "uom": "",
        "upc": "",
        "sku": "",
        "isbn": "",
        "brand": "",
        "manufacturer": "",
        "category": "",
        "color": "",
        "size": "",
        "weight": {
          "weight": 0,
          "unit": ""
        },
        "image_url": "https://media-cdn.tripadvisor.com/media/photo-s/1a/e2/c6/68/porcion-de-papas-a-la.jpg",
        "details_url": "",
        "type": "",
        "taxable": true,
        "discounts": [],
        "included_in_subscription": false,
        "subscription_id": "00000000-0000-0000-0000-000000000000",
        "item_details": []
      },
      {
        "id": "d4ee0dd0-22f2-44c8-9603-7a9c29a20afa",
        "name": "Refresco",
        "description": "Coca-cola Sprite",
        "options": "",
        "total_amount": {
          "amount": 90,
          "original_amount": 75,
          "display_amount": "BRL 0,90",
          "display_original_amount": "BRL 0,75",
          "currency": "BRL",
          "currency_symbol": "R$",
          "total_discount": 0,
          "display_total_discount": "BRL 0,00"
        },
        "unit_price": {
          "amount": 75,
          "display_amount": "BRL 0,75",
          "currency": "BRL",
          "currency_symbol": "R$"
        },
        "tax_amount": {
          "amount": 15,
          "display_amount": "BRL 0,15",
          "currency": "BRL",
          "currency_symbol": "R$"
        },
        "quantity": 1,
        "uom": "",
        "upc": "",
        "sku": "",
        "isbn": "",
        "brand": "",
        "manufacturer": "",
        "category": "",
        "color": "",
        "size": "",
        "weight": {
          "weight": 0,
          "unit": ""
        },
        "image_url": "https://media-cdn.tripadvisor.com/media/photo-s/1a/e2/c6/68/porcion-de-papas-a-la.jpg",
        "details_url": "",
        "type": "",
        "taxable": true,
        "discounts": [],
        "included_in_subscription": false,
        "subscription_id": "00000000-0000-0000-0000-000000000000",
        "item_details": []
      }
    ],
    "discounts": [],
    "shipping_address": {
      "id": 994,
      "user_id": "",
      "first_name": "Pablo",
      "last_name": "Murillo",
      "phone": "+551146733466",
      "identity_document": "58188896454",
      "lat": -22.943934,
      "lng": -43.182984,
      "address1": "Praia de Botafogo St.,",
      "address2": "3o. Andar",
      "city": "Rio de Janeiro",
      "zipcode": "22251-050",
      "state_name": "Rio de Janeiro",
      "country_code": "BRA",
      "additional_description": "confirmar",
      "address_type": "home",
      "is_default": false,
      "created_at": "0001-01-01T00:00:00Z",
      "updated_at": "0001-01-01T00:00:00Z",
      "identity_document_type": "CPF"
    },
    "shipping_options": null,
    "user_instructions": "",
    "metadata": {
      "origin": "core"
    },
    "status": "pending",
    "payment": {
      "data": {
        "amount": {
          "amount": 13000,
          "currency": "BRL"
        },
        "metadata": {
          "authorization_code": "",
          "external_transaction_id": "afa0a436-6f4a-4583-84c4-430639f5e7d9"
        },
        "from_card": {
          "card_brand": "",
          "first_six": "",
          "last_four": "",
          **"installment": {
            "installments": 1,
            "plan_id": "f90e1c3e-eb23-4706-90aa-8e289a38d382",
            "plan_option_id": "c397a748-eda8-4878-a5b2-953415b51fad",
            "installment_type": "MCI",
            "installment_rate": 0,
            "installment_amount": 0**
          },
          "bank_name": "",
          "country_iso": ""
        },
        "updated_at": "2024-07-16 14:55:17.393166774 +0000 UTC",
        "method_type": "credit",
        "merchant": {
          "store_code": "all",
          "id": "20a5bc23-f349-489b-a183-a3e0f09556a6"
        },
        "created_at": "2024-07-16 14:55:17.392079806 +0000 UTC",
        "id": "adb1ef51-e073-49f5-ba3b-a7e42344fd15",
        "processor": "nupay",
        "customer": {
          "email": "eposada@deuna.com",
          "id": "40c3ec29-8562-41c6-bb47-96ca7c852e01",
          "first_name": "",
          "last_name": ""
        },
        "status": "processing",
        "reason": "",
        "external_transaction_id": "afa0a436-6f4a-4583-84c4-430639f5e7d9",
        "merchant_payment_processor_name": "",
        "authorization_code": "",
        "installment_interest_calculations": null
      }
    },
    "gift_card": [],
    "redirect_url": "",
    "webhook_urls": null,
    "total_discount": 0,
    "display_total_discount": "BRL 0,00",
    "shipping": null,
    "cash_change": 0,
    "shipping_method": null,
    "shipping_methods": [],
    "timezone": "",
    "scheduled_at": "",
    "billing_address": {
      "id": 688,
      "user_id": "",
      "first_name": "Jean",
      "last_name": "Roldan",
      "phone": "+5521988939196",
      "identity_document": "58188896454",
      "lat": -23.555425,
      "lng": -46.677048,
      "address1": "Rua Capote Valente",
      "address2": "Pinheiros",
      "city": "São Paulo",
      "zipcode": "05409-002",
      "state_name": "SP",
      "country_code": "BRA",
      "additional_description": "",
      "address_type": "home",
      "is_default": false,
      "created_at": "0001-01-01T00:00:00Z",
      "updated_at": "0001-01-01T00:00:00Z",
      "email": "jroldan@deuna.com",
      "identity_document_type": "CPF"
    },
    "payment_link": "",
    "display_shipping_tax_amount": "BRL 0,00",
    "display_total_tax_amount": "BRL 0,00",
    "shipping_tax_amount": 0,
    "total_tax_amount": 0,
    "user_id": "",
    "include_payment_options": [],
    "redirect_urls": {
      "success": "",
      "pending": "",
      "error": "",
      "fallback": "",
      "close": ""
    },
    "created_at": "",
    "updated_at": "",
    "payer_info": null,
    "discount_amount": 0,
    "shipping_discount_amount": 0,
    "device_fingerprint": "",
    "expired_at": "",
    "version": "0",
    "fraud": {
      "analysis": {
        "score": 0.0405804,
        "processor": "SIFT",
        "risk_level": "",
        "status": "automatic_decision",
        "type": "",
        "fraud_decision": "",
        "details": "",
        "processor_response": ""
      }
    },
    "display_total_interest_amount": "",
    "payment_method": "",
    "token": "",
    "statement_descriptor": ""
  }
}

Refunds

For refunds, use the V2 Refund endpoint.

NuPay always returns a refunding status and supports multiple partial refunds.

Retrieve the original payment to confirm the final refund status after DEUNA processes the provider update.

Request

JSON

{
    "reason": "refund requested",
    "amount": 13000 //Here the amount can be total or partial. If you don't send this parameter, then the refund will be total.
}

Response

JSON

{
  "data": {
    "refund_id": "58635dc5-a968-4da2-bb71-617f74bb3723",
    "status": "refunding",
    "refund_amount": {
      "amount": "13000",
      "currency": "BRL"
    },
    "order": null,
    "refunds": [ // lists all the refunds associated to the same order
      {
        "refund_id": "58635dc5-a968-4da2-bb71-617f74bb3723",
        "refund_amount": {
          "amount": "13000",
          "currency": "BRL"
        },
        "refunded_on": "2024-07-16T14:58:30Z",
        "status": "refunding",
        "external_transaction_id": "3dbd1cce-85b8-4c8c-b745-b894825e9866"
      }
    ]
  },
  "error": null
}

Sandbox testing

You can use the data provided in the following tables to test NuPay in your sandbox environment.

Documents or CPFs for testing:

CPF number	Description
58188896454	Authorization accepted by the customer for any type of charge.
31457612500	Authorization denied by the customer.

Simulating installment responses:

Amount range	Simulation scenario
Amount between R$ 0.01 and R$ 100.00	Debit
Amount between R$ 101.00 and R$ 200.00	Credit
Amount between R$ 201.00 and R$ 500.00	Credit with interest
Amount with any amount above R$501.00	Debit, credit, and credit with interest. A maximum of 3 installments are shown in the response body.

Error codes

Use the information provided in the following tables to corroborate your integration if something went wrong during any step.

Customer consent:

Code	Message	HTTP Status	Action	Message	Reason
DP-4024	Invalid merchant ID	400	Contact DEUNA support	failed	Credentials mismatch, verify your credentials.
DP-3000	Invalid payload	400	Retry	failed	Verify the provided payload for the consent request.
DP-5002	Internal error	500	Contact DEUNA support	failed	Internal DEUNA error.
DP-4025	Consent creation failed	400	Retry	failed	Verify your processor configuration in DEUNAs administrative portal.

Get payment methods

Code	Message	Next action
DP-20001	Failed get Authorization	Verify the request body and retry the request.
DP-20002	Failed in Get Token	Verify the request body and retry the request.
DP-20003	Failed to get payment conditions	Verify the request body and retry the request.

Purchases

Code	Message	Reason
DP-4026	SYSTEM_ERROR	The system can not process this payment now. Please try again later.
DP-4026	CANCELLED_BY_USER	The user cancelled the payment.
DP-4026	CANCELLED_BY_TIMEOUT	This payment was cancelled due to timeout.
DP-4026	CANCELLED_BY_INSTITUTION	The institution cancelled the payment.
DP-4026	CANCELLED_BY_SELLER	Seller has cancelled this payment.

In this section

NuPay via Widget

Get started with NuPayAsk Athia about this#

RequirementsAsk Athia about this#

Integration stepsAsk Athia about this#

1. Create an order_token

2. Get order information

3. Get customer consent

4. Get consent status

5. Get payment methods

6. Make a purchase

Testing and integration dataAsk Athia about this#

Payment installments

Refunds

Sandbox testing

Error codes

In this section

Get started with NuPay#

Requirements#

Integration steps#

1. Create an `order_token`

Testing and integration data#