> ## 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

> Notificaciones de cambios de estado.

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

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

```json theme={null}
{
  "url": "https://partner.example.com/webhooks/yp",
  "description": "Webhook principal",
  "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": "Webhook principal",
  "events": ["completed_transaction", "failed_transaction"]
}
```

## Listar 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": "Webhook principal",
    "status": "ACTIVE"
  }
]
```

## Obtener 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": "Webhook principal",
  "status": "ACTIVE"
}
```

## Actualizar Webhook

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

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

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

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

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

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

### `withdrawal_express`

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

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

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

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

```text theme={null}
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](https://docs.mesadepagos.com/v3/api-reference/webhooks/crear-webhook.md) para los esquemas de request y response.


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