Webhooks - ON RAMP by Mesadepagos

Los webhooks permiten recibir notificaciones cuando una transacción cambia de estado. Webhooks v3 mantiene el mismo contrato de configuración y notificación que v2. Obtén un token con POST /v3/auth/login y envía Authorization: Bearer {accessToken} en los requests de configuración y consulta de logs. El campo url debe usar HTTPS con un nombre de dominio; no se aceptan direcciones IP ni dominios locales. Si configuras apiKey, se envía al receptor en el header x-api-key. status usa ACTIVE por defecto. Crear o actualizar un webhook devuelve HTTP 200.

Crear Webhook

POST /v3/webhooks

{
  "url": "https://partner.example.com/webhooks/yp",
  "description": "Webhook principal",
  "apiKey": "partner-secret",
  "status": "ACTIVE",
  "events": {
    "transaction": ["completed_transaction", "failed_transaction"]
  }
}

Response

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "url": "https://partner.example.com/webhooks/yp",
  "apiKey": "partner-secret",
  "description": "Webhook principal",
  "events": ["completed_transaction", "failed_transaction"]
}

Listar Webhooks

GET /v3/webhooks

Response

[
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "callbalckUrl": "https://partner.example.com/webhooks/yp",
    "events": {
      "transaction": ["completed_transaction", "failed_transaction"],
      "businessClient": []
    },
    "createdAt": "2026-05-12T12:00:00.000Z",
    "updatedAt": "2026-05-12T12:00:00.000Z",
    "description": "Webhook principal",
    "status": "ACTIVE"
  }
]

Obtener Webhook

GET /v3/webhooks/{id}

Response

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "callbalckUrl": "https://partner.example.com/webhooks/yp",
  "events": {
    "transaction": ["completed_transaction", "failed_transaction"],
    "businessClient": []
  },
  "createdAt": "2026-05-12T12:00:00.000Z",
  "updatedAt": "2026-05-12T12:00:00.000Z",
  "description": "Webhook principal",
  "status": "ACTIVE"
}

Actualizar Webhook

PATCH /v3/webhooks/{id}

{
  "url": "https://partner.example.com/webhooks/yp-updated",
  "description": "Webhook actualizado",
  "apiKey": "partner-secret",
  "status": "ACTIVE",
  "events": {
    "transaction": [
      "completed_transaction",
      "failed_transaction",
      "expired_transaction"
    ]
  }
}

Response

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "url": "https://partner.example.com/webhooks/yp-updated",
  "apiKey": "partner-secret",
  "description": "Webhook actualizado",
  "events": [
    "completed_transaction",
    "failed_transaction",
    "expired_transaction"
  ]
}

Payloads de Transacciones

details.description contiene la descripción del pago registrada para la transacción. Siempre es un string; si no hay una descripción de pago, se envía "". details.message informa el cambio de estado.

`deposit_virtual_account`

Los cobros recibidos en cuentas virtuales generan notificaciones de transacción con este valor de transactionType y status: "completed_transaction":

{
  "externalReference": "atc-va-3f1c9e0b7d...",
  "status": "completed_transaction",
  "transactionType": "deposit_virtual_account",
  "timestamp": "2026-10-27T16:42:27.302Z",
  "details": {
    "amount": "150",
    "currency": "BOB",
    "message": "Transaction 6d045d9d-398a-481e-9031-11a165dd91c7 updated to status completed_transaction",
    "description": "Pago factura 123",
    "transactionId": "6d045d9d-398a-481e-9031-11a165dd91c7",
    "achNumber": "14262610226819390312",
    "recipientNumber": "10187012210260072558",
    "payer": {
      "name": "JUAN PEREZ",
      "documentNumber": "7805522",
      "accountNumber": "1311638363",
      "bankCode": "018",
      "bankName": "BANCO GANADERO"
    }
  }
}

details.amount es un string y details.currency contiene el código fiat. Este tipo de webhook no incluye transactionHash. details.description es la glosa que escribió quien hizo la transferencia al enviarla desde su banco, tal como la informa el proveedor. No la define Mesa de Pagos ni el partner. Si el ordenante no escribió una glosa, se envía "". Siempre incluye estos campos:

Campo	Descripción
`details.achNumber`	Número de orden ACH del proveedor.
`details.recipientNumber`	Número de orden del destinatario del proveedor.

details.payer identifica a quien hizo la transferencia (el ordenante), con los datos que informa el proveedor:

Campo	Descripción
`payer.name`	Nombre del titular de la cuenta de origen.
`payer.documentNumber`	Documento de identidad (CI/NIT) del ordenante.
`payer.accountNumber`	Número de la cuenta de origen.
`payer.bankCode`	Código del banco de origen.
`payer.bankName`	Nombre del banco de origen. Se omite si no viene.

details.payer se omite si el proveedor no informa el nombre del ordenante.

Payloads de transacciones cripto

`withdrawal_crypto`

{
  "externalReference": "9dd9614e-5059-4cb5-826c-ef092fd99cb9",
  "status": "completed_transaction",
  "transactionType": "withdrawal_crypto",
  "timestamp": "2026-06-29T20:30:52.828Z",
  "details": {
    "amount": "100",
    "asset": "USDC",
    "blockchain": "Polygon",
    "transactionHash": "0x8f2a7d8dd74c53d68d7f8cfa6529370aa322f1b02a7d68cce8485b571735a9b1",
    "message": "Transaction 48942363-dc5f-47ec-baae-5628d814ccf6 updated to status completed_transaction",
    "description": "",
    "transactionId": "48942363-dc5f-47ec-baae-5628d814ccf6"
  }
}

`deposit_crypto`

{
  "status": "completed_transaction",
  "transactionType": "deposit_crypto",
  "timestamp": "2026-06-29T20:30:52.828Z",
  "details": {
    "walletId": "550e8400-e29b-41d4-a716-446655440001",
    "amount": "100",
    "asset": "USDC",
    "blockchain": "Polygon",
    "transactionHash": "0x8f2a7d8dd74c53d68d7f8cfa6529370aa322f1b02a7d68cce8485b571735a9b1",
    "message": "Transaction 48942363-dc5f-47ec-baae-5628d814ccf6 updated to status completed_transaction",
    "description": "",
    "transactionId": "48942363-dc5f-47ec-baae-5628d814ccf6"
  }
}

transactionHash se incluye cuando el proveedor blockchain lo informa y puede utilizarse para consultar la operación en el explorador de la red correspondiente.

Payloads de transacciones fiat

`deposit_express`

{
  "externalReference": "376e62a0-f586-4fd3-b30f-1fdb39df18cf",
  "status": "completed_transaction",
  "transactionType": "deposit_express",
  "timestamp": "2026-05-22T16:42:27.302Z",
  "details": {
    "amount": "102.102",
    "currency": "BOB",
    "message": "Transaction 6d045d9d-398a-481e-9031-11a165dd91c7 updated to status completed_transaction",
    "description": "Pago QR: Juan Perez",
    "transactionId": "6d045d9d-398a-481e-9031-11a165dd91c7",
    "payer": {
      "name": "Juan Perez",
      "documentNumber": "123456789",
      "accountNumber": "12345678900001",
      "bankCode": "1005",
      "bankName": "Banco de Credito"
    }
  }
}

`withdrawal_express`

{
  "externalReference": "5E3zOnTquFtzLJdh4IhNGT",
  "status": "completed_transaction",
  "transactionType": "withdrawal_express",
  "timestamp": "2026-05-22T19:10:19.377Z",
  "details": {
    "amount": "528.11",
    "currency": "BOB",
    "message": "Transaction ed27d250-1401-48fb-bf3a-3be276dd9b54 updated to status completed_transaction",
    "description": "Pago QR",
    "transactionId": "ed27d250-1401-48fb-bf3a-3be276dd9b54"
  }
}

`withdrawal_ach`

{
  "externalReference": "39f76d75-f80b-4d7c-a0b7-5e81a9dbe21a",
  "status": "completed_transaction",
  "transactionType": "withdrawal_ach",
  "timestamp": "2026-08-13T19:31:00.021Z",
  "details": {
    "amount": "20",
    "currency": "BOB",
    "message": "Transaction 99b95d27-2a1a-494b-8919-fa95b028db41 updated to status completed_transaction",
    "description": "Pago de factura 123",
    "transactionId": "99b95d27-2a1a-494b-8919-fa95b028db41"
  }
}

Datos del pagador

details.payer es opcional en deposit_express y deposit_virtual_account. Se incluye cuando la transacción tiene un detalle de pagador registrado; si no existe, se omite. Los demás tipos de transacción no incluyen este objeto.

Campo	Tipo	Descripción
`name`	`string`	Nombre del pagador.
`documentType`	`string` (opcional)	Tipo de documento, si se registró.
`documentNumber`	`string`	Número de documento del pagador.
`accountNumber`	`string`	Número de cuenta completo, sin enmascarar.
`bankCode`	`string`	Código del banco de origen.
`bankName`	`string` (opcional)	Nombre del banco, si está disponible.

El webhook de confirmación ATC v2 no informa documentType, por lo que ese campo puede faltar incluso cuando se incluye payer.

Logs

GET /v3/webhooks/logs

Query Params

Parámetro	Requerido	Valores
`page`	No	Número de página
`limit`	No	Máximo 100
`status`	No	`PENDING`, `SUCCESS`, `ERROR`
`webhookId`	No	UUID del webhook

Response

{
  "logs": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440010",
      "webhookId": "550e8400-e29b-41d4-a716-446655440000",
      "name": "Webhook principal",
      "webhookUrl": "https://partner.example.com/webhooks/yp",
      "status": "SUCCESS",
      "payload": {
        "event": "completed_transaction"
      },
      "statusCode": 200,
      "duration": 120,
      "retries": 0,
      "createdAt": "2026-05-12T12:00:00.000Z",
      "updatedAt": "2026-05-12T12:00:00.000Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 10,
    "total": 1,
    "totalPages": 1
  }
}

Eventos Soportados

pending_transaction
processing_transaction
completed_transaction
reject_transaction
failed_transaction
expired_transaction

Las suscripciones de transacciones usan events.transaction. Las notificaciones de clientes usan events.businessClient con business_client_status_updated. Al actualizar, las categorías de eventos omitidas conservan sus valores; envía un array vacío para limpiar una categoría. La paginación de logs usa page=1 y limit=10 por defecto, con un máximo de 100 en limit. Consulta la referencia API de Webhooks para los esquemas de request y response.

​Crear Webhook

​Response

​Listar Webhooks

​Response

​Obtener Webhook

​Response

​Actualizar Webhook

​Response

​Payloads de Transacciones

​deposit_virtual_account

​Payloads de transacciones cripto

​withdrawal_crypto

​deposit_crypto

​Payloads de transacciones fiat

​deposit_express

​withdrawal_express

​withdrawal_ach

​Datos del pagador

​Logs

​Query Params

​Response

​Eventos Soportados

Crear Webhook

Response

Listar Webhooks

Response

Obtener Webhook

Response

Actualizar Webhook

Response

Payloads de Transacciones

`deposit_virtual_account`

Payloads de transacciones cripto

`withdrawal_crypto`

`deposit_crypto`

Payloads de transacciones fiat

`deposit_express`

`withdrawal_express`

`withdrawal_ach`

Datos del pagador

Logs

Query Params

Response

Eventos Soportados