Capture, remboursement et annulation asynchrones
Gérer les opérations de capture, de remboursement et d'annulation dont le résultat final du processeur arrive de manière asynchrone.
Sur cette page
Une opération de paiement asynchrone retourne après que DEUNA a accepté ou mis en file d'attente l'opération, avant que le processeur de paiement n'ait confirmé le résultat final. Capture, remboursement et annulation peuvent utiliser ce modèle de traitement lorsque cela est pris en charge et activé pour la connexion au processeur.
Opérations API publiques#
Les opérations suivantes, destinées aux commerçants, sont exposées via le Gateway API DEUNA et sont répertoriées dans catalogue des endpoints:
| Fonctionnement | Point de terminaison | Statut intermédiaire typique |
|---|---|---|
| Capturer | POST /merchants/orders/{order_token}/capture-async | capturing ou partial_capturing |
| Remboursement | POST /merchants/orders/{order_token}/refund-async | refunding ou partial_refunding |
| Vide | POST /merchants/orders/{order_token}/void-async | voiding |
Le support et le mode d'exécution du fournisseur sont configurés par connexion. Utilisez les routes du Gateway API dans le tableau comme contrat d'intégration public.
Statuts intermédiaires et finaux#
DEUNA peut renvoyer ces statuts intermédiaires pendant que le résultat du processeur est en attente :
capturingoupartial_capturing: La capture est en attente.refundingoupartial_refunding: Le remboursement est en attente.voiding: L'annulation est en attente.
Lors de la réception de la confirmation, DEUNA met à jour le paiement. Selon l'opération, le résultat peut être :
capturedoupartial_captured: La capture est terminée.refundedoupartial_refunded: Le remboursement est terminé.voided: L'annulation est terminée.authorized,processed, oudenied: L'opération a échoué, a été annulée ou a restauré le paiement à l'état confirmé par le processeur.
Remboursements asynchrones#
Le reste de ce guide décrit le résultat asynchrone spécifique au remboursement.
Processeurs pris en charge
Les processeurs qui prennent en charge les états intermédiaires pour les remboursements asynchrones sont :
- Kouchki
- dLocal
- Cybersource
- NuPay (APM)
Confirmer le résultat asynchrone#
Récupérer la commande ou le paiement original après que DEUNA ait traité la mise à jour du fournisseur. Voir Webhooks DEUNA pour le modèle de traitement de statut de paiement asynchrone pris en charge.
Remboursement V2 avec statut intermédiaire#
Diagramme de séquence
Remboursement V2 avec statut final
Diagramme de séquence
Résultat de la commande récupéré#
Vérifier le statut de la transaction dans le order.payment.data.status propriété dans le JSON suivant :
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": []
}Réponse de remboursement V2
Dans cet exemple, nous pouvons voir que dans le data.status propriété, nous avons le résultat du remboursement comme refunding mais ça pourrait aussi être refunded en fonction des cas évoqués ci-dessus.
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
}Le tableau suivant décrit les propriétés renvoyées par notre point de terminaison Refund V2 :
| Nom de la propriété | Type de données | Descriptif |
|---|---|---|
| data.refund_id | String | ID de remboursement au format UUID. |
| data.status | String | Statut de remboursement. |
| data.refund_amount.amount | String | Montant du remboursement. |
| data.refund_amount.currency | String | Devise de remboursement. |
| data.order | Commande | Objet de commande. |
| data.refunds | Liste | Liste des remboursements dans la commande. |
| data.refunds.refund_id | String | ID de remboursement au format UUID. |
| data.refunds.refund_amount.amount | String | Montant du remboursement. |
| data.refunds.refund_amount.currency | String | Devise de remboursement. |
| data.refunds.refunded_on | Date | Date de remboursement au format ISO 8601. |
| data.refunds.status | String | Statut de remboursement. |
| data.refunds.external_transaction_id | String | ID de remboursement fourni par le PSP. |
| erreur | Object | Objet d'erreur. |
Également dans notre Obtenir la commande point final que nous renvoyons dans une propriété appelée refunds tous les remboursements qui ont été effectués.
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"
}
]
}