> ## 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 ACH por lote

> Envía varios pagos bancarios en Bolivia desde el saldo del partner.

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

Obtén el token con `POST /v3/auth/login`. El lote usa el saldo del partner por moneda y procesa los pagos en el orden enviado. Este endpoint conserva los campos en `snake_case`.

> **[Referencia API del lote](https://docs.mesadepagos.com/v3/api-reference/payout/payout-ach-por-lote.md)**
>
> Consulta el contrato completo y prueba el endpoint.

## Request

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

| Campo | Requerido | Descripción |
| - | - | - |
| `external_reference` | Sí | Referencia del lote en formato UUID v4. |
| `transactions` | Sí | Arreglo con al menos un pago bancario. |
| `transactions[].country` | No | Por defecto `BO`. El lote se procesa en Bolivia independientemente de este campo. |
| `transactions[].amount` | Sí | Número positivo, múltiplo de `0.01`. |
| `transactions[].bank_code` | Sí | Código del banco destino. Consulta `GET /v3/transactions/payouts/bank/banks?country=BO`. |
| `transactions[].description` | Sí | Descripción de hasta 200 caracteres. |
| `transactions[].destination_account` | Sí | Número de cuenta destino como string. |
| `transactions[].destination_holder` | Sí | Nombre completo del titular de la cuenta. |
| `transactions[].destination_id_number` | Sí | Documento del titular como string de 5 a 20 dígitos. |
| `transactions[].currency_type` | No | `BOB` o `USD`. Por defecto `BOB`. |

El fondeo es desde saldo (`balance`). El request no recibe `funding_source`, `asset_deposit` ni `blockchain`, y la respuesta no incluye una dirección de depósito crypto.

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

`transaction_id` en el nivel superior es igual a `external_reference`. `batch_id` identifica el lote en el proveedor. Los resultados de `transactions` conservan el orden del request y contienen el identificador bancario individual de cada pago.

> [!WARNING]
>
> HTTP 200 y `success: true` no confirman la liquidación de todos los pagos.
> `success` es `true` cuando al menos un pago fue autorizado. Revisa siempre el
> estado de cada transacción.

### Autorización parcial por saldo insuficiente

El saldo se evalúa por moneda en el orden del request. Los pagos con saldo suficiente se envían al proveedor con estado `PENDING`; los demás devuelven `FAILED`. Si al menos un pago se autoriza, `success` sigue siendo `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."
    }
  ]
}
```

Si ningún pago tiene saldo suficiente, la respuesta mantiene HTTP 200, devuelve `success: false`, `batch_id: null`, el mensaje `Insufficient balance to create ACH payout batch.` y todos los pagos con estado `FAILED`.

## Consultar el estado

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

Usa la `external_reference` del lote como `transactionId` para consultar el estado de todos sus pagos. También puedes usar el `transaction_id` del nivel superior de la respuesta, que tiene el mismo valor. Esta consulta busca por referencia del lote.

## Errores

| HTTP | Motivo |
| - | - |
| `400` | Request inválido o arreglo de transacciones vacío. |
| `401` | Token ausente, inválido o expirado. |
| `500` | Error interno o al procesar el lote con el proveedor. |

Los pagos rechazados por saldo insuficiente se informan en la respuesta HTTP 200, dentro de `transactions`.


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