Pular para o conteúdo principal
Todos os sistemas operacionaisNovidadesv1
Entrar

Captura, reembolso e anulação assíncronas

Gerencie as operações de captura, reembolso e cancelamento, cujos resultados finais do processador chegam de forma assíncrona.

Nesta página

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çãoEndpointStatus intermediário típico
CapturarPOST /merchants/orders/{order_token}/capture-asynccapturing ou partial_capturing
ReembolsoPOST /merchants/orders/{order_token}/refund-asyncrefunding ou partial_refunding
VazioPOST /merchants/orders/{order_token}/void-asyncvoiding

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. 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 deste guia descreve o resultado assíncrono 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)

Confirme o resultado assíncrono#

Recupere o pedido ou pagamento original após a DEUNA processar a atualização do provedor. Consulte Webhooks da DEUNA para o modelo de processamento de status de pagamento assíncrono suportado.

Reembolso V2 com status intermediário#

Diagrama de sequência
1Merchant backend2DEUNA3Payment processorRequest Refund V2Request the refundReturn a pending resultReturn refunding statusConfirm the final resultasynchronouslySend the refunded statusnotification
Comerciante ou clienteDEUNAProvedor ou processador

Reembolso V2 com status final

Diagrama de sequência
1Merchant backend2DEUNA3Payment processorRequest Refund V2Request the refundConfirm the final resultReturn refunded status
Comerciante ou clienteDEUNAProvedor ou processador

Resultado da recuperação do pedido#

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 propriedadeTipo de dadosDescrição
data.refund_idStringID de reembolso no formato UUID.
data.statusStringStatus do reembolso.
data.refund_amount.amountStringValor do reembolso.
data.refund_amount.currencyStringMoeda de reembolso.
data.orderPedidoObjeto de pedido.
data.refundsListaLista de reembolsos no pedido.
data.refunds.refund_idStringID de reembolso no formato UUID.
data.refunds.refund_amount.amountStringValor do reembolso.
data.refunds.refund_amount.currencyStringMoeda de reembolso.
data.refunds.refunded_onDataData de reembolso no formato ISO 8601.
data.refunds.statusStringStatus do reembolso.
data.refunds.external_transaction_idStringID de reembolso fornecido pelo PSP.
erroObjectObjeto 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": "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"
        }
    ]
}