Captura, reembolso y anulación asíncronas
Maneje las operaciones de captura, reembolso y anulación, cuyos resultados finales del procesador llegan de forma asíncrona.
En esta página
Una operación de pago asíncrona devuelve después de que DEUNA acepte o encolada la operación, antes de que el procesador de pagos confirme el resultado final. La captura, el reembolso y la anulación pueden utilizar este modelo de procesamiento cuando está soportado y habilitado para la conexión del procesador.
Operaciones de API públicas#
Las siguientes operaciones orientadas al comerciante están expuestas a través del Gateway de API de DEUNA y se enumeran en catálogo de endpoints:
| Operación | Punto final | Estado intermedio típico |
|---|---|---|
| Captura | POST /merchants/orders/{order_token}/capture-async | capturing o partial_capturing |
| Reembolso | POST /merchants/orders/{order_token}/refund-async | refunding o partial_refunding |
| Anulación | POST /merchants/orders/{order_token}/void-async | voiding |
El soporte y el modo de ejecución del proveedor se configuran por conexión. Utilice las rutas del Gateway de API en la tabla como el contrato de integración público.
Estados intermedios y finales#
DEUNA puede devolver estos estados intermedios mientras el resultado del procesador está pendiente:
capturingopartial_capturing: La captura está pendiente.refundingopartial_refunding: El reembolso está pendiente.voiding: La anulación está pendiente.
Cuando se recibe la confirmación, DEUNA actualiza el pago. Dependiendo de la operación, el resultado puede ser:
capturedopartial_captured: Captura completada.refundedopartial_refunded: Reembolso completado.voided: Anulación completada.authorized,processedodenied: La operación ha fallado, se ha revertido o ha restaurado el pago al estado confirmado por el procesador.
Reembolsos asincrónicos#
El resto de esta guía describe el resultado asíncrono específico de la devolución.
Procesadores compatibles
Los procesadores que soportan estados intermedios para reembolsos asíncronos son:
- Kushki
- dLocal
- fuente cibernética
- NuPay (APM)
Confirmar el resultado asíncrono#
Obtener el pedido o el pago original después de que DEUNA procese la actualización del proveedor. Consulte Webhooks de DEUNA para el modelo de procesamiento de estado de pago asíncrono admitido.
Reembolso V2 con estado intermedio#
Diagrama de secuencia
Reembolso V2 con estado final
Diagrama de secuencia
Resultado de recuperación de pedido#
Verificar el estado de la transacción en el order.payment.data.status propiedad dentro del siguiente 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": []
}Respuesta de reembolso V2
En este ejemplo podemos ver que en el data.status propiedad tenemos el resultado del reembolso como refunding pero también podría ser refunded dependiendo de los casos mencionados anteriormente.
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
}La siguiente tabla describe las propiedades devueltas por nuestro punto final Refund V2:
| Nombre de la propiedad | tipo de datos | Descripción |
|---|---|---|
| data.refund_id | String | ID de reembolso en formato UUID. |
| data.status | String | Estado del reembolso. |
| data.refund_amount.amount | String | Monto del reembolso. |
| data.refund_amount.currency | String | Moneda de reembolso. |
| data.order | Orden | Objeto de pedido. |
| data.refunds | Lista | Listado de Reembolsos en el Pedido. |
| data.refunds.refund_id | String | ID de reembolso en formato UUID. |
| data.refunds.refund_amount.amount | String | Monto del reembolso. |
| data.refunds.refund_amount.currency | String | Moneda de reembolso. |
| data.refunds.refunded_on | Fecha | Fecha de reembolso en formato ISO 8601. |
| data.refunds.status | String | Estado del reembolso. |
| data.refunds.external_transaction_id | String | ID de reembolso proporcionado por el PSP. |
| error | Object | Objeto de error. |
También en nuestro ObtenerOrden punto final que devolvemos en una propiedad llamada refunds todos los reembolsos que se hayan realizado.
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"
}
]
}