Payout - ON RAMP by Mesadepagos

Autentícate con POST /v3/auth/login y envía Authorization: Bearer {accessToken} en cada request. Los payouts bancarios usan campos en snake_case; los payouts QR usan camelCase.

Endpoints

Nombre	Método	Ruta
Payout ACH	`POST`	`/v3/transactions/payouts/bank`
Payout ACH por lote	`POST`	`/v3/transactions/payouts/bank/batch`
Estado de payout bancario	`GET`	`/v3/transactions/payouts/bank/status/{transactionId}`
Validación QR	`POST`	`/v3/transactions/payouts/validate/qr`
Payout QR	`POST`	`/v3/transactions/payouts/qr`
Lista de bancos	`GET`	`/v3/transactions/payouts/bank/banks`

Consulta Payout Crypto para transferencias entre wallets.

Payout ACH

Usa funding_source: "balance" para fondear el pago con el saldo del partner o "conversion" para recibir una dirección y un monto de depósito cripto. asset_deposit usa USDC por defecto y blockchain usa Polygon.

POST /v3/transactions/payouts/bank

transaction.destination_account debe enviarse como texto y no puede contener guiones bajos (_), guiones (-) ni espacios en blanco, incluidos tabulaciones y saltos de línea. Esta validación aplica a todos los países; los formatos IBAN de Costa Rica (CR) y Guatemala (GT) conservan sus prefijos. Los valores inválidos se rechazan con HTTP 400. transaction.entity_type, transaction.first_name y transaction.document_type son obligatorios. last_name es obligatorio para individual y opcional para company. El titular se forma con first_name y last_name. Las monedas aceptadas son BOB, USD, CLP, PEN y COP; su disponibilidad depende del corredor habilitado. Las reglas de validación del documento y de la cuenta también dependen del país de destino. Consulta los detalles en la referencia API.

{
  "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": "Pago proveedor",
    "destination_account": "1234567890",
    "first_name": "Juan",
    "last_name": "Pérez",
    "document_type": "national_id",
    "destination_id_number": "1234567",
    "currency_type": "BOB"
  }
}

Response

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

Un payout con una transacción en processing_transaction devuelve HTTP 202; en los demás casos, una creación exitosa devuelve HTTP 201. La creación no confirma la liquidación. Consulta la referencia API de ACH.

Pagos por lote y estado

Consulta Payout ACH por lote para el request, las autorizaciones parciales y la consulta de estado. El lote usa el saldo del partner y mantiene los campos en snake_case.

Validación QR

POST /v3/transactions/payouts/validate/qr

Envía la imagen QR completa en base64 puro, sin el prefijo data:image. Reemplaza el valor abreviado de este ejemplo por la imagen completa.

{
  "image": "iVBORw0KGgoAAAANSUhEUgAA..."
}

Respuesta: HTTP 201

{
  "code": 200,
  "message": "QR code scanned successfully",
  "details": {
    "titularDestino": "Juan Pérez",
    "cuentaDestino": "1234567890",
    "ciNitDestino": "1234567",
    "nombreBancoDestino": "Banco Ejemplo",
    "codigoBancoDestino": "101",
    "moneda": "BOB",
    "monto": 100.5,
    "glosa": "Pago proveedor",
    "numeroReferencia": "123456789",
    "fechaVencimiento": "2026-05-13T23:59:59.000Z"
  }
}

El cuerpo de respuesta contiene code: 200 cuando el escaneo es exitoso. Las imágenes inválidas se rechazan con HTTP 400. Referencia API de validación QR.

Payout QR

POST /v3/transactions/payouts/qr

fundingSource, externalReference (1–32 caracteres) e image son obligatorios. amount es obligatorio con conversion; si se envía, debe ser positivo y múltiplo de 0.01. Envía un monto suficiente para cubrir el pago QR. assetDeposit usa USDC por defecto y blockchain usa Polygon. La imagen usa el mismo formato base64 puro que la validación QR.

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

Respuesta: HTTP 201

{
  "externalReference": "ORDER-QR-1001",
  "amountDeposit": "14.44",
  "depositAddress": "0x0000000000000000000000000000000000000000",
  "transactions": {
    "transactionId": "550e8400-e29b-41d4-a716-446655440002",
    "status": "pending_transaction",
    "message": "Transaction created successfully"
  }
}

Con conversion, fondea depositAddress con amountDeposit del asset seleccionado en la blockchain indicada. Con balance, el pago usa el saldo del partner y los campos de depósito son null. Referencia API de payout QR.

Lista de bancos

GET /v3/transactions/payouts/bank/banks?country=BO

Query Params

Campo	Tipo	Requerido	Default	Descripción
`country`	string	No	`BO`	Código ISO alpha-2 del país para consultar bancos.

{
  "banks": [
    {
      "code": "101",
      "name": "Banco Ejemplo"
    }
  ]
}

Errores

Los errores de validación devuelven HTTP 400 con las rutas de los campos inválidos. Otros errores usan un code estable y un message en inglés. Consulta la referencia API de cada operación: los payouts QR también pueden devolver 404, 409 o 410 si el QR no existe, fue rechazado o expiró; 422 indica saldo insuficiente o rechazo definitivo y 503 indica que el proveedor no está disponible.

​Endpoints

​Payout ACH

​Response

​Pagos por lote y estado

​Validación QR

​Respuesta: HTTP 201

​Payout QR

​Respuesta: HTTP 201

​Lista de bancos

​Query Params

​Errores

Endpoints

Payout ACH

Response

Pagos por lote y estado

Validación QR

Respuesta: HTTP 201

Payout QR

Respuesta: HTTP 201

Lista de bancos

Query Params

Errores