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

> Send bank and QR payouts with the v3 API.

Authenticate with [POST /v3/auth/login](https://docs.mesadepagos.com/en/v3/auth.md) and send `Authorization: Bearer {accessToken}` with each request. Bank payouts use `snake_case` fields; QR payouts use `camelCase`.

## Endpoints

| Name | Method | Path |
| - | - | - |
| ACH payout | `POST` | `/v3/transactions/payouts/bank` |
| Batch ACH payout | `POST` | `/v3/transactions/payouts/bank/batch` |
| Bank payout status | `GET` | `/v3/transactions/payouts/bank/status/{transactionId}` |
| QR validation | `POST` | `/v3/transactions/payouts/validate/qr` |
| QR payout | `POST` | `/v3/transactions/payouts/qr` |
| Bank list | `GET` | `/v3/transactions/payouts/bank/banks` |

See [Crypto Payout](https://docs.mesadepagos.com/en/v3/payout-crypto.md) for wallet-to-wallet transfers.

## Payout ACH

Use `funding_source: "balance"` to fund the payment from the partner balance or `"conversion"` to receive a crypto deposit address and amount. `asset_deposit` defaults to `USDC`, and `blockchain` defaults to `Polygon`.

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

`transaction.destination_account` must be sent as a string and must not contain underscores (`_`), hyphens (`-`), or whitespace, including tabs and line breaks. This validation applies to every country; Costa Rican (`CR`) and Guatemalan (`GT`) IBANs retain their prefixes. Invalid values are rejected with HTTP `400`.

`transaction.entity_type`, `transaction.first_name`, and `transaction.document_type` are required. `last_name` is required for `individual` and optional for `company`. The account holder name is formed from `first_name` and `last_name`. Accepted currencies are `BOB`, `USD`, `CLP`, `PEN`, and `COP`; availability depends on the enabled corridor. Document and account validation rules also depend on the destination country. See the API reference for details.

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

A payout with a transaction in `processing_transaction` returns HTTP `202`; otherwise, successful creation returns HTTP `201`. Creation does not confirm settlement. [Review the ACH API reference](https://docs.mesadepagos.com/en/v3/api-reference/payout/payout-ach.md).

## Batch Payouts and Status

See [Batch ACH payout](https://docs.mesadepagos.com/en/v3/payout-batch.md) for the request, partial authorization behavior, and status query. The batch uses partner balance and keeps `snake_case` fields.

## QR Validation

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

Send the complete QR image as pure base64, without a `data:image` prefix. Replace the abbreviated value in this example with the full image.

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

### Response: HTTP 201

```json theme={null}
{
  "code": 200,
  "message": "QR code scanned successfully",
  "details": {
    "titularDestino": "Juan Pérez",
    "cuentaDestino": "1234567890",
    "ciNitDestino": "1234567",
    "nombreBancoDestino": "Example Bank",
    "codigoBancoDestino": "101",
    "moneda": "BOB",
    "monto": 100.5,
    "glosa": "Supplier payment",
    "numeroReferencia": "123456789",
    "fechaVencimiento": "2026-05-13T23:59:59.000Z"
  }
}
```

The response body contains `code: 200` for a successful scan. Invalid images are rejected with HTTP `400`. [QR validation API reference](https://docs.mesadepagos.com/en/v3/api-reference/payout/validacion-qr.md).

## Payout QR

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

`fundingSource`, `externalReference` (1–32 characters), and `image` are required. `amount` is required with `conversion`; when provided, it must be positive and a multiple of `0.01`. Supply an amount sufficient to cover the QR payment. `assetDeposit` defaults to `USDC`, and `blockchain` defaults to `Polygon`. The image uses the same pure base64 format as QR validation.

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

### Response: 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"
  }
}
```

With `conversion`, fund the returned `depositAddress` with `amountDeposit` of the selected asset on the specified blockchain. With `balance`, the payment uses the partner balance and the deposit fields are `null`. [QR payout API reference](https://docs.mesadepagos.com/en/v3/api-reference/payout/payout-qr.md).

## Bank List

```http theme={null}
GET /v3/transactions/payouts/bank/banks?country=BO
```

### Query Parameters

| Field | Type | Required | Default | Description |
| - | - | - | - | - |
| `country` | string | No | `BO` | Country ISO alpha-2 code used to retrieve banks. |

```json theme={null}
{
  "banks": [
    {
      "code": "101",
      "name": "Example Bank"
    }
  ]
}
```

## Errors

Validation failures return HTTP `400` with the invalid field paths. Other errors use a stable `code` and an English `message`. Check the API reference for each operation: QR payouts can also return `404`, `409`, or `410` for a missing, rejected, or expired QR; `422` indicates insufficient funds or a permanent rejection, and `503` indicates provider unavailability.


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