Integrar links de pago ecommerce
Esta guía está dirigida al equipo técnico del comercio que va a generar links de pago ecommerce desde su propio backend y enviarlos al cliente final para cobrar en el checkout hospedado por Payment Nexus.
Sitio de documentación de esta VPS: https://pnx-tutoriales.atidyarok.com.
El contrato descrito abajo es el contrato objetivo servidor-a-servidor para crear links de pago desde el backend del comercio. Antes de que tus llamadas funcionen, Payment Nexus debe habilitar la ruta final de API y provisionar una credencial de integración servidor-a-servidor para tu ambiente.
No inicies llamadas automatizadas ni pruebas contra POST /f2c65bd1289pm/link hasta que Payment Nexus confirme por canal seguro el host final de API, el host final de checkout y la credencial de integración habilitada para tu tenant/comercio/sucursal. Los ejemplos son plantillas de preparación y no contienen credenciales utilizables hoy.
Para esta integración rápida, la llamada servidor-a-servidor objetivo desde tu ecommerce hacia Payment Nexus es la creación del link con una credencial de integración provisionada por Payment Nexus y datos asignados al comercio. Nunca llames endpoints autenticados desde el frontend, navegador, app móvil pública o código descargable por el cliente final. Tu servidor debe crear el link y devolver únicamente la URL de checkout a tu frontend.
1. Resumen rápido
- Tu backend recibe una orden de compra de tu ecommerce.
- Cuando Payment Nexus haya habilitado tu credencial y host final, tu backend crea un link de pago con
POST /f2c65bd1289pm/link. - Payment Nexus responde con
checkout_urly los datos del link. - Tu frontend redirige al comprador a esa URL o la muestra dentro de un iframe si el canal fue certificado para ello.
- El comprador completa el pago en el checkout hospedado. Durante las primeras pruebas, el estado final se valida con el equipo de Payment Nexus en Payment Nexus/dash/admin hasta que el API autenticado de estado/conciliación y los webhooks estén habilitados para tu ambiente.
Montos: MXN únicamente, expresados en unidades menores (amount_minor), por ejemplo 12345 = $123.45 MXN. No envíes montos con decimales ni monedas distintas a MXN.
2. Arquitectura recomendada
sequenceDiagram
participant C as Cliente final
participant FE as Ecommerce frontend
participant BE as Backend del comercio
participant API as Payment Nexus API
participant CO as Checkout Payment Nexus
C->>FE: Confirma carrito
FE->>BE: POST /ordenes/{id}/pagar
BE->>API: POST /f2c65bd1289pm/link (Bearer de integración + Idempotency-Key)
API-->>BE: checkout_url, id, status=active
BE-->>FE: checkout_url
FE->>CO: Redirección o iframe certificado
C->>CO: Captura datos de pago
Note over BE,API: Estado final inicial: validación con Payment Nexus/dash/admin
Reglas principales:
- La credencial de integración vive solo en tu backend y solo debe usarse cuando Payment Nexus confirme que está habilitada.
- Payment Nexus asigna
tenant_id,merchant_id,branch_idy permisos. - El checkout público es quien recibe los datos de tarjeta; tu ecommerce no debe recolectar PAN/CVV salvo que exista una certificación PCI explícita.
- Usa idempotencia para cada intento de creación ligado a una orden interna.
3. Hosts y ambientes
Para esta VPS usa estos placeholders hasta que Payment Nexus entregue los hosts finales por canal seguro. El host de API debe ser el host final de API de la VPS provisto por Payment Nexus y debe estar habilitado/enrutado antes de iniciar pruebas; no inventes un host.
| Concepto | Valor |
|---|---|
| Documentación | https://pnx-tutoriales.atidyarok.com |
| API base | https://<API_HOST_DE_LA_VPS> |
| Checkout base | https://<CHECKOUT_HOST_DE_LA_VPS> |
| Endpoint real de creación | POST /f2c65bd1289pm/link |
| Moneda soportada | MXN |
El host final de API, el host final de checkout y la credencial de integración serán entregados por Payment Nexus mediante canal seguro. No se publican secretos en esta documentación. Hasta recibir esa confirmación, esta guía sirve para preparar el desarrollo, no para ejecutar llamadas automatizadas.
4. Autenticación y autorización
La creación de links requiere una credencial de integración servidor-a-servidor provisionada y habilitada por Payment Nexus:
Authorization: Bearer <CREDENCIAL_DE_INTEGRACION_A_PROVISIONAR>
Esta credencial todavía no debe considerarse utilizable hasta que Payment Nexus confirme la activación del host/ruta final y el alcance asignado (tenant/comercio/sucursal correspondiente). Los endpoints autenticados de lectura/estado, conciliación y webhooks para este flujo están pendientes o siendo habilitados por Payment Nexus para cada ambiente; no asumas que ya existen hasta recibir confirmación explícita.
Valores asignados por Payment Nexus:
tenant_idmerchant_idbranch_idcuando aplique- credencial de integración servidor-a-servidor
- host final de API
- host final de checkout
No inventes ni reutilices valores entre ambientes. Una credencial de pruebas no debe usarse en producción.
5. Crear link de pago
Endpoint
POST https://<API_HOST_DE_LA_VPS>/f2c65bd1289pm/link
Headers requeridos
| Header | Requerido | Descripción |
|---|---|---|
Authorization: Bearer <CREDENCIAL_DE_INTEGRACION> | Sí | Credencial de integración provisionada y habilitada por Payment Nexus. |
Content-Type: application/json | Sí | Cuerpo JSON. |
Idempotency-Key: <CLAVE_UNICA> | Sí | Clave única por orden/intento lógico de creación. |
Cuerpo JSON
| Campo | Tipo | Requerido | Descripción |
|---|---|---|---|
tenant_id | string | Sí | Asignado por Payment Nexus. |
merchant_id | string | Sí | Comercio asignado por Payment Nexus. |
branch_id | string | No | Sucursal asignada; úsala si tu integración opera por sucursal. |
amount_minor | integer | Sí | Monto en centavos MXN. Debe ser mayor a cero. |
currency | string | Sí | Debe ser MXN. |
description | string | Recomendado | Concepto visible/operativo del pago. |
required_3ds | boolean | No | Si se omite, la plataforma usa el valor seguro por defecto. |
is_permanent | boolean | No | false para links de una orden; true solo si Payment Nexus habilitó links permanentes para tu caso. |
expires_at | string RFC3339 | No | Fecha/hora de expiración, ejemplo 2026-10-06T23:59:00Z. |
notify_email | string email | No | Correo para notificaciones operativas del link, si está habilitado. |
Ejemplo de solicitud
Reemplaza los placeholders únicamente después de que Payment Nexus entregue el host final de API/checkout y la credencial de integración habilitada para tu ambiente.
{
"tenant_id": "<TENANT_ID_ASIGNADO>",
"merchant_id": "<MERCHANT_ID_ASIGNADO>",
"branch_id": "<BRANCH_ID_ASIGNADO>",
"amount_minor": 12345,
"currency": "MXN",
"description": "Orden ecommerce 100045",
"required_3ds": true,
"is_permanent": false,
"expires_at": "2026-10-06T23:59:00Z",
"notify_email": "operaciones@tu-comercio.example"
}
Ejemplo de respuesta exitosa
{
"id": "link_2a8f7b1c9d0e",
"tenant_id": "<TENANT_ID_ASIGNADO>",
"merchant_id": "<MERCHANT_ID_ASIGNADO>",
"branch_id": "<BRANCH_ID_ASIGNADO>",
"amount_minor": 12345,
"currency": "MXN",
"description": "Orden ecommerce 100045",
"status": "active",
"required_3ds": true,
"is_permanent": false,
"created_by": "usr_asignado",
"created_at": "2026-10-06T18:10:00Z",
"updated_at": "2026-10-06T18:10:00Z",
"expires_at": "2026-10-06T23:59:00Z",
"notify_email": "operaciones@tu-comercio.example",
"checkout_url": "https://<CHECKOUT_HOST_DE_LA_VPS>/checkout/link_2a8f7b1c9d0e",
"qr_code_png_base64": "iVBORw0KGgo..."
}
Si una creación se repite con la misma Idempotency-Key y el mismo payload lógico, Payment Nexus puede responder con el mismo link y el header:
Idempotency-Replayed: true
6. Idempotencia
Usa una clave estable por orden interna, por ejemplo:
orden-100045-link-v1
Recomendaciones:
- Reutiliza la misma clave si tu backend reintenta por timeout o error de red antes de saber si Payment Nexus creó el link.
- No reutilices la misma clave para una orden distinta.
- Si cambias monto, comercio, sucursal, moneda, expiración o descripción relevante, usa una clave nueva o espera un
409 Conflictpor conflicto de idempotencia. - Guarda en tu base de datos el
iddel link y lacheckout_urldevueltos por Payment Nexus.
7. Redirección vs iframe
Redirección recomendada
La integración más simple y recomendada es redirigir al comprador:
window.location.href = checkoutUrlFromYourBackend;
iframe
El iframe solo debe usarse si Payment Nexus confirmó que el checkout, encabezados de seguridad y dominio del comercio fueron revisados para ese flujo.
<iframe
src="https://<CHECKOUT_HOST_DE_LA_VPS>/checkout/link_2a8f7b1c9d0e"
title="Pago seguro Payment Nexus"
width="100%"
height="720"
style="border:0;"
allow="payment *"
></iframe>
Si usas iframe, tu sitio debe seguir sin recibir ni almacenar PAN/CVV. El comprador captura la tarjeta dentro del checkout de Payment Nexus.
8. Estados de link
| Estado | Significado |
|---|---|
active | Link creado y cobrable. |
processing | Existe un intento en proceso/reservado. No lo canceles ni lo reintentes agresivamente. |
paid | Link de un solo uso pagado exitosamente. |
canceled | Link cancelado por operación administrativa/API. |
expired | Link expirado por fecha configurada o regla de plataforma. |
Un timeout de tu sistema al crear no significa rechazo. Reintenta de forma idempotente con la misma clave y valida el resultado final con Payment Nexus/dash/admin durante pruebas iniciales, hasta que el API autenticado de estado/reconciliación esté habilitado para tu ambiente.
9. Resolución pública del checkout y estado final
Resolver datos públicos del link para checkout
GET https://<API_HOST_DE_LA_VPS>/f2c65bd1289pm/link/{link_id}
Este endpoint devuelve únicamente la forma pública del link para que el checkout renderice su contexto. Es información de resolución de checkout, no un endpoint autenticado/authoritative para el backend del comercio.
No lo uses como fuente de verdad para conciliación, cierre de orden, cumplimiento, antifraude ni estado final del pago. Puede responder 409 Conflict si el link ya no está activo o expiró, y no sustituye un API autenticado de estado/reconciliación.
Ejemplo:
curl -sS \
"https://<API_HOST_DE_LA_VPS>/f2c65bd1289pm/link/link_2a8f7b1c9d0e"
Estado final, conciliación y webhooks
Para esta integración rápida, después de que Payment Nexus habilite tu credencial servidor-a-servidor, no hay un endpoint adicional que debas invocar desde tu ecommerce además de POST /f2c65bd1289pm/link.
El API autenticado de estado/reconciliación y los webhooks de resultado están pendientes o siendo habilitados por Payment Nexus para tu ambiente. Durante las pruebas iniciales, el estado final del pago puede ser validado por nuestro equipo en Payment Nexus/dash/admin. No implementes polling contra el endpoint público de resolución como si fuera conciliación final.
10. Cancelación y administración posterior
La cancelación administrativa, la consulta autenticada de estado y la conciliación por API no forman parte de la integración rápida documentada aquí salvo confirmación explícita de Payment Nexus para tu ambiente.
Si necesitas cancelar links, conciliar automáticamente o cerrar órdenes sin validación manual, coordina con Payment Nexus la habilitación del API autenticado correspondiente y/o webhooks antes de liberar tu flujo en producción.
11. Errores comunes
| HTTP | Caso típico | Acción recomendada |
|---|---|---|
400 | JSON inválido, amount_minor faltante, moneda distinta a MXN, expires_at inválido, email inválido. | Corrige el payload. |
401 | Credencial ausente, inválida, expirada o todavía no habilitada. | Solicita/revisa activación de host y credencial por canal seguro. |
403 | Credencial sin permiso para tenant/comercio/sucursal. | Verifica alcance asignado por Payment Nexus. |
404 | Link no encontrado. | Confirma que guardaste el id correcto y que corresponde al ambiente. |
409 | Conflicto de idempotencia, límite de links activos, link no activo/reservado. | No generes duplicados automáticamente; valida con Payment Nexus si no tienes API autenticado de estado habilitado. |
500 | Error interno al crear. | Reintenta con la misma Idempotency-Key si aplica y reporta id/timestamp. |
Respuesta de error típica:
{
"error": "payment link create idempotency key is required"
}
12. Ejemplos
cURL
Reemplaza
<API_HOST_DE_LA_VPS>y<CREDENCIAL_DE_INTEGRACION_A_PROVISIONAR>solo después de que Payment Nexus proporcione el host final, la credencial de integración y confirme la activación.
curl -sS -X POST \
"https://<API_HOST_DE_LA_VPS>/f2c65bd1289pm/link" \
-H "Authorization: Bearer <CREDENCIAL_DE_INTEGRACION_A_PROVISIONAR>" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: orden-100045-link-v1" \
-d '{
"tenant_id": "<TENANT_ID_ASIGNADO>",
"merchant_id": "<MERCHANT_ID_ASIGNADO>",
"branch_id": "<BRANCH_ID_ASIGNADO>",
"amount_minor": 12345,
"currency": "MXN",
"description": "Orden ecommerce 100045",
"required_3ds": true,
"is_permanent": false
}'
Node.js
Configura
PNX_API_BASE_URLyPNX_INTEGRATION_CREDENTIALúnicamente con los valores finales entregados por Payment Nexus.
async function crearLinkDePago({orderId, amountMinor}) {
const response = await fetch(`${process.env.PNX_API_BASE_URL}/f2c65bd1289pm/link`, {
method: 'POST',
headers: {
'Authorization': `Bearer ${process.env.PNX_INTEGRATION_CREDENTIAL}`,
'Content-Type': 'application/json',
'Idempotency-Key': `orden-${orderId}-link-v1`,
},
body: JSON.stringify({
tenant_id: process.env.PNX_TENANT_ID,
merchant_id: process.env.PNX_MERCHANT_ID,
branch_id: process.env.PNX_BRANCH_ID,
amount_minor: amountMinor,
currency: 'MXN',
description: `Orden ecommerce ${orderId}`,
required_3ds: true,
is_permanent: false,
}),
});
const body = await response.json();
if (!response.ok) {
throw new Error(`Payment Nexus error ${response.status}: ${body.error || 'unknown'}`);
}
return body.checkout_url;
}
PHP
Configura
PNX_API_BASE_URLyPNX_INTEGRATION_CREDENTIALúnicamente con los valores finales entregados por Payment Nexus.
function crearLinkDePago(string $orderId, int $amountMinor): string {
$payload = [
'tenant_id' => getenv('PNX_TENANT_ID'),
'merchant_id' => getenv('PNX_MERCHANT_ID'),
'branch_id' => getenv('PNX_BRANCH_ID'),
'amount_minor' => $amountMinor,
'currency' => 'MXN',
'description' => 'Orden ecommerce ' . $orderId,
'required_3ds' => true,
'is_permanent' => false,
];
$ch = curl_init(rtrim(getenv('PNX_API_BASE_URL'), '/') . '/f2c65bd1289pm/link');
curl_setopt_array($ch, [
CURLOPT_POST => true,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . getenv('PNX_INTEGRATION_CREDENTIAL'),
'Content-Type: application/json',
'Idempotency-Key: orden-' . $orderId . '-link-v1',
],
CURLOPT_POSTFIELDS => json_encode($payload),
]);
$raw = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
$body = json_decode($raw, true);
if ($status < 200 || $status >= 300) {
throw new RuntimeException('Payment Nexus error ' . $status . ': ' . ($body['error'] ?? 'unknown'));
}
return $body['checkout_url'];
}
13. Checklist de seguridad
- La credencial de integración de Payment Nexus se guarda solo en variables de entorno/secret manager del backend.
- El frontend nunca recibe
Authorization: Bearer ...nitenant_id/merchant_idsi no los necesita. - La creación del link ocurre en servidor a servidor.
- Se usa HTTPS para API y checkout.
- Se usa
Idempotency-Keyestable por orden. - Los montos se calculan como enteros en centavos; no se usan floats.
- Solo se envía
currency: "MXN". - No se registran tokens, PAN, CVV, datos de autenticación ni respuestas completas con datos sensibles.
- Los timeouts se tratan como estado desconocido y se resuelven con reintento idempotente y/o validación con Payment Nexus, no como declinación automática.
- Hay conciliación entre
order_idinterno,link_idy estado final.
14. Casos de prueba para certificación
Después de que Payment Nexus confirme host/ruta final y credencial habilitada para tu ambiente, y antes de liberar en producción, ejecuta y documenta al menos:
- Crear link de una orden MXN con monto válido y redirigir al checkout.
- Reintentar creación con la misma
Idempotency-Keyy payload; debe retornar el mismo resultado lógico sin duplicar orden. - Reintentar con la misma
Idempotency-Keypero monto distinto; debe fallar con conflicto. - Enviar
currencydistinta deMXN; debe rechazarse. - Enviar
amount_minor0, negativo o no entero; debe rechazarse. - Abrir el checkout del link activo y validar que muestra el contexto correcto de pago.
- Validar con Payment Nexus/dash/admin el resultado final durante pruebas iniciales.
- Cuando Payment Nexus habilite APIs autenticados de estado/cancelación para tu ambiente, probar permisos y errores sin revelar datos de otro comercio.
- Simular timeout de creación y reintentar con la misma clave idempotente.
- Validar expiración si usas
expires_at. - Probar redirección de regreso a tu sitio si el checkout habilitado para tu ambiente lo requiere.
- Si se autoriza iframe, validar en navegador real que no hay bloqueo de seguridad y que tu sitio no recibe datos de tarjeta.
15. Ajustes pendientes del lado Payment Nexus
- El endpoint objetivo de creación es
POST /f2c65bd1289pm/link; Payment Nexus debe confirmar la ruta final habilitada en la VPS antes de que el comercio ejecute llamadas automatizadas. - Habilitar autenticación servidor-a-servidor para creación de links con
Authorization: Bearer <CREDENCIAL_DE_INTEGRACION>provisionada para el alcance tenant/comercio/sucursal correspondiente. - Confirmar el host final de API y el host final de checkout de la VPS por canal seguro.
- Habilitar o confirmar el API autenticado de estado/reconciliación antes de que el comercio cierre órdenes automáticamente sin validación manual.
- Definir y habilitar webhooks de resultado si el comercio los requiere para operación automática.
- Los endpoints públicos de checkout/resolución solo sirven para renderizar contexto del checkout; no sustituyen un API autenticado de estado/reconciliación ni son fuente de verdad para cerrar órdenes.
- El API autenticado de estado/reconciliación y los webhooks de resultado están pendientes o siendo habilitados por Payment Nexus; no dependas de ellos para esta integración rápida salvo confirmación explícita para tu ambiente.
- El host exacto de API, host exacto de checkout, credencial de integración y valores de
tenant_id/merchant_id/branch_idserán entregados por canal seguro. - Esta guía no incluye credenciales reales ni hashes de BasicAuth.