Webhooks - ON RAMP by Mesadepagos

Webhooks notify your application when a transaction changes status. In every transaction notification, details.description contains the payment description recorded for that transaction. It is always a string and is "" when no payment description is available. details.message reports the status change. Webhooks v3 keeps the same configuration and notification contract as v2. Get a token with POST /v3/auth/login and send Authorization: Bearer {accessToken} with configuration and log requests. The callback url must use HTTPS with a domain name; IP addresses and local domains are not accepted. If configured, apiKey is sent to your receiver in the x-api-key header. status defaults to ACTIVE. Creating or updating a webhook returns HTTP 200.

Create a Webhook

POST /v3/webhooks

{
  "url": "https://partner.example.com/webhooks/yp",
  "description": "Primary webhook",
  "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": "Primary webhook",
  "events": ["completed_transaction", "failed_transaction"]
}

List 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": "Primary webhook",
    "status": "ACTIVE"
  }
]

Retrieve a 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": "Primary webhook",
  "status": "ACTIVE"
}

Update a Webhook

PATCH /v3/webhooks/{id}

{
  "url": "https://partner.example.com/webhooks/yp-updated",
  "description": "Updated webhook",
  "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": "Updated webhook",
  "events": [
    "completed_transaction",
    "failed_transaction",
    "expired_transaction"
  ]
}

Virtual Account Transaction Payload

`deposit_virtual_account`

Collections received in virtual accounts send transaction notifications with this transactionType and 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": "Invoice 123 payment",
    "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 is a string, and details.currency contains the fiat code. This webhook type does not include transactionHash. details.description is the transfer note written by the sender when sending the transfer from their bank, as reported by the provider. It is not set by Mesa de Pagos or the partner. If the sender did not write a note, "" is sent. It always includes these fields:

Field	Description
`details.achNumber`	Provider ACH order number.
`details.recipientNumber`	Provider recipient order number.

details.payer identifies who sent the transfer, using the data reported by the provider:

Field	Description
`payer.name`	Source account holder name.
`payer.documentNumber`	Sender identity document (CI/NIT).
`payer.accountNumber`	Source account number.
`payer.bankCode`	Source bank code.
`payer.bankName`	Source bank name. Omitted when not provided.

details.payer is omitted if the provider does not report the sender’s name.

Deposit Express Transaction Payload

`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"
    }
  }
}

Payer details

details.payer is optional for deposit_express and deposit_virtual_account. It is included when a payer detail is recorded for the transaction and omitted otherwise. Other transaction types do not include this object.

Field	Type	Description
`name`	`string`	Payer name.
`documentType`	`string` (optional)	Document type, when recorded.
`documentNumber`	`string`	Payer document number.
`accountNumber`	`string`	Full, unmasked account number.
`bankCode`	`string`	Origin bank code.
`bankName`	`string` (optional)	Bank name, when available.

The ATC v2 confirmation webhook does not provide documentType, so this field may be absent even when payer is included.

Crypto Transaction Payloads

`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 is included when the blockchain provider supplies it and can be used to look up the operation in the corresponding network explorer.

Logs

GET /v3/webhooks/logs

Query Parameters

Parameter	Required	Values
`page`	No	Page number
`limit`	No	Maximum 100
`status`	No	`PENDING`, `SUCCESS`, `ERROR`
`webhookId`	No	Webhook UUID

Response

{
  "logs": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440010",
      "webhookId": "550e8400-e29b-41d4-a716-446655440000",
      "name": "Primary webhook",
      "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
  }
}

Supported Events

pending_transaction
processing_transaction
completed_transaction
reject_transaction
failed_transaction
expired_transaction

Transaction subscriptions use events.transaction. Business client notifications use events.businessClient with business_client_status_updated. On update, omitted subscription categories keep their existing values; send an empty array to clear a category. Log pagination defaults to page=1 and limit=10, with a maximum limit of 100. See the Webhooks API reference for request and response schemas.

​Create a Webhook

​Response

​List Webhooks

​Response

​Retrieve a Webhook

​Response

​Update a Webhook

​Response

​Virtual Account Transaction Payload

​deposit_virtual_account

​Deposit Express Transaction Payload

​deposit_express

​Payer details

​Crypto Transaction Payloads

​withdrawal_crypto

​deposit_crypto

​Logs

​Query Parameters

​Response

​Supported Events

Create a Webhook

Response

List Webhooks

Response

Retrieve a Webhook

Response

Update a Webhook

Response

Virtual Account Transaction Payload

`deposit_virtual_account`

Deposit Express Transaction Payload

`deposit_express`

Payer details

Crypto Transaction Payloads

`withdrawal_crypto`

`deposit_crypto`

Logs

Query Parameters

Response

Supported Events