> ## 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.
# Payout
> Envío de pagos de salida por ACH, QR o PIX.
El módulo Payout permite enviar pagos de salida por ACH, procesar pagos mediante QR y realizar pagos instantáneos PIX hacia Brasil.
## Endpoints
| Nombre | Método | Ruta |
| --------------- | ------ | ------------------------------------------------- |
| Payout ACH | `POST` | `/v2/transactions/payouts/bank` |
| Payout ACH v3 | `POST` | `/v3/transactions/payouts/bank` |
| Payout Wallets | - | próximamente |
| Payout Crypto | `POST` | `/v2/transactions/payouts/crypto` |
| Payout PIX | `POST` | `/v2/transactions/payouts/pix` |
| Payout QR | `POST` | `/v2/transactions/payouts/qr` |
| Validación QR | `POST` | `/v2/transactions/payouts/validate/qr` |
| Lista de Bancos | `GET` | `/v2/transactions/payouts/bank/banks` |
## Payout ACH
Disponible para cuentas bancarias de los siguientes países, con nuevas coberturas próximamente:
| Código | País | Disponibilidad |
| ------ | ---------- | ------------------------------------------------- |
| `BO` | Bolivia | Disponible |
| `BR` | Brasil | Disponible |
| `CO` | Colombia | Disponible |
| `CL` | Chile | Disponible |
| `PE` | Perú | Disponible |
| `UY` | Uruguay | Próximamente |
| `CR` | Costa Rica | Próximamente |
| `PY` | Paraguay | Próximamente |
| `PA` | Panamá | Próximamente |
| `CN` | China | Próximamente |
Para los países disponibles, el campo `transaction.country` debe enviarse con el código ISO alpha-2 correspondiente.
```http theme={null}
POST /v2/transactions/payouts/bank
```
En v2 el nombre completo del titular se envía en `transaction.destination_holder`. Los campos `first_name` y `last_name` pueden enviarse de forma opcional.
```json theme={null}
{
"funding_source": "conversion",
"external_reference": "550e8400-e29b-41d4-a716-446655440000",
"asset_deposit": "USDC",
"refund_address": "0x0000000000000000000000000000000000000000",
"blockchain": "Polygon",
"transaction": {
"country": "BO",
"entity_type": "individual",
"amount": 100.5,
"bank_code": "101",
"description": "Pago proveedor",
"destination_account": "1234567890",
"destination_holder": "Juan Pérez",
"first_name": "Juan",
"last_name": "Pérez",
"document_type": "national_id",
"destination_id_number": "1234567",
"currency_type": "BOB"
}
}
```
### Response
```json theme={null}
{
"transaction_id": "550e8400-e29b-41d4-a716-446655440001",
"external_reference": "550e8400-e29b-41d4-a716-446655440000",
"deposit_address": "0x0000000000000000000000000000000000000000",
"amount_deposit": "14.44",
"transactions": [
{
"transaction_id": "550e8400-e29b-41d4-a716-446655440002",
"status": "pending_transaction",
"message": "Transaction created"
}
]
}
```
```http theme={null}
POST /v3/transactions/payouts/bank
```
En v3, `external_reference` es obligatorio y acepta una referencia de texto definida por el partner; no necesita tener formato UUID v4. `transaction.first_name` siempre es obligatorio. `transaction.last_name` es obligatorio cuando `transaction.entity_type` es `individual`, pero puede omitirse cuando es `company`; en ese caso, envía la razón social en `first_name`. El endpoint forma internamente el nombre completo con los campos proporcionados. Además, `transaction.currency_type` soporta `BOB`, `USD`, `CLP` y `PEN`.
```json theme={null}
{
"funding_source": "conversion",
"external_reference": "ORDER-ACH-20260720-001",
"asset_deposit": "USDC",
"refund_address": "0x0000000000000000000000000000000000000000",
"blockchain": "Polygon",
"transaction": {
"country": "BO",
"entity_type": "individual",
"amount": 100.5,
"bank_code": "101",
"description": "Pago proveedor",
"destination_account": "1234567890",
"first_name": "Juan",
"last_name": "Pérez",
"document_type": "national_id",
"destination_id_number": "1234567",
"currency_type": "BOB"
}
}
```
### Response
```json theme={null}
{
"transaction_id": "550e8400-e29b-41d4-a716-446655440001",
"external_reference": "ORDER-ACH-20260720-001",
"deposit_address": "0x0000000000000000000000000000000000000000",
"amount_deposit": "14.44",
"transactions": [
{
"transaction_id": "550e8400-e29b-41d4-a716-446655440002",
"status": "pending_transaction",
"message": "Transaction created"
}
]
}
```
## Payout Wallets próximamente
Payout Wallets permite enviar payouts directamente a wallets digitales disponibles por país.
* PREXPE
* YAPE
* LUQEA
* DALE
* DAVIPLATA
* DING TECNIPAGOS SA
* GIROS Y FINANZAS CF
* IRIS
* MOVII
* NEQUI
* PIBANK
* POWWI
* RAPPIPAY
* UALÁ
## Payout PIX
```http theme={null}
POST /v2/transactions/payouts/pix
```
Permite realizar pagos instantáneos en `BRL` hacia Brasil. El payout admite dos modalidades de fondeo:
* `balance`: envía la operación directamente al proveedor con el balance habilitado para el partner.
* `conversion`: devuelve una dirección y un monto cripto que deben fondearse antes de ejecutar el PIX.
### Request
```json theme={null}
{
"funding_source": "conversion",
"external_reference": "3c68c080-9f72-4fdd-a6f4-b4e59efa05f5",
"asset_deposit": "USDC",
"blockchain": "Polygon",
"transaction": {
"amount": 100.5,
"description": "Pago proveedor Brasil",
"first_name": "Joao",
"last_name": "Silva",
"document_type": "CPF",
"document_number": "12345678909",
"currency_type": "BRL"
},
"clavePix": {
"Email": "joao.silva@example.com"
}
}
```
`clavePix` debe contener exactamente una de estas claves:
| Clave | Formato |
| ---------- | --------------------------------------- |
| `Document` | CPF de 11 dígitos o CNPJ de 14 dígitos. |
| `Email` | Correo electrónico válido. |
| `Phone` | Número iniciado en `+55`. |
| `Random` | Clave aleatoria en formato UUID. |
| `Commerce` | CNPJ de 14 dígitos. |
La respuesta contiene la dirección y el monto cripto que deben depositarse:
```json theme={null}
{
"transaction_id": "550e8400-e29b-41d4-a716-446655440020",
"external_reference": "3c68c080-9f72-4fdd-a6f4-b4e59efa05f5",
"deposit_address": "0x2222222222222222222222222222222222222222",
"amount_deposit": "19.85"
}
```
Deposita exactamente `amount_deposit` del asset seleccionado en
`deposit_address`, sobre la blockchain indicada.
La respuesta contiene el identificador y estado inicial del payout:
```json theme={null}
{
"transaction_id": "550e8400-e29b-41d4-a716-446655440021",
"external_reference": "9a84c1c5-0918-41cb-b163-e033d119f580",
"payout_id": "123456789",
"status": "PROCESSING"
}
```
Este flujo no devuelve `deposit_address` ni `amount_deposit`.
Los cambios de estado se notifican como `withdrawal_pix`. Consulta [Webhooks](/webhooks) para configurar el endpoint receptor.
## Payout QR
Usa este endpoint para procesar un QR de payout.
```json theme={null}
{
"asset_deposit": "USDC",
"blockchain": "Polygon",
"funding_source": "conversion",
"image": "qr-text-or-image-payload",
"external_reference": "ORDER-QR-1001",
"amount": 100
}
```
### Response
```json theme={null}
{
"external_reference": "ORDER-QR-1001",
"amount_deposit": "14.44",
"deposit_address": "0x0000000000000000000000000000000000000000",
"transactions": {
"transaction_id": "550e8400-e29b-41d4-a716-446655440002",
"status": "pending_transaction",
"message": "Payout QR processed successfully"
}
}
```
## Validación QR
Usa este endpoint para decodificar una imagen QR en base64 y validar su información.
```json theme={null}
{
"image": "iVBORw0KGgoAAAANSUhEUgAA..."
}
```
### Response Exitoso
```json theme={null}
{
"code": 200,
"message": "QR code scanned successfully",
"details": {
"titularDestino": "Juan Pérez",
"cuentaDestino": "1234567890",
"ciNitDestino": "1234567",
"nombreBancoDestino": "Banco Ejemplo",
"codigoBancoDestino": "101",
"moneda": "BOB",
"monto": 100.5,
"glosa": "Pago proveedor",
"numeroReferencia": "123456789",
"fechaVencimiento": "2026-05-13T23:59:59.000Z"
}
}
```
### Response Cuando el QR No Puede Procesarse
```json theme={null}
{
"code": null,
"message": "The provided QR code is invalid or could not be processed."
}
```
## Lista de Bancos
```http theme={null}
GET /v2/transactions/payouts/bank/banks?country=BO
```
### Query Params
| Campo | Tipo | Requerido | Default | Descripción |
| --------- | ------ | --------- | ------- | -------------------------------------------------- |
| `country` | string | No | `BO` | Código ISO alpha-2 del país para consultar bancos. |
```json theme={null}
{
"banks": [
{
"code": "101",
"name": "Banco Ejemplo"
}
]
}
```