Transferencias bancarias globales - ON RAMP by Mesadepagos

El módulo de transferencias bancarias globales permite enviar fondos desde USDC o USDT hacia cuentas bancarias mediante los rails ACH, Wire, SWIFT y SEPA. Cada operación genera instrucciones de fondeo con una dirección, un monto, un asset y una red. La transferencia bancaria se procesa después de recibir el monto indicado.

Endpoints

Operación	Método	Ruta
Listar rails disponibles	`GET`	`/v2/transactions/payouts/rails`
Cotizar una transferencia	`POST`	`/v2/transactions/payouts/estimate`
Crear transferencia ACH	`POST`	`/v2/transactions/payouts/ach`
Crear transferencia Wire	`POST`	`/v2/transactions/payouts/wire`
Crear transferencia SWIFT	`POST`	`/v2/transactions/payouts/swift`
Crear transferencia SEPA	`POST`	`/v2/transactions/payouts/sepa`

Todas las solicitudes requieren un token de autenticación válido.

Flujo recomendado

Consulta GET /v2/transactions/payouts/rails para conocer los rails, corredores, límites y campos habilitados para la cuenta.
Solicita una cotización con POST /v2/transactions/payouts/estimate.
Crea la transferencia en el endpoint del rail seleccionado.
Envía exactamente paymentInstructions.amount a paymentInstructions.depositAddress, usando el asset y la red indicados.
Consulta la transacción o procesa sus actualizaciones mediante webhooks.

Listar rails disponibles

GET /v2/transactions/payouts/rails

La respuesta solo incluye los rails de retiro habilitados actualmente. Cada corredor informa su moneda, límites, países permitidos o restringidos y códigos de propósito.

[
  {
    "rail": "SEPA",
    "endpoint": "/v2/transactions/payouts/sepa",
    "corridors": [
      {
        "currency": "EUR",
        "limitMin": 10,
        "limitMax": 100000,
        "eligibleCountries": ["FR", "DE", "ES"],
        "purposeCodes": []
      }
    ],
    "schema": {
      "iban": {
        "type": "string",
        "format": "IBAN (15-34 chars)",
        "required": true
      }
    }
  }
]

Los corredores y límites pueden variar por ambiente y cuenta. Usa esta respuesta como fuente de verdad antes de crear una transferencia.

Cotizar una transferencia

POST /v2/transactions/payouts/estimate

Puedes fijar el monto de origen con sourceAmount o el monto que recibirá el beneficiario con destinationAmount. Debes enviar al menos uno de los dos.

{
  "sourceAmount": 100,
  "sourceCurrency": "USDC",
  "sourceNetwork": "polygon",
  "destinationCurrency": "EUR",
  "rail": "SEPA"
}

{
  "amount": 100,
  "sourceCurrency": "USDC",
  "sourceNetwork": "polygon",
  "destinationAmount": 91.35,
  "destinationCurrency": "EUR",
  "effectiveRate": 0.925,
  "fees": 1.25
}

Campos comunes

Campo	Tipo	Requerido	Descripción
`clientId`	UUID	Sí	Cliente empresarial que fondea el payout. Se obtiene desde el módulo Business Clients.
`externalReference`	UUID	Sí	Referencia única e idempotente de la operación.
`sourceCurrency`	string	Sí	`USDC` o `USDT`.
`sourceNetwork`	string	Sí	`polygon`, `ethereum` o `sepolia`; la disponibilidad depende del ambiente.
`sourceAmount`	number	Condicional	Monto cripto de origen. Requerido si no se envía `destinationAmount`.
`destinationAmount`	number	Condicional	Monto fiat que recibirá el beneficiario. Requerido si no se envía `sourceAmount`.
`destinationCurrency`	string	Sí	Moneda ISO 4217 habilitada para el corredor.
`accountType`	string	Sí	`individual` o `business`.
`firstName`, `lastName`	string	Condicional	Requeridos para beneficiarios `individual`.
`companyName`	string	Condicional	Requerido para beneficiarios `business`.
`purposeCode`	string	Según corredor	Debe pertenecer a `corridors[].purposeCodes` cuando el corredor lo requiera.
`description`	string	No	Concepto o referencia visible de la transferencia.

Crear una transferencia

ACH
Wire
SWIFT
SEPA

ACH utiliza número de cuenta y routing ABA de nueve dígitos.

POST /v2/transactions/payouts/ach

{
  "clientId": "550e8400-e29b-41d4-a716-446655440010",
  "externalReference": "550e8400-e29b-41d4-a716-446655440011",
  "sourceAmount": 100,
  "sourceCurrency": "USDC",
  "sourceNetwork": "polygon",
  "destinationCurrency": "USD",
  "purposeCode": "OTHER",
  "description": "Invoice",
  "accountType": "individual",
  "firstName": "Jane",
  "lastName": "Doe",
  "bankName": "Example Bank",
  "accountNumber": "123456789",
  "routingCode": "021000021",
  "beneficiaryAddress": {
    "streetLine1": "123 Main Street",
    "city": "New York",
    "postalCode": "10001",
    "country": "USA",
    "state": "US-NY"
  }
}

Wire utiliza número de cuenta y routing ABA de nueve dígitos.

POST /v2/transactions/payouts/wire

{
  "clientId": "550e8400-e29b-41d4-a716-446655440010",
  "externalReference": "550e8400-e29b-41d4-a716-446655440012",
  "destinationAmount": 500,
  "sourceCurrency": "USDT",
  "sourceNetwork": "ethereum",
  "destinationCurrency": "USD",
  "purposeCode": "IMPORT_EXPORT",
  "description": "Supplier",
  "accountType": "business",
  "companyName": "Example Imports LLC",
  "bankName": "Example Bank",
  "accountNumber": "987654321",
  "routingCode": "026009593",
  "beneficiaryAddress": {
    "streetLine1": "200 Market Street",
    "city": "New York",
    "postalCode": "10005",
    "country": "USA",
    "state": "US-NY"
  }
}

SWIFT requiere el BIC del banco y un accountNumber o iban. Consulta el schema del corredor: algunos canales solo admiten número de cuenta.

POST /v2/transactions/payouts/swift

{
  "clientId": "550e8400-e29b-41d4-a716-446655440010",
  "externalReference": "550e8400-e29b-41d4-a716-446655440013",
  "sourceAmount": 750,
  "sourceCurrency": "USDC",
  "sourceNetwork": "polygon",
  "destinationCurrency": "EUR",
  "description": "International supplier payment",
  "accountType": "business",
  "companyName": "Example GmbH",
  "bankName": "Example Bank",
  "bic": "DEUTDEFF",
  "accountNumber": "1234567890",
  "currency": "EUR",
  "beneficiaryAddress": {
    "streetLine1": "1 Example Strasse",
    "city": "Berlin",
    "postalCode": "10115",
    "country": "DEU",
    "state": "DE-BE"
  }
}

SEPA utiliza un IBAN de entre 15 y 34 caracteres. El BIC es opcional.

POST /v2/transactions/payouts/sepa

{
  "clientId": "550e8400-e29b-41d4-a716-446655440010",
  "externalReference": "550e8400-e29b-41d4-a716-446655440014",
  "sourceAmount": 100,
  "sourceCurrency": "USDC",
  "sourceNetwork": "polygon",
  "destinationCurrency": "EUR",
  "description": "Pago proveedor",
  "accountType": "individual",
  "firstName": "Marie",
  "lastName": "Dubois",
  "bankName": "Example Bank",
  "iban": "FR1420041010050500013M02606",
  "bic": "PSSTFRPPMON"
}

El IBAN del ejemplo es únicamente para pruebas en sandbox. No lo uses para transferencias reales.

Dirección del beneficiario

ACH, Wire y SWIFT requieren beneficiaryAddress:

Campo	Formato
`streetLine1`	Dirección del beneficiario.
`city`	Ciudad.
`postalCode`	Código postal.
`country`	ISO 3166-1 alpha-3, por ejemplo `USA` o `DEU`.
`state`	Subdivisión ISO 3166-2, por ejemplo `US-NY` o `DE-BE`.

Respuesta de creación

Los cuatro endpoints devuelven el mismo contrato:

{
  "transactionId": "550e8400-e29b-41d4-a716-446655440020",
  "externalReference": "550e8400-e29b-41d4-a716-446655440014",
  "status": "pending_transaction",
  "paymentInstructions": {
    "depositAddress": "0x1111111111111111111111111111111111111111",
    "amount": "101.25000000",
    "asset": "USDC",
    "network": "polygon"
  },
  "destinationAmount": 91.35,
  "destinationCurrency": "EUR",
  "fees": 1.25
}

Envía exactamente el monto, asset y red indicados en paymentInstructions. Un monto o una red diferente puede impedir que la operación sea conciliada.

​Endpoints

​Flujo recomendado

​Listar rails disponibles

​Cotizar una transferencia

​Campos comunes

​Crear una transferencia

​Dirección del beneficiario

​Respuesta de creación

Endpoints

Flujo recomendado

Listar rails disponibles

Cotizar una transferencia

Campos comunes

Crear una transferencia

Dirección del beneficiario

Respuesta de creación