Payout ACH por lote - ON RAMP by Mesadepagos

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

Consulta el contrato completo y prueba el endpoint.

Request

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

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

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:

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

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.

Referencia API del lote

​Request

​Response: HTTP 200

​Autorización parcial por saldo insuficiente

​Consultar el estado

​Errores

Request

Response: HTTP 200

Autorización parcial por saldo insuficiente

Consultar el estado

Errores