Webhooks y Callbacks

Los webhooks te permiten recibir notificaciones automáticas en tu servidor cuando ocurre un evento en PayCode, como un pago aprobado o un abono recibido. Para empezar a recibirlas, debes registrar la URL de tu servidor usando el endpoint de creación de callback.

Cómo funciona un webhook

Ocurre un evento

Por ejemplo, se completa un pago.

PayCode envía la notificación

PayCode envía una solicitud POST a la URL que registraste, con un payload en formato JSON.

Tu servidor responde

Tu servidor procesa la notificación y responde.

La mayoría de los webhooks se disparan solo cuando el evento se completa exitosamente.
Algunos eventos, como el pago en efectivo, envían más de una notificación por transacción, en distintos momentos del proceso (ver Pago en efectivo).
Si tu servidor no responde exitosamente, PayCode reintenta la entrega hasta 3 veces, con un intervalo de 1 hora entre cada intento enviando el mismo payload en cada reintento. Esta política aplica igual para todos los tipos de evento.
Tu endpoint debe retornar errores claros y específicos si algo sale mal al recibir la notificación. Un error 500 genérico no es suficiente para que el equipo de soporte de PayCode pueda diagnosticar el problema.

Tipos de evento disponibles

Cada callback que registres se asocia a un type_callback específico. El payload que recibe tu servidor depende del tipo de evento.

A diferencia de otras integraciones donde todos los eventos comparten una misma envoltura, aquí cada type_callback tiene su propia estructura de payload. Revisa la sección correspondiente antes de construir tu endpoint receptor.

`type_callback`	Evento
`payment_links`	Pago completado a través de un Payment Link
`spei`	Abono recibido por transferencia SPEI
`card`	Pago con tarjeta
`codi`	Pago recibido vía CoDi
`cie`	Pago en efectivo: confirmación (CIE / Practicaja)
`cash`	Cash in (tiendas de conveniencia)
`schedule_payment_valid_invoice_id`	Cobro programado / domiciliación

Payment Link

Se dispara cuando se completa un pago iniciado a través de un Payment Link o del Embebido.

{
  "success": true,
  "data": {
    "hash": "XNP-MRG-k1u",
    "paid_at": "2026-08-10-14-23-51",
    "amount_paid": 100.12,
    "status": "paid",
    "type_paid": "payment_links"
  },
  "hash": "XNP-MRG-k1u",
  "result_code": "00",
  "metadata": {
    "payment_id": "123456789",
    "payment_method": "payment_links",
    "currency": "MXN"
  }
}

Campo	Descripción
`data.hash` / `hash`	El hash usado durante la transacción
`data.paid_at`	Fecha y hora en que se completó el pago
`data.amount_paid`	Monto pagado
`data.status`	Estado del pago
`metadata`	Los mismos campos que se enviaron en `metadata` al crear el Payment Link

SPEI recibido

Se dispara cuando entra un abono a la CLABE del comercio.

{
  "numeroCuentaCliente": "012180001234567895",
  "cuentaBeneficiario": "646180110400000007",
  "concepto": "REF123456",
  "monto": "1500.00",
  "horaSolicitudMensajeCobro": "2026-08-10 14:30:15",
  "horaProcMensajeCobro": "2026-08-10 14:30:15",
  "clave_rastreo": "PAYCODE0000012345",
  "referenciaNumerica": "1234567",
  "metadata": {
    "nombreBeneficiario": "Elva Elf",
    "tipoCuentaBeneficiario": "Cta. Clabe",
    "tipoCuentaCliente": "Cta. Clabe",
    "nombreCliente": "Elva Elf",
    "rfcCurpCliente": "ELVE123456HDFRLL09",
    "rfcCurpBeneficiario": "ELVE123456HDFRLL09"
  }
}

Campo	Descripción
`numeroCuentaCliente`	Cuenta de origen del cliente que envió el abono
`cuentaBeneficiario`	CLABE del comercio que recibió el abono
`concepto`	Concepto de la transferencia
`monto`	Monto abonado. Nota: llega como string, no como número
`clave_rastreo`	Clave de rastreo del banco emisor
`referenciaNumerica`	Referencia numérica asociada a la transferencia
`metadata`	Metadata que tú defines al generar el cobro. En este ejemplo incluye `nombreBeneficiario`, `tipoCuentaBeneficiario`, `tipoCuentaCliente`, `nombreCliente`, `rfcCurpCliente` y `rfcCurpBeneficiario`

Cuando el abono se cruza contra un cobro SPEI previamente esperado, el payload incluye además el campo resultadoMensajeCobro, con el resultado de ese cruce de montos: pagado, incompleto o excedido.

Pago con tarjeta

Se dispara al completarse (o rechazarse) un pago con tarjeta.

{
  "success": true,
  "error": "",
  "display_message": "Aprobado",
  "reference_number": "178396333566",
  "track_code": "178396333566",
  "card_type": "CREDITO",
  "metadata": {
    "card_number": "411111****1111",
    "card_expiration": "12/2025",
    "card_holder_name": "Juan Perez"
  },
  "result_code": "00"
}

Campo	Descripción
`success`	`true` si la transacción fue aprobada
`display_message`	Mensaje del resultado, listo para mostrar al usuario
`reference_number`	Número de referencia de la transacción
`track_code`	Código de rastreo de la transacción
`card_type`	Tipo de tarjeta usada (`CREDITO`, `DEBITO`)
`metadata`	Metadata que tú defines al generar el cobro. En este ejemplo incluye `card_number` (enmascarado), `card_expiration` y `card_holder_name`
`error`	Detalle del error, si la transacción fue rechazada. Viene vacío cuando el pago es exitoso
`result_code`	Código de resultado de la transacción

Si el cliente solicitó guardar su tarjeta para futuros pagos, el payload incluye además token_card con el token generado, o token_error si la tokenización falló.

CoDi

Se dispara cuando se recibe un pago a través de CoDi.

{
  "numeroCuentaCliente": "012180001234567895",
  "concepto": "REF123456",
  "monto": "500.00",
  "resultadoMensajeCobro": "PAGADO",
  "horaSolicitudMensajeCobro": "2026-08-10 14:30:15",
  "horaProcMensajeCobro": "2026-08-10 14:30:18",
  "clave_rastreo": "TRK0000998877",
  "order_id": "ORD-4455"
}

Campo	Descripción
`numeroCuentaCliente`	Cuenta de origen del pago
`concepto`	Concepto del cobro
`monto`	Monto pagado. Llega como string
`resultadoMensajeCobro`	Resultado del cobro
`clave_rastreo`	Clave de rastreo del banco
`order_id`	Identificador de la orden asociado al cobro

Pago en efectivo

El pago en efectivo en cajero (también conocido internamente como CIE o Practicaja) genera dos notificaciones distintas para la misma transacción, en dos momentos diferentes del proceso.

El webhook de confirmación se dispara cuando el banco notifica el pago a PayCode, no necesariamente en el instante exacto en que el cliente paga en el cajero. Puede haber un desfase entre el momento real del pago y el momento en que tu servidor recibe la confirmación.

Registro y Confirmación no son dos suscripciones distintas: ambos se reciben bajo el mismo type_callback: cie. Solo necesitas registrar un callback para recibir las dos notificaciones de una misma transacción.

1. Registro

Se dispara cuando el cliente genera su referencia de pago (por ejemplo, al abrir el link de pago y elegir “Efectivo”), antes de que el pago se realice. En este punto el dinero todavía no ha sido cobrado.

La estructura de este payload es distinta a la del webhook de Confirmación porque, además de la información del pago (payment), este evento también incluye información del link de pago asociado.

{
  "request": {
    "success": true,
    "data": {
      "hash": "NFQ-jdc-GoZ",
      "customer_alias": "131_603298",
      "payment": {
        "id": "1",
        "status": "register",
        "amount": "52.00",
        "currency": "MXN",
        "paid_at": "2025-05-07 04:18:10",
        "external_request_id": "",
        "external_client_id": "PAY1746551689",
        "value": ""
      },
      "metadata": ""
    }
  },
  "response": null
}

Campo	Descripción
`data.hash`	Hash asociado a la transacción o link de pago
`data.customer_alias`	Alias o identificador del cliente que generó la referencia
`data.payment.id`	Identificador interno del pago
`data.payment.status`	Siempre `register` en este evento
`data.payment.amount`	Monto a pagar
`data.payment.paid_at`	Fecha y hora en que se generó la referencia (no la fecha de pago)
`data.payment.external_client_id`	Identificador del cliente en el sistema externo de efectivo
`data.metadata`	Metadata asociada a la transacción, si existe

El campo metadata está presente en la estructura del payload, pero en este evento normalmente no se utiliza.

No uses este webhook para marcar un pedido como pagado. Solo indica que el cliente generó su referencia, no que el dinero ya fue recibido. Usa el webhook de Confirmación para eso.

2. Confirmación

Se dispara cuando el pago ya fue cobrado y el banco lo notificó a PayCode. Este es el webhook que debes usar para confirmar que el dinero fue recibido.

{
  "request": {
    "success": true,
    "data": {
      "reference": "TRAVEPAYM262402NFQJ9",
      "paid_at": "2026-12-31 18:00:00",
      "amount_paid": 3050,
      "status": "Pagado",
      "type_paid": "cie",
      "payment_method": "Efectivo"
    },
    "hash": "NFQ-jdc-GoZ",
    "alias": "131_603298"
  },
  "response": null
}

Campo	Descripción
`data.reference`	Referencia del pago asignada por el banco o el sistema de cobro
`data.paid_at`	Fecha y hora en que se confirmó el pago
`data.amount_paid`	Monto pagado
`data.status`	Estado del pago (`Pagado`)
`data.type_paid`	Tipo de pago confirmado (`cie`)
`hash`	El mismo `hash` recibido en el webhook de Registro, útil para relacionar ambas notificaciones
`alias`	Alias o identificador del cliente. Corresponde al mismo valor recibido como `customer_alias` en el webhook de Registro

El valor de status no está homologado entre estos dos eventos: en la Confirmación llega en español ("Pagado"), tal como se solicitó originalmente para este evento. En el Registro llega en inglés ("confirmed"). Esto es una inconsistencia conocida, pendiente de homologar por el equipo de ingeniería.

Cash in (tiendas de conveniencia)

Se dispara cuando se confirma un pago realizado en efectivo en una tienda de conveniencia afiliada (por ejemplo OXXO).

{
  "request": {
    "success": true,
    "data": {
      "monto": "1.0",
      "concepto": "Pago de cash in",
      "clave_rastreo": "000000000047039572",
      "numeroCuentaCliente": "23442",
      "horaProcMensajeCobro": "2026-02-02 13:00:00",
      "resultadoMensajeCobro": "PAGADO",
      "horaSolicitudMensajeCobro": "2026-02-02 13:00:00"
    }
  }
}

Campo	Descripción
`data.monto`	Monto pagado
`data.concepto`	Concepto del pago
`data.clave_rastreo`	Clave de rastreo de la transacción
`data.numeroCuentaCliente`	Alias o identificador del cliente
`data.resultadoMensajeCobro`	Resultado del cobro: `PAGADO` o `RECHAZADO`

Cobro programado / domiciliación

Se dispara en cada intento de cobro de una domiciliación programada.

{
  "id": 8877,
  "montoCargo": "299.00",
  "fechaCargo": "2026-08-10",
  "reintentos": "01",
  "codigoAutorizacion": "123456",
  "codigoResultado": "00",
  "mensajeDescripcion": "Aprobado"
}

Campo	Descripción
`id`	Identificador del cobro programado
`montoCargo`	Monto cobrado en este intento
`fechaCargo`	Fecha en la que se ejecutó el cargo
`reintentos`	Número de intento de cobro (`01`, `02`, etc.)
`codigoAutorizacion`	Código de autorización del banco, si fue aprobado
`codigoResultado`	Código de resultado del cargo
`mensajeDescripcion`	Descripción del resultado, lista para mostrar al usuario

Buenas prácticas para tu endpoint receptor

Responde rápido. Guarda la notificación (por ejemplo en una cola o en tu base de datos) y procesa la lógica de negocio después, en vez de hacer todo el trabajo pesado antes de responder.
Valida que los campos esperados existan antes de usarlos; no asumas que un campo opcional (como metadata o token_card) siempre estará presente.
Usa un identificador único para evitar procesar el mismo evento dos veces, por ejemplo hash, reference_number o clave_rastreo según el tipo de evento.
En pagos de efectivo, distingue el webhook de registro del de confirmación (ver Pago en efectivo) y marca un pedido como pagado únicamente con el segundo.
Registra (log) cada notificación recibida, incluyendo las que no pudiste procesar, para facilitar el diagnóstico si algo falla.

Administrar tus callbacks

Estos son los endpoints para registrar, consultar, modificar y eliminar los callbacks de tu negocio.

Obtener callback

Consulta la información de un callback registrado. Método: GET Endpoint: /Api/v2/hook/get Header requerido: Authorization: Bearer {token}

integer

required

Identificador del callback a consultar

Ejemplo de request:

curl -G {{url}}Api/v2/hook/get \
     --data-urlencode "id=43"

Crear callback

Registra una nueva URL donde PayCode enviará las notificaciones de los eventos configurados. Método: POST Endpoint: /Api/v2/hook/create Header requerido: Authorization: Bearer {token}

string

required

URL de tu servidor donde PayCode enviará las notificaciones

string

required

Tipo de evento que disparará la notificación. Ver tipos de evento disponibles

Ejemplo de request:

{
  "url": "https://tuservidor.com/paycode/webhook",
  "type_callback": "schedule_payment_valid_invoice_id"
}

Ejemplo de respuesta 200 OK:

{
  "success": true,
  "message": "La ruta se creó correctamente"
}

Actualizar callback

Modifica la URL o el tipo de evento de un callback existente. Método: PUT Endpoint: /Api/v2/hook/update Header requerido: Authorization: Bearer {token}

integer

required

Identificador del callback a actualizar

string

required

Nueva URL donde PayCode enviará las notificaciones

string

required

Nuevo tipo de evento

Ejemplo de request:

{
  "id": 96,
  "url": "https://tuservidor.com/paycode/webhook",
  "type_callback": "card"
}

Eliminar callback

Elimina un callback registrado. PayCode dejará de enviar notificaciones a esa URL. Método: DELETE Endpoint: /Api/v2/hook/delete Header requerido: Authorization: Bearer {token}

integer

required

Identificador del callback a eliminar

Ejemplo de request:

{
  "id": 1
}

Esta acción es irreversible. Una vez eliminado el callback PayCode dejará de enviar notificaciones a esa URL.

Reenviar notificación

Reenvía una notificación de un evento que ya ocurrió. Útil cuando tu servidor no recibió correctamente la notificación original. Método: POST Endpoint: /api/v2/internal/callback/resendnotificacion Header requerido: Authorization: Bearer {token}

integer

required

Identificador de tu negocio en PayCode

string

required

Tipo de evento cuya notificación quieres reenviar

Ejemplo de request:

{
  "business_info": 25958,
  "type_callback": "payment_links"
}

COMIENZA AQUÍ

INTEGRACIONES FRONTEND

INTEGRACIONES BACKEND V2

CASOS DE USO

Cómo funciona un webhook

Tipos de evento disponibles

Payment Link

SPEI recibido

Pago con tarjeta

CoDi

Pago en efectivo

1. Registro

2. Confirmación

Cash in (tiendas de conveniencia)

Cobro programado / domiciliación

Buenas prácticas para tu endpoint receptor

Administrar tus callbacks

Obtener callback

Crear callback

Actualizar callback

Eliminar callback

Reenviar notificación

​Cómo funciona un webhook

​Tipos de evento disponibles

​Payment Link

​SPEI recibido

​Pago con tarjeta

​CoDi

​Pago en efectivo

​1. Registro

​2. Confirmación

​Cash in (tiendas de conveniencia)

​Cobro programado / domiciliación

​Buenas prácticas para tu endpoint receptor

​Administrar tus callbacks

​Obtener callback

​Crear callback

​Actualizar callback

​Eliminar callback

​Reenviar notificación

Cómo funciona un webhook

Tipos de evento disponibles

Payment Link

SPEI recibido

Pago con tarjeta

CoDi

Pago en efectivo

1. Registro

2. Confirmación

Cash in (tiendas de conveniencia)

Cobro programado / domiciliación

Buenas prácticas para tu endpoint receptor

Administrar tus callbacks

Obtener callback

Crear callback

Actualizar callback

Eliminar callback

Reenviar notificación