Documentación

PIX

Suggest Edits
NuPay payment method

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:

  1. A user selects PIX as the payment method on your website or app.
  2. Your website or app generates and displays a unique QR code associated with the transaction.
  3. The user accesses their banking app by scanning the QR code.
  4. User confirms the payment.
  5. 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:

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:

  1. The API returns the message user already exists.
  2. Request the OTP and login with the OTP to obtain a fresh user token.
  3. You can now use thetoken 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 payment
  • order.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 and order.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. and order.status = expired.
  • PIX Processed: When the PIX payment is successfully completed. The possible statuses are payment.status = processed and order.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 the order.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 the amount 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 = processed
    • order.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_refunded
      • order.status = succeeded
    • When the refund reaches the total value, the statuses are:
      • payment.status = refunded
      • order.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.

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 theauthorization_bank_transfer node's data and payment.data.statusfor 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 16 days ago