Webhooks - ON RAMP by Mesadepagos

Los webhooks permiten recibir notificaciones cuando una transacción cambia de estado.

Crear Webhook

POST /v2/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 /v2/webhooks

Response

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

Obtener Webhook

GET /v2/webhooks/{id}

Response

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

Actualizar Webhook

PATCH /v2/webhooks/{id}

{
  "url": "https://partner.example.com/webhooks/yp-v2",
  "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-v2",
  "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 de cuentas virtuales nominadas generan notificaciones de transacción con este nuevo valor de transactionType. Este ejemplo muestra un cobro con datos del pagador registrados:

{
  "externalReference": "provider-collection-123",
  "status": "received_transaction",
  "transactionType": "deposit_virtual_account",
  "timestamp": "2026-09-23T16:42:27.302Z",
  "details": {
    "amount": "100.50",
    "currency": "EUR",
    "message": "Transaction 6d045d9d-398a-481e-9031-11a165dd91c7 updated to status received_transaction",
    "description": "Pago de factura 123",
    "transactionId": "6d045d9d-398a-481e-9031-11a165dd91c7",
    "payer": {
      "name": "Juan Perez",
      "documentNumber": "123456789",
      "accountNumber": "12345678900001",
      "bankCode": "1005",
      "bankName": "Banco de Credito"
    }
  }
}

details.amount es un string y details.currency contiene el código fiat. Si el evento del proveedor aún no llegó cuando se registra el cobro, la primera notificación puede traer amount: "0" y currency: "N/A"; consulta la transacción más tarde para obtener los datos de origen actualizados. Este tipo de webhook no incluye transactionHash. Puede incluir details.payer cuando la transacción tiene un detalle de pagador registrado; consulta Datos del pagador.

`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.

`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 /v2/webhooks/logs

Query Params

Parámetro	Requerido	Valores
`page`	No	Número de página
`limit`	No	Máximo 100
`status`	No	`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

​Crear Webhook

​Response

​Listar Webhooks

​Response

​Obtener Webhook

​Response

​Actualizar Webhook

​Response

​Payloads de Transacciones

​deposit_virtual_account

​withdrawal_crypto

​deposit_crypto

​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`

`withdrawal_crypto`

`deposit_crypto`

`deposit_express`

`withdrawal_express`

`withdrawal_ach`

Datos del pagador

Logs

Query Params

Response

Eventos Soportados