Batch ACH payout - ON RAMP by Mesadepagos

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

Review the full contract and try the endpoint.

Request

{
  "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

{
  "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.

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:

{
  "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

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.

Batch API reference

​Request

​Response: HTTP 200

​Partial authorization due to insufficient funds

​Retrieve status

​Errors

Request

Response: HTTP 200

Partial authorization due to insufficient funds

Retrieve status

Errors