Asynchronous refunds

What are asynchronous refunds?

An asynchronous refund means that when making a request to a processor via DEUNA, it first responds that it has started the process and the confirmation or rejection may arrive a few seconds later.

📘

Sending a request does not mean that a refund has been successfully processed.

DEUNA returns intermediate states such as:

  • refunding: Full refund
  • partial_refunding Partial refund

When confirmation is received from the processor, DEUNA updates the status and emits a webhook with the final status:

  • refunded: Refund completed
  • partial_refunded: Partial refund completed
  • denied: Refund denied

📘

Refund updates are asynchronous.

The processors that support intermediate states for asynchronous refunds are:

  • Kushki
  • dLocal
  • Cybersource
  • NuPay (APM)

DEUNA Webhook Configuration

All this order status information will be transmitted via Webhooks to our merchants, as long as a value has been placed in webhook_urls.notify_order when creating an order.

📘

For more information check Order Tokenization.

In case you are using /purchase V2 the field order.webhook_urls.notify_order can be sent directly in the request payload.

📘

Use refunds V2 for proper functioning of the refund flow.

Flow Diagrams

Refund V2 with intermediate status

Refund V2 with final status

Examples

Webhook Response

The DEUNA webhook responds to the Merchant with the order result, where you can verify the transaction status in the order.payment.data.status property within the following JSON:

{
    "order": {
        "order_id": "checkout_qsr_1723230422",
        "store_code": "all",
        "currency": "MXN",
        "tax_amount": 0,
        "display_tax_amount": "",
        "shipping_amount": 0,
        "display_shipping_amount": "MXN 0.00",
        "items_total_amount": 1900,
        "display_items_total_amount": "MXN 19.00",
        "sub_total": 1900,
        "display_sub_total": "MXN 19.00",
        "total_amount": 1900,
        "display_total_amount": "MXN 19.00",
        "items": [
            {
                "id": "789456123",
                "name": "Polo Shirt",
                "description": "Lorem ipsum dolor sit amet, consectetur adipiscing elit. Aenean euismod bibendum laoreet.",
                "options": "string option",
                "total_amount": {
                    "amount": 1900,
                    "original_amount": 0,
                    "display_amount": "MXN 19.00",
                    "display_original_amount": "MXN 0.00",
                    "currency": "MXN",
                    "currency_symbol": "$",
                    "total_discount": 0,
                    "display_total_discount": "MXN 0.00"
                },
                "unit_price": {
                    "amount": 1900,
                    "display_amount": "MXN 19.00",
                    "currency": "MXN",
                    "currency_symbol": "$"
                },
                "tax_amount": {
                    "amount": 0,
                    "display_amount": "MXN 0.00",
                    "currency": "MXN",
                    "currency_symbol": "$"
                },
                "quantity": 1,
                "uom": "Piece",
                "upc": "string",
                "sku": "HEADPH001",
                "isbn": "123-456-789",
                "brand": "Generic Brand",
                "manufacturer": "Generic Manufacturer",
                "category": "Electronics",
                "color": "Black",
                "size": "",
                "weight": {
                    "weight": 1,
                    "unit": "kg"
                },
                "image_url": "https://cdn.stg.deuna.io/explore-deuna/assets/shirt.png",
                "details_url": "",
                "type": "Electronics",
                "taxable": true,
                "discounts": [],
                "included_in_subscription": false,
                "subscription_id": "00000000-0000-0000-0000-000000000000",
                "item_details": []
            }
        ],
        "discounts": [],
        "shipping_address": {
            "id": 0,
            "user_id": "",
            "first_name": "John",
            "last_name": "Doe",
            "phone": "99999999999",
            "identity_document": "XAXX010101000",
            "lat": -41.743,
            "lng": 11.987,
            "address1": "José Luis Lagrange 456, Colonia Polanco",
            "address2": "José Luis Lagrange 456, Colonia Polanco",
            "city": "Ciudad de México",
            "zipcode": "11510",
            "state_name": "Cundinamarca",
            "country_code": "MX",
            "additional_description": "",
            "address_type": "home",
            "is_default": false,
            "created_at": "2024-08-09T19:07:10.577163712Z",
            "updated_at": "2024-08-09T19:07:10.577163825Z",
            "identity_document_type": ""
        },
        "shipping_options": null,
        "user_instructions": "",
        "metadata": {},
        "status": "succeeded",
        "payment": {
            "data": {
                "amount": {
                    "amount": 1900,
                    "currency": "COP"
                },
                "metadata": {
                    "authorization_code": "000000",
                    "site_domain": null
                },
                "from_card": {
                    "card_brand": "visa",
                    "first_six": "411111",
                    "last_four": "1111",
                    "installment": {
                        "installments": 1,
                        "plan_id": "",
                        "plan_option_id": "",
                        "installment_type": "",
                        "installment_rate": 0,
                        "installment_amount": 0
                    },
                    "bank_name": "JPMORGAN CHASE BANK, N.A.",
                    "country_iso": "BR"
                },
                "updated_at": "2024-08-09 19:07:11.201482143 +0000 UTC",
                "method_type": "credit_card",
                "merchant": {
                    "store_code": "all",
                    "id": "eb3e7d0e-389e-4685-bcfe-ccf26f613519"
                },
                "created_at": "2024-08-09 19:07:11.200209553 +0000 UTC",
                "id": "checkout_qsr_1723230422",
                "processor": "kushki",
                "customer": {
                    "email": "[email protected]",
                    "id": "cb7c2531-e99a-489c-8f8f-45e57e4ce5fb",
                    "first_name": "",
                    "last_name": ""
                },
                "status": "refunded",
                "reason": "",
                "external_transaction_id": "197950573098739835",
                "merchant_payment_processor_name": "",
                "authorization_code": "000000",
                "installment_interest_calculations": null
            }
        },
        "gift_card": [],
        "redirect_url": "",
        "webhook_urls": null,
        "total_discount": 0,
        "display_total_discount": "MXN 0.00",
        "shipping": null,
        "cash_change": 0,
        "shipping_method": null,
        "shipping_methods": [],
        "timezone": "",
        "scheduled_at": "",
        "billing_address": {
            "id": 1896,
            "user_id": "cb7c2531-e99a-489c-8f8f-45e57e4ce5fb",
            "first_name": "Jhon",
            "last_name": "Doe",
            "phone": "+5999999999",
            "identity_document": "1234567891",
            "lat": -0.10003200173377991,
            "lng": -78.46955871582031,
            "address1": "Av. Eloy Alfaro 14, Quito 170515, Ecuador",
            "address2": "Av. Eloy Alfaro 14, Quito 170515, Ecuador",
            "city": "Quito",
            "zipcode": "170515",
            "state_name": "Quito",
            "country_code": "ECU",
            "additional_description": "No tocar timbre",
            "address_type": "home",
            "is_default": false,
            "created_at": "2024-08-09T19:07:10.577164403Z",
            "updated_at": "2024-08-09T19:07:10.577164531Z",
            "email": "",
            "identity_document_type": "DNI"
        },
        "payment_link": "",
        "display_shipping_tax_amount": "MXN 0.00",
        "display_total_tax_amount": "MXN 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.28712958,
                "processor": "SIFT",
                "risk_level": "",
                "status": "automatic_decision",
                "type": "",
                "fraud_decision": "",
                "details": "",
                "processor_response": ""
            }
        },
        "display_total_interest_amount": "",
        "payment_method": "",
        "token": "",
        "statement_descriptor": ""
    },
    "custom_fields": []
}

Refund V2 Response

In this example we can see that in the data.status property we have the refund result as refunding but it could also be refunded depending on the cases mentioned above.

{
    "data": {
        "refund_id": "fffda815-bde4-47be-b698-f94ad41c270f",
        "status": "refunding",
        "refund_amount": {
            "amount": "1900",
            "currency": "COP"
        },
        "order": null,
        "refunds": [
            {
                "refund_id": "fffda815-bde4-47be-b698-f94ad41c270f",
                "refund_amount": {
                    "amount": "1900",
                    "currency": "COP"
                },
                "refunded_on": "2024-08-09T19:18:31Z",
                "status": "refunding",
                "external_transaction_id": "661723231110709722"
            }
        ]
    },
    "error": null
}

The following table describes the properties returned by our Refund V2 endpoint:

Property NameData typeDescription
data.refund_idStringRefund ID in UUID format.
data.statusStringRefund Status.
data.refund_amount.amountStringRefund Amount.
data.refund_amount.currencyStringRefund Currency.
data.orderOrderOrder Object.
data.refundsListList of Refunds in the Order.
data.refunds.refund_idStringRefund ID in UUID format.
data.refunds.refund_amount.amountStringRefund Amount.
data.refunds.refund_amount.currencyStringRefund Currency.
data.refunds.refunded_onDateRefund Date in ISO 8601 format.
data.refunds.statusStringRefund Status.
data.refunds.external_transaction_idStringRefund ID provided by the PSP.
errorObjectError object.

Also in our GetOrder endpoint we return in a property called refunds all the refunds that have been made.

{
    "token": "6a5827ee-2d0c-440f-bb72-cd203fcf7f47",
    "order_type": "DEUNA_NOW",
    "order": {
        "order_id": "checkout_qsr_1723231005",
        "store_code": "all",
        "currency": "MXN",
        "tax_amount": 0,
        "display_tax_amount": "MXN 0.00",
        "shipping_amount": 0,
        "display_shipping_amount": "MXN 0.00",
        "items_total_amount": 1900,
        "display_items_total_amount": "MXN 19.00",
        "sub_total": 1900,
        "display_sub_total": "MXN 19.00",
        "total_amount": 1900,
        "display_total_amount": "MXN 19.00",
        "items": [
            {
                "id": "789456123",
                "name": "Polo Shirt",
                "description": "Lorem ipsum dolor sit amet, consectetur adipiscing elit. Aenean euismod bibendum laoreet.",
                "options": "string option",
                "total_amount": {
                    "amount": 1900,
                    "original_amount": 0,
                    "display_amount": "MXN 19.00",
                    "display_original_amount": "MXN 0.00",
                    "currency": "MXN",
                    "currency_symbol": "$",
                    "total_discount": 0,
                    "display_total_discount": "MXN 0.00"
                },
                "unit_price": {
                    "amount": 1900,
                    "display_amount": "MXN 19.00",
                    "currency": "MXN",
                    "currency_symbol": "$"
                },
                "tax_amount": {
                    "amount": 0,
                    "display_amount": "MXN 0.00",
                    "currency": "MXN",
                    "currency_symbol": "$"
                },
                "quantity": 1,
                "uom": "Piece",
                "upc": "string",
                "sku": "HEADPH001",
                "isbn": "123-456-789",
                "brand": "Generic Brand",
                "manufacturer": "Generic Manufacturer",
                "category": "Electronics",
                "color": "Black",
                "size": "",
                "weight": {
                    "weight": 1,
                    "unit": "kg"
                },
                "image_url": "https://cdn.stg.deuna.io/explore-deuna/assets/shirt.png",
                "details_url": "",
                "type": "Electronics",
                "taxable": true,
                "discounts": [],
                "included_in_subscription": false,
                "subscription_id": "00000000-0000-0000-0000-000000000000",
                "item_details": []
            }
        ],
        "discounts": [],
        "shipping_address": {
            "id": 0,
            "user_id": "",
            "first_name": "John",
            "last_name": "Doe",
            "phone": "99999999999",
            "identity_document": "XAXX010101000",
            "lat": -41.743,
            "lng": 11.987,
            "address1": "José Luis Lagrange 456, Colonia Polanco",
            "address2": "José Luis Lagrange 456, Colonia Polanco",
            "city": "Ciudad de México",
            "zipcode": "11510",
            "state_name": "Cundinamarca",
            "country_code": "MX",
            "additional_description": "",
            "address_type": "home",
            "is_default": false,
            "created_at": "2024-08-09T19:16:57.821466737Z",
            "updated_at": "2024-08-09T19:16:57.821466842Z",
            "identity_document_type": ""
        },
        "shipping_options": {
            "type": "delivery",
            "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": {},
        "status": "refund",
        "payment": {
            "data": {
                "amount": {
                    "amount": 1900,
                    "currency": "COP"
                },
                "metadata": {
                    "authorization_code": "000000",
                    "site_domain": null,
                    "status_reason": ""
                },
                "from_card": {
                    "card_brand": "visa",
                    "first_six": "411111",
                    "last_four": "1111",
                    "installment": {
                        "installments": 1,
                        "plan_id": "",
                        "plan_option_id": "",
                        "installment_type": "",
                        "installment_rate": 0,
                        "installment_amount": 0
                    },
                    "bank_name": "JPMORGAN CHASE BANK, N.A.",
                    "country_iso": "BR"
                },
                "updated_at": "2024-08-09 19:18:33.400481096 +0000 UTC",
                "method_type": "credit_card",
                "merchant": {
                    "store_code": "all",
                    "id": "eb3e7d0e-389e-4685-bcfe-ccf26f613519"
                },
                "created_at": "2024-08-09 19:16:58.382945 +0000 UTC",
                "id": "checkout_qsr_1723231005",
                "processor": "kushki",
                "customer": {
                    "email": "[email protected]",
                    "id": "cb7c2531-e99a-489c-8f8f-45e57e4ce5fb",
                    "first_name": "",
                    "last_name": ""
                },
                "status": "refunded",
                "reason": "",
                "external_transaction_id": "591961123539970140",
                "authorization_3ds": {
                    "version": "",
                    "url_challenge": ""
                },
                "merchant_payment_processor_name": "kushki",
                "processor_error": {
                    "code": "",
                    "message": ""
                },
                "authorization_code": "000000",
                "installment_interest_calculations": {
                    "installment_type": "",
                    "installment_rate": 0,
                    "is_mci_payment": false,
                    "calculated_interest": 0,
                    "items_subtotal_amount": 0
                },
                "routing_strategy": ""
            }
        },
        "gift_card": [],
        "redirect_url": "",
        "webhook_urls": null,
        "total_discount": 0,
        "display_total_discount": "MXN 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": 1896,
            "user_id": "cb7c2531-e99a-489c-8f8f-45e57e4ce5fb",
            "first_name": "Jhon",
            "last_name": "Doe",
            "phone": "+5999999999",
            "identity_document": "1234567891",
            "lat": -0.10003200173377991,
            "lng": -78.46955871582031,
            "address1": "Av. Eloy Alfaro 14, Quito 170515, Ecuador",
            "address2": "Av. Eloy Alfaro 14, Quito 170515, Ecuador",
            "city": "Quito",
            "zipcode": "170515",
            "state_name": "Quito",
            "country_code": "ECU",
            "additional_description": "No tocar timbre",
            "address_type": "home",
            "is_default": false,
            "created_at": "2024-08-09T19:16:57.82146762Z",
            "updated_at": "2024-08-09T19:16:57.821467755Z",
            "email": "",
            "identity_document_type": "DNI"
        },
        "payment_link": "",
        "display_shipping_tax_amount": "MXN 0.00",
        "display_total_tax_amount": "MXN 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-08-09 19:16:45.517043918 +0000 UTC",
        "updated_at": "",
        "payer_info": null,
        "discount_amount": 0,
        "shipping_discount_amount": 0,
        "device_fingerprint": "",
        "expired_at": "",
        "version": "0",
        "fraud": {
            "analysis": {
                "score": 0.2977461,
                "processor": "SIFT",
                "risk_level": "",
                "status": "automatic_decision",
                "type": "",
                "fraud_decision": "",
                "details": "",
                "processor_response": ""
            }
        },
        "total_interest_amount": 0,
        "display_total_interest_amount": "MXN 0.00",
        "payment_method": "",
        "token": "",
        "statement_descriptor": ""
    },
    "custom_fields": [],
    "checkout_modules": [],
    "refunds": [
        {
            "refund_id": "fffda815-bde4-47be-b698-f94ad41c270f",
            "refund_amount": {
                "amount": "1900",
                "currency": "COP"
            },
            "refunded_on": "2024-08-09T19:18:31Z",
            "status": "refunded",
            "external_transaction_id": "661723231110709722"
        }
    ]
}