Acceso a manuales

Saltar al contenido principal

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.

Estado de habilitación: pendiente Payment Nexus

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.

Llamada solo desde backend

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​

  1. Tu backend recibe una orden de compra de tu ecommerce.
  2. Cuando Payment Nexus haya habilitado tu credencial y host final, tu backend crea un link de pago con POST /f2c65bd1289pm/link.
  3. Payment Nexus responde con checkout_url y los datos del link.
  4. Tu frontend redirige al comprador a esa URL o la muestra dentro de un iframe si el canal fue certificado para ello.
  5. 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_id y 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.

ConceptoValor
Documentaciónhttps://pnx-tutoriales.atidyarok.com
API basehttps://<API_HOST_DE_LA_VPS>
Checkout basehttps://<CHECKOUT_HOST_DE_LA_VPS>
Endpoint real de creaciónPOST /f2c65bd1289pm/link
Moneda soportadaMXN

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_id
  • merchant_id
  • branch_id cuando 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.


Endpoint​

POST https://<API_HOST_DE_LA_VPS>/f2c65bd1289pm/link

Headers requeridos​

HeaderRequeridoDescripción
Authorization: Bearer <CREDENCIAL_DE_INTEGRACION>SíCredencial de integración provisionada y habilitada por Payment Nexus.
Content-Type: application/jsonSíCuerpo JSON.
Idempotency-Key: <CLAVE_UNICA>SíClave única por orden/intento lógico de creación.

Cuerpo JSON​

CampoTipoRequeridoDescripción
tenant_idstringSíAsignado por Payment Nexus.
merchant_idstringSíComercio asignado por Payment Nexus.
branch_idstringNoSucursal asignada; úsala si tu integración opera por sucursal.
amount_minorintegerSíMonto en centavos MXN. Debe ser mayor a cero.
currencystringSíDebe ser MXN.
descriptionstringRecomendadoConcepto visible/operativo del pago.
required_3dsbooleanNoSi se omite, la plataforma usa el valor seguro por defecto.
is_permanentbooleanNofalse para links de una orden; true solo si Payment Nexus habilitó links permanentes para tu caso.
expires_atstring RFC3339NoFecha/hora de expiración, ejemplo 2026-10-06T23:59:00Z.
notify_emailstring emailNoCorreo 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 Conflict por conflicto de idempotencia.
  • Guarda en tu base de datos el id del link y la checkout_url devueltos 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.


EstadoSignificado
activeLink creado y cobrable.
processingExiste un intento en proceso/reservado. No lo canceles ni lo reintentes agresivamente.
paidLink de un solo uso pagado exitosamente.
canceledLink cancelado por operación administrativa/API.
expiredLink 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​

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​

HTTPCaso típicoAcción recomendada
400JSON inválido, amount_minor faltante, moneda distinta a MXN, expires_at inválido, email inválido.Corrige el payload.
401Credencial ausente, inválida, expirada o todavía no habilitada.Solicita/revisa activación de host y credencial por canal seguro.
403Credencial sin permiso para tenant/comercio/sucursal.Verifica alcance asignado por Payment Nexus.
404Link no encontrado.Confirma que guardaste el id correcto y que corresponde al ambiente.
409Conflicto 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.
500Error 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_URL y PNX_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_URL y PNX_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 ... ni tenant_id/merchant_id si no los necesita.
  • La creación del link ocurre en servidor a servidor.
  • Se usa HTTPS para API y checkout.
  • Se usa Idempotency-Key estable 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_id interno, link_id y 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:

  1. Crear link de una orden MXN con monto válido y redirigir al checkout.
  2. Reintentar creación con la misma Idempotency-Key y payload; debe retornar el mismo resultado lógico sin duplicar orden.
  3. Reintentar con la misma Idempotency-Key pero monto distinto; debe fallar con conflicto.
  4. Enviar currency distinta de MXN; debe rechazarse.
  5. Enviar amount_minor 0, negativo o no entero; debe rechazarse.
  6. Abrir el checkout del link activo y validar que muestra el contexto correcto de pago.
  7. Validar con Payment Nexus/dash/admin el resultado final durante pruebas iniciales.
  8. Cuando Payment Nexus habilite APIs autenticados de estado/cancelación para tu ambiente, probar permisos y errores sin revelar datos de otro comercio.
  9. Simular timeout de creación y reintentar con la misma clave idempotente.
  10. Validar expiración si usas expires_at.
  11. Probar redirección de regreso a tu sitio si el checkout habilitado para tu ambiente lo requiere.
  12. 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_id serán entregados por canal seguro.
  • Esta guía no incluye credenciales reales ni hashes de BasicAuth.