PIX

Get started with PIX
This page provides a comprehensive guide to successfully integrating PIX with DEUNA.
PIX is a Brazilian account-to-account (A2A) payment method offering secure and reliable real-time transactions in a seamless solution for your payment processing needs.
How it works
PIX is an instant payment method developed by the Central Bank of Brazil, operated by banks and digital wallets.
It has quickly become one of the most widely used payment methods in the country. PIX offers real-time transactions, 24/7, providing convenience and speed for both businesses and consumers.
PIX payment process
This is a standard process for a PIX Pay purchase in Deuna:
- A user selects PIX as the payment method on your website or app.
- Your website or app generates and displays a unique QR code associated with the transaction.
- The user accesses their banking app by scanning the QR code.
- User confirms the payment.
- The transaction is processed.
This seamless and efficient flow makes PIX an ideal solution for businesses seeking to offer fast, secure, and frictionless payment options.
Requirements
Environments:
- Sandbox: https://api.sandbox.deuna.io
- Production: https://api.deuna.io
Postman collection: PIX - Brazil | DEUNA | Postman API
DEUNA provides PIX-specific endpoints for managing users, payments, and refunds.
Integration steps
Now that the technical requirements are set, you can start the integration.
1. Create a user
Create a user with DEUNA to get an authorization token to perform the purchase later.
Make a request to the Create a User endpoint.
The API returns a user token
, which is required to follow the next steps.
OTP is recommended to get a new token each time a customer confirms the code through SMS or email. You can use an External authorization login to manage the user auth tokens by your own without requesting the OTP. Talk to your Sales Engineer for further guidance.
If the email does not exist, then a new user is created.
If the email used already exists:
- The API returns the message
user already exists
. - Request the OTP and login with the OTP to obtain a fresh user
token
. - You can now use the
token
for the next steps.
The user document can be CPF
or CNPJ
. Here are some examples for both scenarios:
CPF
:01354778911
CNPJ
:52672745000112
Creating a user is optional. In case you do not want to create users with DEUNA, then talk to your Sales Engineer for further steps.
2. Make a PIX purchase
Make a request to the V2 Purchase endpoint.
For PIX purchases, DEUNA generated the following parameters:
- QR Codes
- Token (Copia e Cola)
- Expiration date informed in the request
These parameters are found in the authorization_bank_transfer
node.
Once expired, the customer can not use PIX to pay anymore.
In the response:
payment.status
informs the status of the paymentorder.status
informs the status of the order.
3. Get purchase notifications
You will receive the following statuses notifications after processing a purchase:
- PIX Created: The statuses are
payment.status
andorder.status
=pending
.This indicates that the PIX has been generated and is awaiting payment from the customer. - PIX Expired: If the customer does not act on the QR code, then the order will expire, then the statuses are
payment.status
=denied
. andorder.status
=expired
. - PIX Processed: When the PIX payment is successfully completed. The possible statuses are
payment.status
= processed andorder.status
=succeeded
. - PIX Denied: This scenario occurs when the customer makes the PIX payment, but it has already expired in the Central Bank of Brazil. The possible statuses are
payment.status
=denied
and theorder.status
=pending
. In these cases, the order remains in a pending status, allowing the user to either complete the payment with a different payment method or retry the PIX transaction.
Refer to the PIX webhook examples for more information.
Request
{
"order_type": "DEUNA_CHECKOUT",
"payer_info": {
"email": "{{$randomEmail}}",
"save_user_info": false
},
"callback_urls": {
"on_success": "url",
"on_reject": "url",
"on_canceled": "url",
"on_failed": "url"
},
"payment_source": {
"method_type": "bank_transfer", //use bank_transfer for PIX payment method
"processor": "asaas_pix", //ask to your SE for the processor name
"method_type_specific_fields": {
"description": "Test PIX DEUNA",
"expiration_date": "2024-08-30 12:00:00" //always yyyy/MM/dd hh:mm:ss in Local Brazil Time. Add extra time for PIX expiration window
}
},
"order": {
"order_id": "{{$randomUUID}}",
"store_code": "all",
"currency": "BRL",
"items_total_amount": 2175,
"tax_amount": 0,
"sub_total": 2175,
"shipping_amount": 100,
"shipping_tax_amount": 0,
"total_tax_amount": 65,
"total_amount": 2240,
"expires_at":"2024-08-30T16:00:00.000Z", // 15m min 60days max //e.g. UTC 2024-08-30T16:00:00.000Z
"shipping_methods": [
{
"code": "12345JR",
"name": "Fast Delivery",
"cost": 250
}
],
"discounts": [],
"metadata": {
"key1": "identificador 1",
"key2": "identificador 2"
},
"items": [
{
"id": "{{$randomUUID}}",
"name": "Premium Baby Beef",
"description": "Premium Baby Beef Estância 92 Angus Resfriado",
"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": "Coração Da Alcatra",
"description": "Coração Da Alcatra (bombom) Estância 92 Resfriado",
"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": "204",
"first_name": "Joao",
"last_name": "Silva",
"email": "{{$randomEmail}}",
"address1": "Av. Pres. Juscelino Kubitschek",
"address2": "3ro. Andar",
"zipcode": "04543-011",
"city": "São Paulo",
"state_name": "SP",
"country_code": "BRA",
"identity_document": "52672745000112",
"identity_document_type": "CNPJ", //CPF or CNPJ E.g. 01354778911 or 52672745000112
"phone": "+5511985176644",
"lat": -22.943934,
"lng": -43.182984,
"additional_description": "confirmar",
"address_type": "casa"
},
"billing_address": {
"id": "179",
"first_name": "Joao",
"last_name": "Silva",
"email": "{{$randomEmail}}",
"address1": "Av. Pres. Juscelino Kubitschek",
"address2": "3ro. Andar",
"zipcode": "04543-011",
"city": "São Paulo",
"state_name": "SP",
"country_code": "BRA",
"identity_document": "52672745000112",
"identity_document_type": "CNPJ", //CPF or CNPJ E.g. 01354778911 or 52672745000112
"phone": "+5511985176644",
"lat": -23.555425,
"lng": -46.677048,
"address_type": "casa"
},
"user_instructions": "pesar antes de enviar",
"browser_details": {
"screen_height": 1000,
"screen_width": 2000
},
"webhook_urls": {
"notify_order": "https://webhook.site/5f19a36f-8931-4317-a850-fe102f93edbb",
"apply_coupon": "",
"remove_coupon": "",
"get_shipping_methods": "",
"update_shipping_method": "",
"Tarifa de envio": ""
}
}
}
Response
{
"order_type": "DEUNA_CHECKOUT",
"order_token": "410c9684-9046-42aa-8507-50779eaae223",
"order": {
"order_id": "717981f0-bade-4c29-9d2b-302763e655cb",
"store_code": "all",
"currency": "BRL",
"tax_amount": 0,
"display_tax_amount": "",
"shipping_amount": 100,
"display_shipping_amount": "BRL 1,00",
"items_total_amount": 2175,
"display_items_total_amount": "BRL 21,75",
"sub_total": 2175,
"display_sub_total": "BRL 21,75",
"total_amount": 2240,
"display_total_amount": "BRL 22,40",
"items": [
{
"id": "73a8886c-7dfb-4f49-a13c-d021adcf3e0f",
"name": "Premium Baby Beef",
"description": "Premium Baby Beef Estância 92 Angus Resfriado",
"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": "5f0ab6cc-1c90-432d-a805-2cc4032f7b08",
"name": "Coração Da Alcatra",
"description": "Coração Da Alcatra (bombom) Estância 92 Resfriado",
"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": 204,
"user_id": "",
"first_name": "Joao",
"last_name": "Silva",
"phone": "+5511985176644",
"identity_document": "52672745000112",
"lat": -22.943934,
"lng": -43.182984,
"address1": "Av. Pres. Juscelino Kubitschek",
"address2": "3ro. Andar",
"city": "São Paulo",
"zipcode": "04543-011",
"state_name": "SP",
"country_code": "BRA",
"additional_description": "confirmar",
"address_type": "casa",
"is_default": false,
"created_at": "0001-01-01T00:00:00Z",
"updated_at": "2024-08-26T15:25:43.635770405Z",
"identity_document_type": "CNPJ"
},
"shipping_options": null,
"user_instructions": "pesar antes de enviar",
"metadata": {
"key1": "identificador 1",
"key2": "identificador 2"
},
"status": "pending",
"payment": {
"data": {
"amount": {
"amount": 2240,
"currency": "BRL"
},
"metadata": {
"authorization_code": "",
"reference_transaction_id": ""
},
"from_card": {
"card_brand": "",
"first_six": "",
"last_four": "",
"bank_name": "",
"country_iso": ""
},
"updated_at": "2024-08-26 15:25:44.243843116 +0000 UTC",
"method_type": "bank_transfer",
"merchant": {
"store_code": "all",
"id": "c2273d9a-94c0-40a6-9b39-2556b4fadd1b"
},
"created_at": "2024-08-26 15:25:44.243356589 +0000 UTC",
"id": "717981f0-bade-4c29-9d2b-302763e655cb",
"processor": "asaas_pix",
"customer": {
"email": "[email protected]",
"id": "ffd0b445-4537-4316-8677-423deb770f24",
"first_name": "",
"last_name": ""
},
"status": "pending",
"reason": "",
"external_transaction_id": "JEANROLD00000000495401ASA",
"authorization_bank_transfer": {
"qr": "iVBORw0KGgoAAAANSUhEUgAAAZ8AAAGfCAIAAAAPgEjDAAAP3UlEQVR42u3aQXIjORADQP3/0943zIqFAqnEVR6rmywmHYH5/ImIvJiPJRARuomI0E1EhG4iInQTEaGbiNBNRIRuIiJ0ExGhm4gI3URE6CYidBMRoZuICN1EROgmIkI3ERG6iQjdREToJiJCNxERuomI0E1EhG4iQrf/87tSueKZ/+mL/ukhv3nBb17/4L89+L4lY3ZwQ7/ZhYPf+8Lpphvd6EY3utGNbnSjG93oRje60Y1udKMb3eh2k25bv3luZA8Ox5zIB4cyxkrsTMbOc2x/Y0NYcrrpRje60Y1udKMb3ehGN7rRjW50oxvd6EY3uv2MbgfruZLD0GnfjV1e7N/GasGDF8Pc5X3j6aYb3ehGN7rRjW50oxvd6EY3utGNbnSjG93oRresbnO9WEy3WD031xLGysqSL4plTka60Y1udKMb3ehGN7rRjW50oxvd6EY3utGNbnR7RbeDlVNJ7xmr9mIFXMm1UVKDxkblm2emG93oRje60Y1udKMb3ehGN7rRjW50oxvd6Ea3Vd1iv7lkgucGa2ugY831Vhl9RZE9J9QVp5tudKMb3ehGN7rRjW50oxvd6EY3utGNbnSj27u6xbo8n/rUp+FP72jq6eZTn/qUbnTzqU99Sje6+dSndKMb3XzqU7pV67aVWKm09UVznWlnlxfrWzvnKnb4Y93lmgx0oxvd6EY3utGNbnSjG93oRje60Y1udKMb3S7W7eAE5zqXlCNbdVXJGx0cpM4ub+5OveLPArrRjW50oxvd6EY3utGNbnSjG93oRje60Y1udMvqdqObcy1hTIq5Hz647Ae3+wo4SsrZb35VrgWmG93oRje60Y1udKMb3ehGN7rRjW50oxvd6PaObrFZ2ZqkuWnYmtEHmuu5Zd+6craeees+phvd6EY3utGNbnSjG93oRje60Y1udKMb3ej2M7qVFFKxiq2kYdyq2Do70znrY138XDkbq5vpRje60Y1udKMb3ehGN7rRjW50oxvd6EY3utEt28fFFnrrIWMt4dxTxRrVrdWI3amdcMxdonSjG93oRje60Y1udKMb3ehGN7rRjW50oxvdflW3ueXYmoa5/rHkeMeWrsT6gz+8tQudd3mJyHSjG93oRje60Y1udKMb3ehGN7rRjW50oxvdunWbG/et4ejcwoNjdxCdkrScqw7O5h4ydj/RjW50oxvd6EY3utGNbnSjG93oRje60Y1udPtV3UoaqNhBip2cEmQP1nOdteCcX7F/u/VFayeFbnSjG93oRje60Y1udKMb3ehGN7rRjW50o9s7upVsf2yTDpJUcghjjerW/sZu6y0a5u6nksqYbnSjG93oRje60Y1udKMb3ehGN7rRjW50o9uv6nbwqWLTX/JUseo2Vt6VELx11c1tSsk6041udKMb3ehGN7rRjW50oxvd6EY3utGNbnSj2+p5nmtFY01fZ/F30K+D4z73VFeWhvd303SjG93oRje60Y1udKMb3ehGN7rRjW50oxvd3tXtvdLwM5bOOrLkjebed640LOF7rsntvMzoRje60Y1udKMb3ehGN7rRjW50oxvd6EY3uj2k2zfTH+tMtzY4tnRbnVpJw1iyKXPFfaxB3hKKbnSjG93oRje60Y1udKMb3ehGN7rRjW50o9u7usXO5Na6x+b7CqBj63zFqeusMg/eMXMTSze60Y1udKMb3ehGN7rRjW50oxvd6EY3utGNbsOtWaxEi03D1rLHrqvPUg7OxlwNurWwB4/G1p8ydKMb3ehGN7rRjW50oxvd6EY3utGNbnSjG93e1e3GCjW2hbHzXKLb3A0Ua0WvsO89KOlGN7rRjW50oxvd6EY3utGNbnSjG93oRje6PaTb3EDfWKId3OCtx4gd4K1nLvnerfv4ijNIN7rRjW50oxvd6EY3utGNbnSjG93oRje60e1d3Q4e4LldmWvrYg3j8xM8t6FbPX7JaZ97qtjBoRvd6EY3utGNbnSjG93oRje60Y1udKMb3ej2kG4HX3jutHfWZCUruTaFlffEFXNV8vdHCWd0oxvd6EY3utGNbnSjG93oRje60Y1udKMb3d7VLbZnB/9tSfO19b5z+zt3bVxhQSejD5wjutGNbnSjG93oRje60Y1udKMb3ehGN7rRjW7dun06MvfMscWJLWxndVuyOHO7HztHsevq/c6UbnSjG93oRje60Y1udKMb3ehGN7rRjW50o1u6My35oticbcExV1eVHNG5lbziTp1rRec609gtQje60Y1udKMb3ehGN7rRjW50oxvd6EY3utHtId3eqwVjmsfe9+AE3/iCc69f8kZb9q0dHLrRjW50oxvd6EY3utGNbnSjG93oRje60Y1uN+nW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",
"token": "00020126760014br.gov.bcb.pix013689bd5e4e-2393-4bd1-b973-2010c3169ea20214Test PIX DEUNA520400005303986540522.405802BR5911Jean Roldan6014Rio de Janeiro62290525JEANROLD00000000495401ASA6304507E",
"expiration_date": "2024-08-30 12:00:00"
},
"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": 179,
"user_id": "",
"first_name": "Joao",
"last_name": "Silva",
"phone": "+5511985176644",
"identity_document": "52672745000112",
"lat": -23.555425,
"lng": -46.677048,
"address1": "Av. Pres. Juscelino Kubitschek",
"address2": "3ro. Andar",
"city": "São Paulo",
"zipcode": "04543-011",
"state_name": "SP",
"country_code": "BRA",
"additional_description": "",
"address_type": "casa",
"is_default": false,
"created_at": "0001-01-01T00:00:00Z",
"updated_at": "2024-08-26T15:25:43.635771056Z",
"email": "[email protected]",
"identity_document_type": "CNPJ"
},
"payment_link": "",
"display_shipping_tax_amount": "BRL 0,00",
"display_total_tax_amount": "BRL 0,65",
"shipping_tax_amount": 0,
"total_tax_amount": 65,
"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": null,
"display_total_interest_amount": "",
"payment_method": "",
"token": "",
"statement_descriptor": ""
}
Manage PIX orders
You can manage your PIX orders, including refunds and order status.
Refund a PIX payment
When processing a refund, you can choose between a full refund, a partial refund, or a multiple partial refund:
- Full refund: A refund that is equal to the amount of the original transaction.
- Partial refund: A refund of a specific portion of the original amount, that is lesser than the amount of the original transaction
- Multiple partial refund: A set of more than one refund for the same transaction, that can be equal or lesser than the total amount of the original transaction.
Refer to V2 Purchase for further details.
Request
{
"reason": "",
"amount": 2240
}
Response
{
"data": {
"refund_id": "961bb161-5340-4d36-a08d-7d767458e0af",
"status": "refunding",
"refund_amount": {
"amount": "2240",
"currency": "BRL"
},
"order": null,
"refunds": [
{
"refund_id": "961bb161-5340-4d36-a08d-7d767458e0af",
"refund_amount": {
"amount": "2240",
"currency": "BRL"
},
"refunded_on": "2024-08-17T00:05:05Z",
"status": "refunding",
"external_transaction_id": "c0884fd3-8c7f-45eb-b4f5-caf89ba44d4b"
}
]
},
"error": null
}
Multiple partial refunds, with the corresponding refund_id
for each requested refund
{
"data": {
"invoice": {
"token": "6c2ccbe0-ec31-40d0-b21d-45e2a33f604a",
"order_id": "e54d8720-d4e6-4922-ad45-6cc1c9724fd8",
"amount": 5025
},
"refund_id": "bdc2f63e-230c-46f6-9c9b-2ba2b5817cc9",
"status": "refunding",
"external_transaction_id": "50722010-fd12-4718-8383-30aefa25f3ad",
"refund_amount": {
"amount": 4025,
"currency": "BRL"
},
"refunds": [
{
"refund_id": "8e41fe00-dd9f-4505-906d-7b1dc9a4016c",
"status": "refunding",
"external_transaction_id": "7db40b18-0926-4d31-9c84-43df7c55c56f",
"refund_amount": {
"amount": 1000,
"currency": "BRL"
},
"refunded_on": "2025-01-06T21:32:13Z"
},
{
"refund_id": "bdc2f63e-230c-46f6-9c9b-2ba2b5817cc9",
"status": "refunding",
"external_transaction_id": "50722010-fd12-4718-8383-30aefa25f3ad",
"refund_amount": {
"amount": 4025,
"currency": "BRL"
},
"refunded_on": "2025-01-06T21:32:52Z"
}
],
"request": {
"raw_request": {
"description": "refund",
"value": 40.25
},
"raw_response": {
"addressKey": null,
"addressKeyType": null,
"canBeCanceled": false,
"canBeRefunded": false,
"changeValue": null,
"chargedFeeValue": 0,
"conciliationIdentifier": null,
"dateCreated": "2025-01-06 18:32:51",
"description": "refund",
"effectiveDate": "2025-01-06 18:32:51",
"endToEndIdentifier": null,
"externalAccount": {
"account": "000000",
"accountDigit": "0",
"accountType": "PAYMENT_ACCOUNT",
"addressKey": "89bd5e4e-2393-4bd1-b973-2010c3169ea2",
"addressKeyType": "EVP",
"agency": "0000",
"cpfCnpj": "***.399.399-**",
"ispb": 19540550,
"ispbName": "ASAAS GESTÃO FINANCEIRA INSTITUIÇÃO DE PAGAMENTO S.A.",
"name": "Jean Roldan"
},
"externalReference": null,
"finality": null,
"id": "50722010-fd12-4718-8383-30aefa25f3ad",
"originType": null,
"originalTransaction": {
"effectiveDate": "2025-01-06 18:30:34",
"endToEndIdentifier": "5e71aeec7171974a7a2aa51adcca1a28",
"id": "933f092e-d511-426c-be39-c6609f8a5a9b",
"value": 50.25
},
"payment": null,
"qrCode": null,
"refundDisabledReason": "O tipo desta transação não permite que ela seja estornada.",
"refundedValue": 0,
"refusalReason": null,
"scheduledDate": null,
"status": "AWAITING_REQUEST",
"transactionReceiptUrl": null,
"transferId": "37d3cd1f-1f2b-453a-ad02-7d034d65fabc",
"type": "CREDIT_REFUND",
"value": 40.25
}
}
}
}
If the parameter
amount
is not sent in the request, then the refund is total. If theamount
is less than the total order amount, then the refund is set as a partial refund.
Get refund notifications
You receive the following notifications when a refund has been requested:
- Refund Denied: If the refund fails, then the possible statuses are:
payment.status
= processedorder.status
= succeeded
- Refund Processed: If the refund is successfully processed, then the expected status is
payment.status
. - Multiple partial refunds:
- If at least one partial refund has been successfully processed but the total value has not been reached, then the notification for subsequent refunds is:
payment.status
= partial_refundedorder.status
= succeeded
- When the refund reaches the total value, the statuses are:
payment.status
= refundedorder.status
= refund
- In these cases, send the
refund_id
along with an array of refunds. Here you can check the status and additional information about the refund.
- If at least one partial refund has been successfully processed but the total value has not been reached, then the notification for subsequent refunds is:
Retrieve order information
You can retrieve the order's information to check the status of the order.
Make a request to the Get Order endpoint.
It is recommended to use the
authorization_bank_transfer
node's data andpayment.data.status
for monitoring purposes.
Response
"status": "pending",
"payment": {
"data": {
.
.
.
},
"status": "pending",
"reason": "",
"external_transaction_id": "JEANROLD00000000495401ASA",
"authorization_bank_transfer": {
"qr": "iVBORw0KGgoAAAANSUhEUgAAAZ8AAAGfCAIAAAAPgEjDAAAP3UlEQVR42u3aQXIjORADQP3/0943zIqFAqnEVR6rmywmHYH5/ImIvJiPJRARuomI0E1EhG4iInQTEaGbiNBNRIRuIiJ0ExGhm4gI3URE6CYidBMRoZuICN1EROgmIkI3ERG6iQjdREToJiJCNxERuomI0E1EhG4iQrf/87tSueKZ/+mL/ukhv3nBb17/4L89+L4lY3ZwQ7/ZhYPf+8Lpphvd6EY3utGNbnSjG93oRje60Y1udKMb3eh2k25bv3luZA8Ox5zIB4cyxkrsTMbOc2x/Y0NYcrrpRje60Y1udKMb3ehGN7rRjW50oxvd6EY3uv2MbgfruZLD0GnfjV1e7N/GasGDF8Pc5X3j6aYb3ehGN7rRjW50oxvd6EY3utGNbnSjG93oRresbnO9WEy3WD031xLGysqSL4plTka60Y1udKMb3ehGN7rRjW50oxvd6EY3utGNbnR7RbeDlVNJ7xmr9mIFXMm1UVKDxkblm2emG93oRje60Y1udKMb3ehGN7rRjW50oxvd6Ea3Vd1iv7lkgucGa2ugY831Vhl9RZE9J9QVp5tudKMb3ehGN7rRjW50oxvd6EY3utGNbnSj27u6xbo8n/rUp+FP72jq6eZTn/qUbnTzqU99Sje6+dSndKMb3XzqU7pV67aVWKm09UVznWlnlxfrWzvnKnb4Y93lmgx0oxvd6EY3utGNbnSjG93oRje60Y1udKMb3S7W7eAE5zqXlCNbdVXJGx0cpM4ub+5OveLPArrRjW50oxvd6EY3utGNbnSjG93oRje60Y1udMvqdqObcy1hTIq5Hz647Ae3+wo4SsrZb35VrgWmG93oRje60Y1udKMb3ehGN7rRjW50oxvd6PaObrFZ2ZqkuWnYmtEHmuu5Zd+6craeees+phvd6EY3utGNbnSjG93oRje60Y1udKMb3ej2M7qVFFKxiq2kYdyq2Do70znrY138XDkbq5vpRje60Y1udKMb3ehGN7rRjW50oxvd6EY3utEt28fFFnrrIWMt4dxTxRrVrdWI3amdcMxdonSjG93oRje60Y1udKMb3ehGN7rRjW50oxvdflW3ueXYmoa5/rHkeMeWrsT6gz+8tQudd3mJyHSjG93oRje60Y1udKMb3ehGN7rRjW50oxvdunWbG/et4ejcwoNjdxCdkrScqw7O5h4ydj/RjW50oxvd6EY3utGNbnSjG93oRje60Y1udPtV3UoaqNhBip2cEmQP1nOdteCcX7F/u/VFayeFbnSjG93oRje60Y1udKMb3ehGN7rRjW50o9s7upVsf2yTDpJUcghjjerW/sZu6y0a5u6nksqYbnSjG93oRje60Y1udKMb3ehGN7rRjW50o9uv6nbwqWLTX/JUseo2Vt6VELx11c1tSsk6041udKMb3ehGN7rRjW50oxvd6EY3utGNbnSj2+p5nmtFY01fZ/F30K+D4z73VFeWhvd303SjG93oRje60Y1udKMb3ehGN7rRjW50oxvd3tXtvdLwM5bOOrLkjebed640LOF7rsntvMzoRje60Y1udKMb3ehGN7rRjW50oxvd6EY3uj2k2zfTH+tMtzY4tnRbnVpJw1iyKXPFfaxB3hKKbnSjG93oRje60Y1udKMb3ehGN7rRjW50o9u7usXO5Na6x+b7CqBj63zFqeusMg/eMXMTSze60Y1udKMb3ehGN7rRjW50oxvd6EY3utGNbsOtWaxEi03D1rLHrqvPUg7OxlwNurWwB4/G1p8ydKMb3ehGN7rRjW50oxvd6EY3utGNbnSjG93e1e3GCjW2hbHzXKLb3A0Ua0WvsO89KOlGN7rRjW50oxvd6EY3utGNbnSjG93oRje6PaTb3EDfWKId3OCtx4gd4K1nLvnerfv4ijNIN7rRjW50oxvd6EY3utGNbnSjG93oRje60e1d3Q4e4LldmWvrYg3j8xM8t6FbPX7JaZ97qtjBoRvd6EY3utGNbnSjG93oRje60Y1udKMb3ej2kG4HX3jutHfWZCUruTaFlffEFXNV8vdHCWd0oxvd6EY3utGNbnSjG93oRje60Y1udKMb3d7VLbZnB/9tSfO19b5z+zt3bVxhQSejD5wjutGNbnSjG93oRje60Y1udKMb3ehGN7rRjW7dun06MvfMscWJLWxndVuyOHO7HztHsevq/c6UbnSjG93oRje60Y1udKMb3ehGN7rRjW50o1u6My35oticbcExV1eVHNG5lbziTp1rRec609gtQje60Y1udKMb3ehGN7rRjW50oxvd6EY3utHtId3eqwVjmsfe9+AE3/iCc69f8kZb9q0dHLrRjW50oxvd6EY3utGNbnSjG93oRje60Y1uN+nW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",
"token": "00020126760014br.gov.bcb.pix013689bd5e4e-2393-4bd1-b973-2010c3169ea20214Test PIX DEUNA520400005303986540522.405802BR5911Jean Roldan6014Rio de Janeiro62290525JEANROLD00000000495401ASA6304507E",
"expiration_date": "2024-08-30 12:00:00"
},
Updated 10 days ago