Acquisizione, rimborso e annullamento asincroni

In questa pagina

Operazioni API pubbliche
Stati intermedi e finali
Rimborso asincrono
configurazione webhook DEUNA
Rimborso V2 con stato intermedio
Payload del webhook

Un'operazione di pagamento asincrona restituisce dopo che DEUNA ha accettato o messo in coda l'operazione, prima che il processore di pagamento abbia confermato il risultato finale. Acquisizione, rimborso e annullamento possono utilizzare questo modello di elaborazione quando è supportato e abilitato per la connessione del processore.

Operazioni API pubbliche#

Le seguenti operazioni per i commercianti sono esposte tramite il gateway API di DEUNA e sono elencate nella catalogo degli endpoint:

Operazioni	Fine	Stato intermedio tipico
Capture	`POST /merchants/orders/{order_token}/capture-async`	`capturing` o `partial_capturing`
Rimborso	`POST /merchants/orders/{order_token}/refund-async`	`refunding` o `partial_refunding`
Void	`POST /merchants/orders/{order_token}/void-async`	`voiding`

Il supporto del fornitore e la modalità di esecuzione sono configurati per ogni connessione. Utilizzare i percorsi del gateway API nella tabella come contratto di integrazione pubblico.

Stati intermedi e finali#

DEUNA può restituire questi stati intermedi mentre il risultato del processore è in attesa:

capturing o partial_capturing: L'acquisizione è in attesa.
refunding o partial_refunding: Il rimborso è in attesa.
voiding: L'annullamento è in attesa.

Quando arriva la conferma, DEUNA aggiorna il pagamento ed emette il webhook configurato. A seconda dell'operazione, il risultato può essere:

captured o partial_captured: Acquisizione completata.
refunded o partial_refunded: Rimborso completato.
voided: Annullamento completato.
authorized, processedo denied: L'operazione è fallita, è stata annullata o ha riportato il pagamento allo stato confermato dal processore.

Rimborso asincrono#

Il resto di questa guida descrive il flusso di webhook specifico per il rimborso.

Processori supportati

I processori che sostengono gli stati intermedi per i rimborsi asincroni sono:

Kushki
dLocal
Cybersource
NuPay (APM)

configurazione webhook DEUNA#

DEUNA invia lo snapshot dell'ordine risultante quando webhook_urls.notify_order è configurato per l'ordine o fornito dalla configurazione a livello di commerciante.

Se stai usando /purchase V2, poi il campo order.webhook_urls.notify_order può essere inviato direttamente nel carico di pagamento della richiesta.

Consulta Webhook DEUNA per i modalità di consegna supportate, contratto del payload, intestazione di firma, riconoscimento, tentativi e configurazione gestita da TAM.

Rimborso V2 con stato intermedio#

Rimborso V2 con stato finale

Payload del webhook#

DEUNA pubblica il risultato dell'ordine sul tuo server. Verificare lo stato della transazione nel order.payment.data.status proprietà all'interno del seguente 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": []
}

Rimborso V2 Risposta

In questo esempio possiamo vedere che data.status proprietà abbiamo il risultato del rimborso come refunding ma potrebbe anche refunded a seconda dei casi sopra menzionati.

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 seguente tabella descrive le proprietà restituite dal nostro endpoint Refund V2:

Nome della proprietà	Tipo di dati	Descrizione
data.refund_id	String	ID di rimborso in formato UUID.
data.status	String	Stato di rimborso.
data.refund_amount.amount	String	Rimborso Importo.
data.refund_amount.currency	String	Rimborso Valuta.
data.order	Ordine	Ordine oggetto.
data.refunds	Elenco	Elenco dei Rimborsi dell'Ordine.
data.refunds.refund_id	String	ID di rimborso in formato UUID.
data.refunds.refund_amount.amount	String	Rimborso Importo.
data.refunds.refund_amount.currency	String	Rimborso Valuta.
data.refunds.refunded_on	Data	Data di rimborso in formato ISO 8601.
data.refunds.status	String	Stato di rimborso.
data.refunds.external_transaction_id	String	ID di rimborso fornito dal PSP.
errore	Object	Oggetto di errore.

Anche nel nostro Ottenga l'ordine endpoint torniamo in una proprietà chiamata refunds tutti i rimborsi che sono stati fatti.

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"
        }
    ]
}