Integración: NuPay

Integration Steps

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

1 - Create Order

Create an order with DEUNA. This API will return back a DEUNA’s order_token which will be required to follow the next steps.

👍
The object webhook_urls/notify_order will receive the URL that DEUNA will send 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- 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- 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- Using 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- 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": ""
      }
    }
  ]
}

7- Creating a payment with or without 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": ""
  }
}

9- Creating a 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
}

10- 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).

11- 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.

Integración: NuPay

Integration Steps

1 - Create Order

👍
The object `webhook_urls/notify_order` will receive the URL that DEUNA will send the status of the customer’s consent when it receives an update.

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

3- It is possible to update an order using the following endpoint

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- Using the GET endpoint to check the Consent current status

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

📘
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.

7- Creating a payment with or without 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.

9- Creating a 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.

10- 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).

11- Error Codes

Integration Steps

1 - Create Order

👍The object webhook_urls/notify_order will receive the URL that DEUNA will send the status of the customer’s consent when it receives an update.

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

3- It is possible to update an order using the following endpoint

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- Using the GET endpoint to check the Consent current status

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

📘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.

7- Creating a payment with or without 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.

9- Creating a 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.

10- 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).

11- Error Codes

👍
The object `webhook_urls/notify_order` will receive the URL that DEUNA will send 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).