Link di pagamento tramite API
In questa pagina
Questa pagina fornisce una guida dettagliata per integrare la funzionalità di Payment Link nell'applicazione tramite API.
Il DEUNA Payment Link consente di creare collegamenti di pagamento per gli acquisti.
Il Payment Link facilita e semplifica il processo di pagamento attraverso la piattaforma DEUNA e riduce drasticamente la necessità di qualsiasi sviluppo.
Requisiti#
- Conoscenza di base di JavaScript e Typescript
- URLS API:
- Sandbox:
https://api.sandbox.deuna.io - Produzione:
https://api.deuna.io
- Sandbox:
- DEUNA merchant ID:
- Sandbox: Testare le credenziali per l'implementazione iniziale
- Produzione: credenziali di produzione per test e lancio controllati
- DEUNA credenziali di amministrazione
- DEUNA chiavi API pubbliche e private
1. Creare un link di pagamento#
Fai una richiesta al Creare ordine endpoint con il order_type come PAYMENT LINK.
Questo crea un token di ordine associato al link di pagamento.
Esempio di richiesta
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"
}
}
}Esempio di risposta
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": []
}Campi di link di pagamento#
I campi necessari per creare un link di pagamento sono documentati di seguito.
order campi
Questa sezione documenta i campi relativi all'ordine.
| Campo | Tipo | Obbligatorio | Descrizione |
|---|---|---|---|
| order_id | string | Sì. | ID interno per l'ordine |
| store_code | string | Sì. | Codice di memorizzazione |
| moneta | string | Sì. | Valuta ISO 4217 |
| total_tax_amount | number | Sì. | Importo totale dell'imposta |
| items_total_amount | number | Sì. | Sum dei prezzi base di tutti gli articoli prima delle tasse. |
| sub_total | number | Sì. | elementi_total_amount + totale_tax_amount. |
| total_amount | number | Sì. | Importo totale estratto dal sub_total. |
| Articolo | array | Sì. | Elenco degli articoli |
| order.items[].id | string | Sì. | Unique item ID |
| order.items[].name | string | Sì. | Nome dell'oggetto per il cliente |
| order.items[].description | string | No. | Descrizione dettagliata |
| order.items[].quantity | integer | Sì. | Quantità di elementi |
| order.items[].unit_price | object | Sì. | Prezzo unitario |
| importo | number | Sì. | Importo unitario |
| moneta | string | Sì. | Valuta ISO per unit_Prezzo |
| currency_symbol | string | Sì. | simbolo della valuta |
| order.items[].tax_amount | object | No. | Tassa applicata alla voce |
| order.items[].total_amount | object | Sì. | Totale finale |
| importo | number | Sì. | Totale importo dopo le tasse e gli sconti |
| discount_amount | number | Sì. | Importo scontato (se applicabile) |
| original_amount | number | Sì. | Prezzo originale senza tasse |
| order.items[].image_url | string | No. | URL dell'immagine dell'oggetto |
| redirect_urls | object | No. | Reindirizza URL a ciascun risultato |
| vicino | string | No. | Chiude il checkout |
| successo | string | No. | Per pagamenti di successo |
| in attesa di | string | No. | Per pagamenti in sospeso |
| errore | string | No. | Per guasti nel pagamento |
| fallo | string | No. | Pulsante posteriore nelle schermate di errore |
| include_payment_options | array | Sì. | Filtri disponibili metodi di pagamento e processori al momento del checkout. |
| include_payment_options[].payment_method | string | Sì. | Tipo di metodo di pagamento |
| include_payment_options[].processors | object | Sì. | Elenco dei nomi dei processori per abilitare |
checkout_modules campi
Definire quali moduli si desidera visualizzare quando si apre il link di pagamento nel widget:
| Campo di Campo | Tipo | Richiede | Cosa accade / A cosa serve |
|---|---|---|---|
| checkout_modules | array | No. | Elenco dei moduli di checkout da visualizzare |
| nome | string | Sì. | Nome del modulo: UserInfoPattern, OrderDetailPattern, LoginPattern |
configuration campi
Questi campi corrispondono alle impostazioni e alla personalizzazione dei Link di pagamento.
| Campo | Tipo | Obbligatorio | Descrizione |
|---|---|---|---|
| expires_at | string | No. | Data di scadenza/ora (ISO 8601). Senza questo campo, la data/ora non scadrà. |
| payment_link_name | string | No. | Nome descrittivo per il tuo link di pagamento (max. 60 caratteri). |
| max_completed_purchases | integer | No. | Limiti di acquisti di successo prima di disattivare il link. |
| max_payment_retries | integer | No. | Limiti di tentativi di pagamento per utente (include rifiuti). |
2. Presa il campo di redirect#
Nella risposta API, utilizzareorder.payment_link per reindirizzare l'utente alla schermata di pagamento.
Integra il link di pagamento in un'app o condividerlo attraverso la tua pagina web.
Nella risposta alla chiamata, troverete il link di pagamento nel campo payment_link.
Integrare il link di pagamento in una funzione javascript, dove href.location che reindirizza al link generato.
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>Carte di prova#
Utilizzare le schede di prova per elaborare i pagamenti di test:
- Importi inferiori a 50.000 mxn = Approvato
- Importi superiori a 50.000 mxn e inferiori a 100.000 mxn = Declined
3DS (MPI DEUNA)
Numero di carta:
- 4000000000002503 (successo della catena)
- 4000000000002370 (cambiamento guasto)
- 40000000000000002701 (successo senza frizione)
- 4000000000002925 (infrazione)
- Data di scadenza: 05/26
- CVV: 123
- Freddamento della carta:
Prueba por Deuna
Senza 3DS
Numero di carta:
4111111111111111(credito)5474925432670366(credito)4152313289903408(debito)5200828282828210(debito)4242424242424242(credito)4622943127013705- Data di scadenza: 05/26
- CVV: 123
- Porta carte:
Prueba por Deuna
3. Ottenere lo stato di pagamento#
Fai una richiesta al Ordinare endpoint per verificare lo stato di pagamento.
Utilizzare il gettone dell'ordine nella richiesta.
Esempio di risposta
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. Ascoltare gli eventi di collegamento di pagamento#
Uso Webhook DEUNA per ascoltare gli eventi di Payment Link.
Impostare i retries di consegna ad un massimo di tre tentativi.