Capture, remboursement et annulation asynchrones
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.
Lorsque la confirmation est reçue, DEUNA met à jour le paiement et émet le webhook configuré. 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 flux de webhook 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)
Configuration du webhook DEUNA#
DEUNA envoie l'instantané de commande résultant lorsque webhook_urls.notify_order est configuré pour la commande ou fourni par la configuration de niveau entreprise.
Si vous utilisez /purchase V2, puis le champ order.webhook_urls.notify_order peut être envoyé directement dans la charge utile de la demande.
Consultez Webhooks DEUNA pour les modes de livraison pris en charge, le contrat de contenu, l'en-tête de signature, l'accus, les tentatives et la configuration gérée par le TAM.
Remboursement V2 avec statut intermédiaire#
Remboursement V2 avec statut final
Payload de webhook#
DEUNA publie le résultat de la commande sur votre serveur. Vérifiez le statut de la transaction dans 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": "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": "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"
}
]
}