Link de pagamento via API
Nesta página
Esta página fornece um guia detalhado para integrar a funcionalidade do link de pagamento em seu aplicativo via API.
O Link de Pagamento DEUNA permite criar links de pagamento para compras.
O Link de Pagamento facilita e agiliza o processo de pagamento através da plataforma DEUNA e reduz drasticamente a necessidade de qualquer desenvolvimento.
Requisitos#
- Conhecimento básico de JavaScript e Typescript
- URLs de API:
- Caixa de areia:
https://api.sandbox.deuna.io - Produção:
https://api.deuna.io
- Caixa de areia:
- DEUNA merchant ID:
- Sandbox: testando credenciais para a implementação inicial
- Produção: Credenciais de produção para testes e lançamento controlados
- Credenciais de administrador DEUNA
- Chaves API públicas e privadas DEUNA
1. Crie um link de pagamento#
Faça uma solicitação ao Criar pedido ponto final com o order_type definir como PAYMENT LINK.
Isso cria um token de pedido associado ao link de pagamento.
Solicitação de exemplo
JSON
{
"order_type": "PAYMENT_LINK",
"payer_info": {
"email": "mramos@deuna.com" // email of the user
},
"order": {
"order_id": "{{identificador orden del comercio}}",
"currency": "MXN",
"items_total_amount": 150000, //Monto con 2 decimales sin punto
"sub_total": 150000,
"total_amount": 150000,
"store_code": "all",
// URL to redirect back after payment is attempted
"redirect_urls": {
"success": "https://www.google.com?q=success", // redirect on successful payment
"error": "https://www.google.com?q=failure", // redirect on failure payment
"close": "https://www.google.com?q=close" // redirect on user closing the payment link
},
"payer_info":{
"email": "mramos@deuna.com" // email of the user
},
"billing_address": {
"country": "MX",
"country_code": "MX",
"email": "mramos@deuna.com" // email of the user
},
"items": [ // items the user is purchasing
{
"id": "79", // required
"name": "Pago de impuesto", // required
"description": "Pago de servicio de agua", // required
"type": "virtual", // required to send "virtual"
"total_amount": { // required
"amount": 150000,
"currency": "MXN"
},
"unit_price": { // required
"amount": 150000,
"currency": "MXN"
},
"quantity": 1, // required
"category": "Pago de servicios", // required
"image_url": "https://encrypted-tbn0.gstatic.com/images?q=tbn:ANd9GcSj5Ywbfmq1apVaZL9YeODf1J22DzGDI9THkA&s" // required
}
],
"webhook_urls": { // API Endpoint into which we will send you the order status updates
"notify_order": "https://webhook.site/54a29453-05fd-4875-a861-08071421a609"
}
}
}Exemplo de resposta
JSON
{
"token": "638f7ec0-9f1f-4898-8b42-a1ac2d555216",
"order_type": "PAYMENT_LINK",
"order": {
"order_id": "4167f4a3-0081-4b3d-82ba-cf8da04e5cc4",
"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": 150000,
"display_items_total_amount": "MXN 1500.00",
"sub_total": 150000,
"display_sub_total": "MXN 1500.00",
"total_amount": 150000,
"display_total_amount": "MXN 1500.00",
"items": [
{
"id": "79",
"name": "Pago de impuesto",
"description": "Pago de servicio de agua",
"options": "",
"total_amount": {
"amount": 1000,
"original_amount": 0,
"display_amount": "MXN 1500.00",
"display_original_amount": "MXN 0.00",
"currency": "MXN",
"currency_symbol": "",
"total_discount": 0,
"display_total_discount": "MXN 0.00"
},
"unit_price": {
"amount": 1000,
"display_amount": "MXN 1500.00",
"currency": "MXN",
"currency_symbol": ""
},
"tax_amount": {
"amount": 0,
"display_amount": " 0.00",
"currency": "",
"currency_symbol": ""
},
"quantity": 1,
"uom": "",
"upc": "",
"sku": "",
"isbn": "",
"brand": "",
"manufacturer": "",
"category": "taxation",
"color": "",
"size": "",
"weight": {
"weight": 0,
"unit": ""
},
"image_url": "https://encrypted-tbn0.gstatic.com/images?q=tbn:ANd9GcSj5Ywbfmq1apVaZL9YeODf1J22DzGDI9THkA&s",
"details_url": "",
"type": "virtual",
"taxable": false,
"discounts": [],
"included_in_subscription": false,
"item_details": []
}
],
"discounts": [],
"shipping_address": {
"id": 0,
"user_id": "",
"first_name": "",
"last_name": "",
"phone": "",
"identity_document": "",
"lat": 0,
"lng": 0,
"address1": "",
"address2": "",
"city": "",
"zipcode": "",
"state_name": "",
"country_code": "",
"additional_description": "",
"address_type": "",
"is_default": false,
"created_at": "",
"updated_at": "",
"identity_document_type": "",
"email": "",
"state_code": "",
"country": ""
},
"shipping_options": {
"type": "",
"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": "pending",
"payment": {
"data": {
"amount": {
"amount": 0,
"currency": ""
},
"metadata": {},
"from_card": {
"card_brand": "",
"first_six": "",
"last_four": "",
"bank_name": "",
"country_iso": "",
"credential_source": "",
"expiry_month": "",
"expiry_year": ""
},
"updated_at": "0001-01-01 00:00:00 +0000 UTC",
"method_type": "",
"merchant": {
"store_code": "",
"id": "",
"affiliation_code": "",
"mcc": ""
},
"created_at": "0001-01-01 00:00:00 +0000 UTC",
"id": "",
"processor": "",
"customer": {
"email": "",
"id": "",
"first_name": "",
"last_name": ""
},
"status": "",
"reason": "",
"external_transaction_id": "",
"merchant_payment_processor_name": "",
"authorization_code": "",
"installment_interest_calculations": null,
"three_ds_details": {},
"merchant_payment_processor_id": ""
}
},
"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": 0,
"user_id": "",
"first_name": "",
"last_name": "",
"phone": "",
"identity_document": "",
"lat": 0,
"lng": 0,
"address1": "",
"address2": "",
"city": "",
"zipcode": "",
"state_name": "",
"country_code": "MX",
"additional_description": "",
"address_type": "",
"is_default": false,
"created_at": "2025-04-30T01:45:30Z",
"updated_at": "2025-04-30T01:45:30Z",
"email": "jmoscoso@deuna.com",
"identity_document_type": "",
"country": "",
"state_code": ""
},
"payment_link": "https://pay.bancoazteca.deuna.com//638f7ec0-9f1f-4898-8b42-a1ac2d555216",
"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": "https://www.google.com?q=success",
"pending": "",
"error": "https://www.google.com?q=failure",
"fallback": "",
"close": "https://www.google.com?q=close"
},
"created_at": "2025-04-30 01:45:30.06298093 +0000 UTC",
"updated_at": "",
"payer_info": {
"email": "mramos@deuna.com",
"person_type": "UNKNOWN_PERSON"
},
"discount_amount": 0,
"shipping_discount_amount": 0,
"device_fingerprint": "",
"expired_at": "",
"version": "0",
"fraud": null,
"total_interest_amount": 0,
"display_total_interest_amount": "MXN 0.00",
"payment_method": "",
"token": "",
"statement_descriptor": "",
"callback_urls": null
},
"custom_fields": [],
"checkout_modules": []
}Campos de link de pagamento#
Os campos necessários para criar um link de pagamento estão documentados abaixo.
order campos
Esta seção documenta os campos relacionados ao pedido.
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| order_id | string | Sim | ID interno do pedido |
| store_code | string | Sim | Código da loja |
| moeda | string | Sim | Moeda ISO 4217 |
| total_tax_amount | number | Sim | Valor total do imposto |
| items_total_amount | number | Sim | Soma dos preços base de todos os itens antes dos impostos. |
| sub_total | number | Sim | itens_total_valor + total_imposto_valor. |
| total_amount | number | Sim | Valor total extraído de sub_total. |
| itens | array | Sim | Lista de itens |
| order.items[].id | string | Sim | Unique item ID |
| order.items[].name | string | Sim | Nome do item para o cliente |
| order.items[].description | string | Não | Descrição detalhada |
| order.items[].quantity | integer | Sim | Quantidade de itens |
| order.items[].unit_price | object | Sim | Preço unitário |
| quantidade | number | Sim | Valor unitário |
| moeda | string | Sim | Moeda ISO para unidade_preço |
| currency_symbol | string | Sim | Símbolo de moeda |
| order.items[].tax_amount | object | Não | Imposto aplicado ao item |
| order.items[].total_amount | object | Sim | Valor total final |
| quantidade | number | Sim | Valor total após impostos e descontos |
| discount_amount | number | Sim | Valor com desconto (se aplicável) |
| original_amount | number | Sim | Preço original sem impostos |
| order.items[].image_url | string | Não | URL da imagem do item |
| redirect_urls | object | Não | Redirecionar URLs para cada resultado |
| fechar | string | Não | Fecha o checkout |
| sucesso | string | Não | Para pagamentos bem-sucedidos |
| pendente | string | Não | Para pagamentos pendentes |
| erro | string | Não | Por falhas no pagamento |
| substituto | string | Não | Botão Voltar em telas de erro |
| include_payment_options | array | Sim | Filtra métodos de pagamento e processadores disponíveis na finalização da compra. |
| include_payment_options[].payment_method | string | Sim | Tipo de forma de pagamento |
| include_payment_options[].processors | object | Sim | Lista de nomes de processadores para ativar |
checkout_modules campos
Defina quais módulos você deseja exibir ao abrir o link de pagamento no seu widget:
| Campo | Tipo | Requer | O que acontece / Para que serve |
|---|---|---|---|
| checkout_modules | array | Não | Lista de módulos de checkout a serem exibidos |
| nome | string | Sim | Nome do módulo: UserInfoPattern, OrderDetailPattern, LoginPattern |
configuration campos
Estes campos correspondem às configurações e personalização dos Links de Pagamento.
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| expires_at | string | Não | Data/hora de expiração (ISO 8601). Sem este campo, a data/hora não expirará. |
| payment_link_name | string | Não | Nome descritivo do seu Link de Pagamento (máx. 60 caracteres). |
| max_completed_purchases | integer | Não | Limite de compras bem-sucedidas antes de desativar o link. |
| max_payment_retries | integer | Não | Limite de tentativas de pagamento por usuário (inclui rejeições). |
2. Busque o campo de redirecionamento#
Na resposta da API, useorder.payment_link para redirecionar o usuário para a tela de pagamento.
Integre o link de pagamento em um aplicativo ou compartilhe-o em sua página web.
Na resposta da chamada, você encontrará o link de pagamento no campo payment_link.
Integre o Link de Pagamento em uma função javascript, onde um href.location que redireciona para o link gerado.
JavaScript
function openDeunaPayment() {
const paymentLink = "https://api.deuna.io/payment-links/{payment-link-id}";
window.location.href = paymentLink; // Opens the link in the same window
}JavaScript
<!DOCTYPE html>
<html>
.
.
<body>
<div class="container">
<h1>Realizar Pago</h1>
<p>Haz clic en el botón "Pagar con Deuna" para continuar con el pago.</p>
<button id="payButton" class="pay-button" onclick="openDeunaPayment()">Pagar con Deuna</button>
</div>
<script src="app.ts"></script>
</body>
</html>Cartões de teste#
Use cartões de teste para processar pagamentos de teste:
- Valores inferiores a 50.000 mxn = Aprovados
- Valores superiores a 50.000 mxn e inferiores a 100.000 mxn = Recusados
3DS (MPI DEUNA)
Número do cartão:
- 4000000000002503 (sucesso no desafio)
- 4000000000002370 (falha no desafio)
- 4000000000002701 (sucesso sem atrito)
- 4000000000002925 (falha sem atrito)
- Data de validade: 26/05
- CVV: 123
- Cartão mais frio:
Prueba por Deuna
Sem 3DS
Número do cartão:
4111111111111111(crédito)5474925432670366(crédito)4152313289903408(débito)5200828282828210(débito)4242424242424242(crédito)4622943127013705- Data de validade: 26/05
- CVV: 123
- Titular do cartão:
Prueba por Deuna
3. Obtenha o status do pagamento#
Faça uma solicitação ao Obter pedido endpoint para verificar o status do pagamento.
Use o token do pedido na solicitação.
Exemplo de resposta
JSON
{
"token": "bb0aa546-8d96-4121-8cc2-981f2e3082d1",
"order_type": "PAYMENT_LINK",
"order": {
"order_id": "8000-123-293467",
"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": 166746,
"display_items_total_amount": "MXN 1,500.00",
"sub_total": 166746,
"display_sub_total": "MXN 1,500.00",
"total_amount": 166746,
"display_total_amount": "MXN 1,500.00",
"items": [
{
"id": "8000-123-293467",
"name": "PAGO REGULAR SERVICIO DE AGUA",
"description": "PAGO REGULAR SERVICIO DE AGUA Contrato: 14932 Periodo Inicial: 202501 Periodo Final: 202502",
"options": "",
"total_amount": {
"amount": 166746,
"original_amount": 0,
"display_amount": "MXN 1,500.00",
"display_original_amount": "MXN 0.00",
"currency": "MXN",
"currency_symbol": "",
"total_discount": 0,
"display_total_discount": "MXN 0.00"
},
"unit_price": {
"amount": 166746,
"display_amount": "MXN 1,500.00",
"currency": "MXN",
"currency_symbol": ""
},
"tax_amount": {
"amount": 0,
"display_amount": " 0.00",
"currency": "",
"currency_symbol": ""
},
"quantity": 1,
"uom": "",
"upc": "",
"sku": "",
"isbn": "",
"brand": "",
"manufacturer": "",
"category": "curso",
"color": "",
"size": "",
"weight": {
"weight": 0,
"unit": ""
},
"image_url": "https://encrypted-tbn0.gstatic.com/images?q=tbn:ANd9GcSj5Ywbfmq1apVaZL9YeODf1J22DzGDI9THkA&",
"details_url": "",
"type": "virtual",
"taxable": false,
"discounts": [],
"included_in_subscription": false,
"item_details": []
}
],
"discounts": [],
"shipping_address": {
"id": 0,
"user_id": "",
"first_name": "ROBERTO ANTONIO",
"last_name": "MILLAN FLORES",
"phone": "+52 5619179755",
"identity_document": "",
"lat": 0,
"lng": 0,
"address1": "",
"address2": "",
"city": "",
"zipcode": "55770",
"state_name": "",
"country_code": "MX",
"additional_description": "",
"address_type": "",
"is_default": true,
"created_at": "2025-04-30T00:05:19Z",
"updated_at": "2025-04-30T00:05:19Z",
"identity_document_type": "",
"email": "juridicomillan@gmail.com",
"state_code": "",
"country": "MX"
},
"shipping_options": {
"type": "",
"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": "succeeded",
"payment": {
"data": {
"amount": {
"amount": 166746,
"currency": "MXN"
},
"metadata": {
"authorization_code": "020815"
},
"from_card": {
"card_brand": "mastercard",
"first_six": "520416",
"last_four": "8095",
"installment": {
"installments": 1,
"plan_id": "",
"plan_option_id": "",
"installment_type": "",
"installment_rate": 0,
"installment_amount": 0
},
"bank_name": "Banco Nacional De Mexico, S.A.",
"country_iso": "MX",
"credential_source": "",
"expiry_month": "04",
"expiry_year": "2028"
},
"updated_at": "2025-04-30 00:05:20.824900873 +0000 UTC",
"method_type": "credit_card",
"merchant": {
"store_code": "all",
"id": "ba8537e7-4f9d-4306-94f9-784c99304bde",
"affiliation_code": "127",
"mcc": "4900"
},
"created_at": "2025-04-30 00:05:19.747601 +0000 UTC",
"id": "8000-123-293467",
"processor": "baz_gateway",
"customer": {
"email": "juridicomillan@gmail.com",
"id": "88635a0c-2bca-4f43-80a0-d6ebbd31709a",
"first_name": "",
"last_name": ""
},
"status": "processed",
"reason": "",
"external_transaction_id": "100740865324",
"merchant_payment_processor_name": "9269029",
"processor_error": {
"code": "",
"message": ""
},
"authorization_code": "020815",
"installment_interest_calculations": null,
"routing_strategy": "Procesamiento sin 3DS + Antifraude",
"three_ds_details": {},
"data_sync": {
"iso8583_processing_code": "",
"iso8583_response_code": "",
"iso8583_response_code_description": "",
"switch_name": "PROSA"
},
"merchant_payment_processor_id": "12235b03-e48c-4ca6-8e7c-c18676df1546"
}
},
"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": 0,
"user_id": "",
"first_name": "ROBERTO ANTONIO",
"last_name": "MILLAN FLORES",
"phone": "+52 5619179755",
"identity_document": "",
"lat": 0,
"lng": 0,
"address1": "M 64 L 21 GALEANA",
"address2": "",
"city": "Ojo de Agua",
"zipcode": "55770",
"state_name": "Estado de México",
"country_code": "MX",
"additional_description": "",
"address_type": "",
"is_default": false,
"created_at": "2025-04-30T00:05:19Z",
"updated_at": "2025-04-30T00:05:19Z",
"email": "juridicomillan@gmail.com",
"identity_document_type": "",
"country": "",
"state_code": "MEX"
},
"payment_link": "https://pay.bancoazteca.deuna.com//bb0aa546-8d96-4121-8cc2-981f2e3082d1",
"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": "https://www.google.com?q=success",
"pending": "https://www.google.com?q=pending",
"error": "https://www.google.com?q=error",
"fallback": "",
"close": "https://www.google.com?q=close"
},
"created_at": "2025-04-30 00:00:24.145522886 +0000 UTC",
"updated_at": "2025-04-30 00:05:20.921803615 +0000 UTC",
"payer_info": {
"email": "mramos@deuna.com",
"person_type": "UNKNOWN_PERSON"
},
"discount_amount": 0,
"shipping_discount_amount": 0,
"device_fingerprint": "",
"expired_at": "",
"version": "0",
"fraud": {
"analysis": {
"score": 0.4589535,
"processor": "SIFT",
"risk_level": "low",
"status": "automatic_decision",
"type": "",
"fraud_decision": "low_risk",
"details": "Everything Else",
"processor_response": "order_looks_ok_payment_abuse"
}
},
"total_interest_amount": 0,
"display_total_interest_amount": "MXN 0.00",
"payment_method": "",
"token": "",
"statement_descriptor": "",
"browser_details": {
"screen_height": 753,
"screen_width": 339,
"user_agent": "",
"ip_address": "",
"color_depth": 24,
"java_enabled": false,
"java_script_enabled": false,
"language": "es-ES",
"time_zone_offset": 0,
"accept_header": "text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,image/apng,*/*;q=0.8"
},
"callback_urls": null
},
"custom_fields": [],
"checkout_modules": [],
"refunds": []
}4. Ouça os eventos do link de pagamento#
Uso Webhooks da DEUNA para ouvir eventos de link de pagamento.
Defina as tentativas de entrega para no máximo três tentativas.