NuPay
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:
Integration steps
Now that the technical requirements are set, you can start the integration.
1. Create an order_token
order_tokenTo 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.
webhook_urls/notify_orderreceives the DEUNA URL that sends the status of the customer’s consent when it receives an update.
Request
{
"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
{
"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
Make a request to the Get Order endpoint.
Use this token for the next steps.
Response
{
"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. Get customer consent
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
{
"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
statuswill start with the valuepending, and it will change when the customer concludes the consent flow on its Nubank app.
To get the current status, you can.
- Make a GET request to see the new status.
- Receive the status update through webhooks.
4. Get consent status
DEUNA sends the status update through a webhook event.
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}}'
Response
{
"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 parameter
?restrict_to_payment_methods=NUPAYin the endpoint URL is mandatory
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"
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
{
"@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": ""
}
}
]
}
6. Make a V1 purchase
Make a request to the V1 Purchase endpoint and process the payment.
Response
{
"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": "[email protected]",
"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.
If the
plan_option_idis not provided, then the V2 Purchase API returns a validation error. This only applies to NuPay.
Request
{
"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 you must send the plan_option_id for 1x installment, for debit or credit.
}
}
}
Response
{
"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": ""
}
}
Refunds
For refunds, use the V2 Refund endpoint.
NuPay always returns a refunding status and supports multiple partial refunds.
Listen to DEUNA's webhooks to get notified of the final status of a refund.
If you don't send the parameter
"amount"in the request body, then the refund will be total.
Request
{
"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
{
"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:
The document number must be sent in the Order Creation request body.
| CPF number | Description |
|---|---|
| 58188896454 | Authorization accepted by the customer for any type of charge. |
| 31457612500 | Authorization denied by the customer. |
Simulating installment responses:
The amount must be sent in the Order Creation request body.
| 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. |
Updated 17 days ago