Asynchronous capture, refund, and void
Handle capture, refund, and void operations whose final processor result arrives asynchronously.
On this page
An asynchronous payment operation returns after DEUNA accepts or queues the operation, before the payment processor has confirmed the final result. Capture, refund, and void can use this processing model when it is supported and enabled for the processor connection.
Public API operations#
The following merchant-facing operations are exposed through the DEUNA API Gateway and listed in the endpoint catalog:
| Operation | Endpoint | Typical intermediate status |
|---|---|---|
| Capture | POST /merchants/orders/{order_token}/capture-async | capturing or partial_capturing |
| Refund | POST /merchants/orders/{order_token}/refund-async | refunding or partial_refunding |
| Void | POST /merchants/orders/{order_token}/void-async | voiding |
Provider support and execution mode are configured per connection. Use the API Gateway routes in the table as the public integration contract.
Intermediate and final statuses#
DEUNA can return these intermediate statuses while the processor result is pending:
capturingorpartial_capturing: Capture is pending.refundingorpartial_refunding: Refund is pending.voiding: Void is pending.
When confirmation arrives, DEUNA updates the payment. Depending on the operation, the result can be:
capturedorpartial_captured: Capture completed.refundedorpartial_refunded: Refund completed.voided: Void completed.authorized,processed, ordenied: The operation failed, was reversed, or restored the payment to the processor-confirmed state.
Asynchronous refunds#
The remainder of this guide describes the refund-specific asynchronous result.
Supported processors
The processors that support intermediate states for asynchronous refunds are:
- Kushki
- dLocal
- Cybersource
- NuPay (APM)
Confirm the asynchronous result#
Retrieve the original order or payment after DEUNA processes the provider update. See DEUNA Webhooks for the supported asynchronous payment-status processing model.
Refund V2 with intermediate status#
Sequence diagram
Refund V2 with final status
Sequence diagram
Retrieved order result#
Verify the transaction status in the retrieved order's order.payment.data.status property within the following JSON:
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": "Polo shirt for retail.",
"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": "Moises",
"last_name": "Caicedo",
"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": "jhondoe@deuna.com",
"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.
JSON
{
"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 Name | Data type | Description |
|---|---|---|
| data.refund_id | String | Refund ID in UUID format. |
| data.status | String | Refund Status. |
| data.refund_amount.amount | String | Refund Amount. |
| data.refund_amount.currency | String | Refund Currency. |
| data.order | Order | Order Object. |
| data.refunds | List | List of Refunds in the Order. |
| data.refunds.refund_id | String | Refund ID in UUID format. |
| data.refunds.refund_amount.amount | String | Refund Amount. |
| data.refunds.refund_amount.currency | String | Refund Currency. |
| data.refunds.refunded_on | Date | Refund Date in ISO 8601 format. |
| data.refunds.status | String | Refund Status. |
| data.refunds.external_transaction_id | String | Refund ID provided by the PSP. |
| error | Object | Error object. |
Also in our GetOrder endpoint we return in a property called refunds all the refunds that have been made.
JSON
{
"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": "Short-sleeve polo shirt in navy blue.",
"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": "jhondoe@deuna.com",
"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"
}
]
}