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

# Batch ACH payout

> Send multiple bank payments in Bolivia using the partner balance.

```http theme={null}
POST /v3/transactions/payouts/bank/batch
Authorization: Bearer {accessToken}
Content-Type: application/json
```

Get a token with `POST /v3/auth/login`. The batch uses the partner balance for each currency and processes payments in the submitted order. This endpoint keeps its fields in `snake_case`.

> **[Batch API reference](https://docs.mesadepagos.com/en/v3/api-reference/payout/payout-ach-por-lote.md)**
>
> Review the full contract and try the endpoint.

## Request

```json theme={null}
{
  "external_reference": "550e8400-e29b-41d4-a716-446655440000",
  "transactions": [
    {
      "country": "BO",
      "amount": 100.5,
      "bank_code": "101",
      "description": "Supplier payment",
      "destination_account": "1234567890",
      "destination_holder": "Juan Pérez",
      "destination_id_number": "1234567",
      "currency_type": "BOB"
    },
    {
      "country": "BO",
      "amount": 50,
      "bank_code": "101",
      "description": "Service payment",
      "destination_account": "9876543210",
      "destination_holder": "María López",
      "destination_id_number": "7654321",
      "currency_type": "BOB"
    }
  ]
}
```

| Field | Required | Description |
| - | - | - |
| `external_reference` | Yes | Batch reference in UUID v4 format. |
| `transactions` | Yes | Array with at least one bank payment. |
| `transactions[].country` | No | Defaults to `BO`. The batch is processed in Bolivia regardless of this field. |
| `transactions[].amount` | Yes | Positive number, multiple of `0.01`. |
| `transactions[].bank_code` | Yes | Destination bank code. Retrieve banks with `GET /v3/transactions/payouts/bank/banks?country=BO`. |
| `transactions[].description` | Yes | Description up to 200 characters. |
| `transactions[].destination_account` | Yes | Destination account number as a string. |
| `transactions[].destination_holder` | Yes | Full name of the account holder. |
| `transactions[].destination_id_number` | Yes | Account holder document as a string of 5 to 20 digits. |
| `transactions[].currency_type` | No | `BOB` or `USD`. Defaults to `BOB`. |

Funding uses the partner balance (`balance`). The request does not take `funding_source`, `asset_deposit`, or `blockchain`, and the response does not include a crypto deposit address.

## Response: HTTP 200

```json theme={null}
{
  "success": true,
  "message": "Batch authorized successfully",
  "transaction_id": "550e8400-e29b-41d4-a716-446655440000",
  "external_reference": "550e8400-e29b-41d4-a716-446655440000",
  "batch_id": "ACH-123456",
  "transactions": [
    {
      "transaction_id": "12345678901234",
      "status": "PENDING",
      "message": "Transaction created successfully"
    },
    {
      "transaction_id": "12345678901235",
      "status": "PENDING",
      "message": "Transaction created successfully"
    }
  ]
}
```

The top-level `transaction_id` equals `external_reference`. `batch_id` identifies the batch at the provider. The `transactions` results preserve the request order and contain the individual bank identifier for each payment.

> [!WARNING]
>
> HTTP 200 and `success: true` do not confirm settlement of all payments.
> `success` is `true` when at least one payment was authorized. Always check
> each transaction status.

### Partial authorization due to insufficient funds

The balance is evaluated per currency in the request order. Payments with sufficient funds are sent to the provider with status `PENDING`; the others return `FAILED`. If at least one payment is authorized, `success` remains `true`:

```json theme={null}
{
  "success": true,
  "message": "Batch partially authorized: some transactions have insufficient funds.",
  "transaction_id": "550e8400-e29b-41d4-a716-446655440000",
  "external_reference": "550e8400-e29b-41d4-a716-446655440000",
  "batch_id": "ACH-123456",
  "transactions": [
    {
      "transaction_id": "12345678901234",
      "status": "PENDING",
      "message": "Transaction created successfully"
    },
    {
      "transaction_id": "12345678901235",
      "status": "FAILED",
      "message": "Insufficient BOB balance to create ACH payout transaction."
    }
  ]
}
```

If no payment has sufficient funds, the response still uses HTTP 200 and returns `success: false`, `batch_id: null`, the message `Insufficient balance to create ACH payout batch.`, and all payments with status `FAILED`.

## Retrieve status

```http theme={null}
GET /v3/transactions/payouts/bank/status/{transactionId}
Authorization: Bearer {accessToken}
```

Use the batch `external_reference` as `transactionId` to retrieve the status of all its payments. You can also use the top-level response `transaction_id`, which has the same value. This query looks up the batch reference.

## Errors

| HTTP | Reason |
| - | - |
| `400` | Invalid request or empty transaction array. |
| `401` | Missing, invalid, or expired token. |
| `500` | Internal error or error processing the batch with the provider. |

Payments rejected due to insufficient funds are reported inside `transactions` in the HTTP 200 response.


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