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.

Create a Webhook

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

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

Update a Webhook

PATCH /v2/webhooks/{id}

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

Virtual Account Transaction Payload

`deposit_virtual_account`

Named virtual account collections send transaction notifications with this transactionType. This example shows a collection with recorded payer details:

{
  "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": "Invoice 123 payment",
    "transactionId": "6d045d9d-398a-481e-9031-11a165dd91c7",
    "payer": {
      "name": "Juan Perez",
      "documentNumber": "123456789",
      "accountNumber": "12345678900001",
      "bankCode": "1005",
      "bankName": "Banco de Credito"
    }
  }
}

details.amount is a string, and details.currency contains the fiat code. If the provider event has not arrived when the collection is recorded, the first notification may contain amount: "0" and currency: "N/A"; retrieve the transaction later for updated source details. This webhook type does not include transactionHash. It may include details.payer when a payer detail is recorded for the transaction; see Payer details.

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

Query Parameters

Parameter	Required	Values
`page`	No	Page number
`limit`	No	Maximum 100
`status`	No	`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

​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