PIX Asaas | DEUNA Docs

On this page

Get started with PIX
How it works
Requirements
Integration steps
Manage PIX orders

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.

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 thetoken for the next steps.

The user document can be CPF or CNPJ. Here are some examples for both scenarios:

CPF: 01354778911
CNPJ: 52672745000112

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.

Request

JSON

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

JSON

{
    "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": "Antwan61@gmail.com",
                    "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": "Gerry_Kautzer42@hotmail.com",
            "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.

Request

JSON

{
    "reason": "",
    "amount": 2240
}

Response

JSON

{
    "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 correspondingrefund_id for each requested refund

JSON

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

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.

Response

JSON

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

In this section

PIX webhooks