Captura, reembolso e anulação assíncronas

Nesta página

Operações da API pública
Status intermediário e final
Reembolsos assíncronos
Configuração do webhook DEUNA
Reembolso V2 com status intermediário
Carga útil do webhook

Uma operação de pagamento assíncrona retorna após a DEUNA aceitar ou enfileirar a operação, antes que o processador de pagamento confirme o resultado final. Captura, reembolso e anulação podem usar este modelo de processamento quando é suportado e habilitado para a conexão do processador.

Operações da API pública#

As seguintes operações voltadas para o comerciante estão expostas através do Gateway API da DEUNA e listadas no catálogo de endpoints:

Operação	Endpoint	Status intermediário típico
Capturar	`POST /merchants/orders/{order_token}/capture-async`	`capturing` ou `partial_capturing`
Reembolso	`POST /merchants/orders/{order_token}/refund-async`	`refunding` ou `partial_refunding`
Vazio	`POST /merchants/orders/{order_token}/void-async`	`voiding`

O suporte e o modo de execução do provedor são configurados por conexão. Use as rotas do Gateway API na tabela como o contrato de integração público.

Status intermediário e final#

A DEUNA pode retornar estes status intermediários enquanto o resultado do processador está pendente:

capturing ou partial_capturing: Captura está pendente.
refunding ou partial_refunding: Reembolso está pendente.
voiding: Anulação está pendente.

Quando a confirmação chega, a DEUNA atualiza o pagamento e emite o webhook configurado. Dependendo da operação, o resultado pode ser:

captured ou partial_captured: Captura concluída.
refunded ou partial_refunded: Reembolso concluído.
voided: Anulação concluída.
authorized, processed, ou denied: A operação falhou, foi revertida ou restaurou o pagamento para o estado confirmado pelo processador.

Reembolsos assíncronos#

O restante desta guia descreve o fluxo de webhook específico para reembolso.

Processadores suportados

Os processadores que suportam estados intermediários para reembolsos assíncronos são:

Kushki
dLocal
Fonte cibernética
NuPay (APM)

Configuração do webhook DEUNA#

A DEUNA envia o snapshot do pedido resultante quando webhook_urls.notify_order está configurado para o pedido ou fornecido pela configuração de nível de comerciante.

Se você estiver usando /purchase V2, então o campo order.webhook_urls.notify_order pode ser enviado diretamente na carga útil da solicitação.

Consulte Webhooks da DEUNA para os modos de entrega suportados, contrato de payload, cabeçalho de assinatura, confirmação, tentativas e configuração gerenciada pelo TAM.

Reembolso V2 com status intermediário#

Reembolso V2 com status final

Carga útil do webhook#

A DEUNA publica o resultado do pedido no seu servidor. Verifique o status da transação no order.payment.data.status propriedade dentro do seguinte 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": []
}

Resposta de reembolso V2

Neste exemplo podemos ver que no data.status imóvel temos o resultado do reembolso conforme refunding mas também poderia ser refunded dependendo dos casos mencionados acima.

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
}

A tabela a seguir descreve as propriedades retornadas pelo nosso endpoint Refund V2:

Nome da propriedade	Tipo de dados	Descrição
data.refund_id	String	ID de reembolso no formato UUID.
data.status	String	Status do reembolso.
data.refund_amount.amount	String	Valor do reembolso.
data.refund_amount.currency	String	Moeda de reembolso.
data.order	Pedido	Objeto de pedido.
data.refunds	Lista	Lista de reembolsos no pedido.
data.refunds.refund_id	String	ID de reembolso no formato UUID.
data.refunds.refund_amount.amount	String	Valor do reembolso.
data.refunds.refund_amount.currency	String	Moeda de reembolso.
data.refunds.refunded_on	Data	Data de reembolso no formato ISO 8601.
data.refunds.status	String	Status do reembolso.
data.refunds.external_transaction_id	String	ID de reembolso fornecido pelo PSP.
erro	Object	Objeto de erro.

Também em nosso Obter pedido endpoint que retornamos em uma propriedade chamada refunds todos os reembolsos que foram feitos.

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