NuPay

Get started with NuPay

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

NuPay is an advanced platform that 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.

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 step-by-step integration.

1. Create an`order_token`

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

Follow the steps to Create an Order.

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

📘
webhook_urls/notify_order receives the DEUNA URL that sends the status of the customer’s consent when it receives an update.

Endpoint: https://{{base_url}}/merchants/orders
Method: POST

Request Example

{
  "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": "[email protected]",
      "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": "[email protected]",
      "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
    },
    **"webhook_urls": {
      "notify_order": "https://webhook.site/065ef7c7-38e8-48aa-9da7-49f73a2d7a2a" // URL for DEUNA to send webhooks
    }**
  }
}

Response Example

{
  "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": "[email protected]",
      "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

It is possible to get the order information using a GET Request

Endpoint: https://{{base_url}}/merchants/orders/{{order_token}}
Method: GET

Response Example

{
  "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": "[email protected]",
      "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": []
}

3. Update order

It is possible to update an order using the following endpoint

Is the same endpoint to create an order, but if any field is changed, the order will be updated with the new value/information.

Endpoint: https://{{base_url}}/merchants/orders
Method: /POST

4. Get the customer’s consent

This request will get the customer’s consent to move forward with the purchase.
The request body can be empty.

Endpoint: https://{{base_url}}/merchants/orders/{{order_token}}/consent
Method: /POST

Consent statuses:

pending
success
failed

Response Example

{
  "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
  }
}

📘
The field status will start with the value pending, and it will change when the customer concludes the consent flow on its Nubank App.
DEUNA will send the status update also thru a webhook event.

To get the current status will be there 2 options.

Make a GET request to see the new status
Receive the status update thru webhooks.

5- Check the consent status

Use the GET endpoint to check the Consent current status

Endpoint: https://{{base_url}}/merchants/orders/{{order_token}}/consent
Method: GET

Check that the field status is now with the value “success”

Response Example

{
  "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
  }
}

6. Check payment methods

With the customer’s consent, now it is possible to check the payment methods (conditions) available

Endpoint: https://{{base_url}}/merchants/orders/{{order_token}}/payments-methods?restrict_to_payment_methods=NUPAY
Method: GET

📘
The parameter ?restrict_to_payment_methods=NUPAY in the endpoint URL is mandatory

The response will bring the methods available to the purchase, and also the number of the installments that the customer is allowed to use.
"method_type": "nupay_credit" or "nupay_debit"
"installments": []

🚧
The installments API returns HTTP 200 OK and an empty response body if there are no payment options applicable to the user. This usually means that the customer has no limit or balance in their Nubank account.

Response Example

{
  "@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",
          "installment_tax": []
        },
        {
          "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",
          "installment_tax": []
        }
      ],
      "credentials": {
        "public_api_key": "",
        "external_merchant_id": ""
      }
    }
  ]
}

Testing and integration data

Payment installments

Endpoint: https://{{base_url}}/v2/merchants/orders/purchase
Method: POST

🚧
In case, the customer wants to purchase without installments it is still require for the merchant to send in the purchase API the plan_option_id related to 1 installment

🚧
The /purchase V2 API will return a validation error when the plan_option_id is not provided.
This only applies to NuPay.

Request Example

{
    "transaction_id": "{{transaction_id}}",
    "amount": {{total_amount}},
    "device_id": "{{$randomUUID}}",
    "order_token": "{{order_token}}",
    "payer_info": {
        "email": "[email protected]" // email of the purchaser
    },
    "payment_source": {
        "method_type": "nupay_credit",
        "processor": "NUPAY",
        **"installment": {
            "plan_option_id": "{{plan_option_id}}" // Here is mandatory to send the plan_option_id for 1x installment, for debit or credit.
        }
    }
}

Response Example

{
  "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": "[email protected]",
          "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": "[email protected]",
      "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": ""
  }
}

Create an order refund

Endpoint: https://{{base_url}}/v2/merchants/orders/{{order_token}}/refund
Method: POST

📘
Nupay always returns back a refunding status. It is important for the merchant to listen to DEUNA's webhooks to get notified on the final status of a refund.

📘
Nupay does support multiple partial refunds

🚧
It is mandatory to use the refunds V2 API from DEUNA

📘
If you don't send the parameter "amount" in the request body, the refund will be total.

Request Example

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

Response Example

{
  "data": {
    "refund_id": "58635dc5-a968-4da2-bb71-617f74bb3723",
    "status": "refunding",
    "refund_amount": {
      "amount": "13000",
      "currency": "BRL"
    },
    "order": null,
    "refunds": [ // list of 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 data

Documents/CPFs for testing:

📘
The document number must be sent in the Order Creation request body (Step 1).

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

Simulating Installments Responses:

📘
The amount must be sent in the Order Creation request body (Step 1).

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 will be shown in the response body).

Error codes

Customer’s Consent:

Code	Message	HTTP Status	Action	Message	Reason
DP-4024	invalid merchant ID	400	Contact DEUNA support	failed	This could be due to a credentials mismatch
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.

NuPay

Get started with NuPay

Requirements

Integration steps

1. Create an`order_token`

📘
`webhook_urls/notify_order` receives the DEUNA URL that sends the status of the customer’s consent when it receives an update.

2. Get order information

3. Update order

4. Get the customer’s consent

📘
The field `status` will start with the value `pending`, and it will change when the customer concludes the consent flow on its Nubank App.

5- Check the consent status

6. Check payment methods

📘
The parameter `?restrict_to_payment_methods=NUPAY` in the endpoint URL is mandatory

🚧
The installments API returns HTTP 200 OK and an empty response body if there are no payment options applicable to the user. This usually means that the customer has no limit or balance in their Nubank account.

Testing and integration data

Payment installments

🚧
In case, the customer wants to purchase without installments it is still require for the merchant to send in the purchase API the `plan_option_id` related to `1 installment`

🚧
The /purchase V2 API will return a validation error when the `plan_option_id` is not provided.

Create an order refund

📘
Nupay always returns back a `refunding` status. It is important for the merchant to listen to DEUNA's webhooks to get notified on the final status of a refund.

📘
Nupay does support multiple partial refunds

🚧
It is mandatory to use the refunds V2 API from DEUNA

📘
If you don't send the parameter `"amount"` in the request body, the refund will be total.

Sandbox testing data

📘
The document number must be sent in the Order Creation request body (Step 1).

📘
The amount must be sent in the Order Creation request body (Step 1).

Error codes

Get started with NuPay

Requirements

Integration steps

1. Create anorder_token

📘webhook_urls/notify_order receives the DEUNA URL that sends the status of the customer’s consent when it receives an update.

2. Get order information

3. Update order

4. Get the customer’s consent

📘The field status will start with the value pending, and it will change when the customer concludes the consent flow on its Nubank App.

5- Check the consent status

6. Check payment methods

📘The parameter ?restrict_to_payment_methods=NUPAY in the endpoint URL is mandatory

🚧The installments API returns HTTP 200 OK and an empty response body if there are no payment options applicable to the user. This usually means that the customer has no limit or balance in their Nubank account.

Testing and integration data

Payment installments

🚧In case, the customer wants to purchase without installments it is still require for the merchant to send in the purchase API the plan_option_id related to 1 installment

🚧The /purchase V2 API will return a validation error when the plan_option_id is not provided.

Create an order refund

📘Nupay always returns back a refunding status. It is important for the merchant to listen to DEUNA's webhooks to get notified on the final status of a refund.

📘Nupay does support multiple partial refunds

🚧It is mandatory to use the refunds V2 API from DEUNA

📘If you don't send the parameter "amount" in the request body, the refund will be total.

Sandbox testing data

📘The document number must be sent in the Order Creation request body (Step 1).

📘The amount must be sent in the Order Creation request body (Step 1).

Error codes

1. Create an`order_token`

📘
`webhook_urls/notify_order` receives the DEUNA URL that sends the status of the customer’s consent when it receives an update.

📘
The field `status` will start with the value `pending`, and it will change when the customer concludes the consent flow on its Nubank App.

📘
The parameter `?restrict_to_payment_methods=NUPAY` in the endpoint URL is mandatory

🚧
The installments API returns HTTP 200 OK and an empty response body if there are no payment options applicable to the user. This usually means that the customer has no limit or balance in their Nubank account.

🚧
In case, the customer wants to purchase without installments it is still require for the merchant to send in the purchase API the `plan_option_id` related to `1 installment`

🚧
The /purchase V2 API will return a validation error when the `plan_option_id` is not provided.

📘
Nupay always returns back a `refunding` status. It is important for the merchant to listen to DEUNA's webhooks to get notified on the final status of a refund.

📘
Nupay does support multiple partial refunds

🚧
It is mandatory to use the refunds V2 API from DEUNA

📘
If you don't send the parameter `"amount"` in the request body, the refund will be total.

📘
The document number must be sent in the Order Creation request body (Step 1).

📘
The amount must be sent in the Order Creation request body (Step 1).