> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mesadepagos.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhooks

> Transaction status change notifications.

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](https://docs.mesadepagos.com/en/v3/auth.md) 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

```http theme={null}
POST /v3/webhooks
```

```json theme={null}
{
  "url": "https://partner.example.com/webhooks/yp",
  "description": "Primary webhook",
  "apiKey": "partner-secret",
  "status": "ACTIVE",
  "events": {
    "transaction": ["completed_transaction", "failed_transaction"]
  }
}
```

### Response

```json theme={null}
{
  "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

```http theme={null}
GET /v3/webhooks
```

### Response

```json theme={null}
[
  {
    "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

```http theme={null}
GET /v3/webhooks/{id}
```

### Response

```json theme={null}
{
  "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

```http theme={null}
PATCH /v3/webhooks/{id}
```

```json theme={null}
{
  "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

```json theme={null}
{
  "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"`:

```json theme={null}
{
  "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`

```json theme={null}
{
  "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`

```json theme={null}
{
  "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`

```json theme={null}
{
  "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

```http theme={null}
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

```json theme={null}
{
  "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

```text theme={null}
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](https://docs.mesadepagos.com/en/v3/api-reference/webhooks/crear-webhook.md) for request and response schemas.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.