> ## 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ía pagos bancarios y QR con la API v3.

Autentícate con [POST /v3/auth/login](https://docs.mesadepagos.com/v3/auth.md) y envía `Authorization: Bearer {accessToken}` en cada request. Los payouts bancarios usan campos en `snake_case`; los payouts QR usan `camelCase`.

## Endpoints

| Nombre | Método | Ruta |
| - | - | - |
| Payout ACH | `POST` | `/v3/transactions/payouts/bank` |
| Payout ACH por lote | `POST` | `/v3/transactions/payouts/bank/batch` |
| Estado de payout bancario | `GET` | `/v3/transactions/payouts/bank/status/{transactionId}` |
| Validación QR | `POST` | `/v3/transactions/payouts/validate/qr` |
| Payout QR | `POST` | `/v3/transactions/payouts/qr` |
| Lista de bancos | `GET` | `/v3/transactions/payouts/bank/banks` |

Consulta [Payout Crypto](https://docs.mesadepagos.com/v3/payout-crypto.md) para transferencias entre wallets.

## Payout ACH

Usa `funding_source: "balance"` para fondear el pago con el saldo del partner o `"conversion"` para recibir una dirección y un monto de depósito cripto. `asset_deposit` usa `USDC` por defecto y `blockchain` usa `Polygon`.

```http theme={null}
POST /v3/transactions/payouts/bank
```

`transaction.destination_account` debe enviarse como texto y no puede contener guiones bajos (`_`), guiones (`-`) ni espacios en blanco, incluidos tabulaciones y saltos de línea. Esta validación aplica a todos los países; los formatos IBAN de Costa Rica (`CR`) y Guatemala (`GT`) conservan sus prefijos. Los valores inválidos se rechazan con HTTP `400`.

`transaction.entity_type`, `transaction.first_name` y `transaction.document_type` son obligatorios. `last_name` es obligatorio para `individual` y opcional para `company`. El titular se forma con `first_name` y `last_name`. Las monedas aceptadas son `BOB`, `USD`, `CLP`, `PEN` y `COP`; su disponibilidad depende del corredor habilitado. Las reglas de validación del documento y de la cuenta también dependen del país de destino. Consulta los detalles en la referencia API.

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

Un payout con una transacción en `processing_transaction` devuelve HTTP `202`; en los demás casos, una creación exitosa devuelve HTTP `201`. La creación no confirma la liquidación. [Consulta la referencia API de ACH](https://docs.mesadepagos.com/v3/api-reference/payout/payout-ach.md).

## Pagos por lote y estado

Consulta [Payout ACH por lote](https://docs.mesadepagos.com/v3/payout-batch.md) para el request, las autorizaciones parciales y la consulta de estado. El lote usa el saldo del partner y mantiene los campos en `snake_case`.

## Validación QR

```http theme={null}
POST /v3/transactions/payouts/validate/qr
```

Envía la imagen QR completa en base64 puro, sin el prefijo `data:image`. Reemplaza el valor abreviado de este ejemplo por la imagen completa.

```json theme={null}
{
  "image": "iVBORw0KGgoAAAANSUhEUgAA..."
}
```

### Respuesta: HTTP 201

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

El cuerpo de respuesta contiene `code: 200` cuando el escaneo es exitoso. Las imágenes inválidas se rechazan con HTTP `400`. [Referencia API de validación QR](https://docs.mesadepagos.com/v3/api-reference/payout/validacion-qr.md).

## Payout QR

```http theme={null}
POST /v3/transactions/payouts/qr
```

`fundingSource`, `externalReference` (1–32 caracteres) e `image` son obligatorios. `amount` es obligatorio con `conversion`; si se envía, debe ser positivo y múltiplo de `0.01`. Envía un monto suficiente para cubrir el pago QR. `assetDeposit` usa `USDC` por defecto y `blockchain` usa `Polygon`. La imagen usa el mismo formato base64 puro que la validación QR.

```json theme={null}
{
  "fundingSource": "conversion",
  "externalReference": "ORDER-QR-1001",
  "assetDeposit": "USDC",
  "blockchain": "Polygon",
  "image": "iVBORw0KGgoAAAANSUhEUgAA...",
  "amount": 100
}
```

### Respuesta: HTTP 201

```json theme={null}
{
  "externalReference": "ORDER-QR-1001",
  "amountDeposit": "14.44",
  "depositAddress": "0x0000000000000000000000000000000000000000",
  "transactions": {
    "transactionId": "550e8400-e29b-41d4-a716-446655440002",
    "status": "pending_transaction",
    "message": "Transaction created successfully"
  }
}
```

Con `conversion`, fondea `depositAddress` con `amountDeposit` del asset seleccionado en la blockchain indicada. Con `balance`, el pago usa el saldo del partner y los campos de depósito son `null`. [Referencia API de payout QR](https://docs.mesadepagos.com/v3/api-reference/payout/payout-qr.md).

## Lista de bancos

```http theme={null}
GET /v3/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"
    }
  ]
}
```

## Errores

Los errores de validación devuelven HTTP `400` con las rutas de los campos inválidos. Otros errores usan un `code` estable y un `message` en inglés. Consulta la referencia API de cada operación: los payouts QR también pueden devolver `404`, `409` o `410` si el QR no existe, fue rechazado o expiró; `422` indica saldo insuficiente o rechazo definitivo y `503` indica que el proveedor no está disponible.


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