> ## 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.

# Transferencias bancarias globales

> Payouts bancarios mediante ACH, Wire, SWIFT y SEPA.

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](/auth) válido.

## Flujo recomendado

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

## Listar rails disponibles

```http theme={null}
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.

```json theme={null}
[
  {
    "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
      }
    }
  }
]
```

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

## Cotizar una transferencia

```http theme={null}
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.

```json theme={null}
{
  "sourceAmount": 100,
  "sourceCurrency": "USDC",
  "sourceNetwork": "polygon",
  "destinationCurrency": "EUR",
  "rail": "SEPA"
}
```

```json theme={null}
{
  "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

<Tabs>
  <Tab title="ACH">
    ACH utiliza número de cuenta y routing ABA de nueve dígitos.

    ```http theme={null}
    POST /v2/transactions/payouts/ach
    ```

    ```json theme={null}
    {
      "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"
      }
    }
    ```
  </Tab>

  <Tab title="Wire">
    Wire utiliza número de cuenta y routing ABA de nueve dígitos.

    ```http theme={null}
    POST /v2/transactions/payouts/wire
    ```

    ```json theme={null}
    {
      "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"
      }
    }
    ```
  </Tab>

  <Tab title="SWIFT">
    SWIFT requiere el BIC del banco y un `accountNumber` o `iban`. Consulta el schema del corredor: algunos canales solo admiten número de cuenta.

    ```http theme={null}
    POST /v2/transactions/payouts/swift
    ```

    ```json theme={null}
    {
      "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"
      }
    }
    ```
  </Tab>

  <Tab title="SEPA">
    SEPA utiliza un IBAN de entre 15 y 34 caracteres. El BIC es opcional.

    ```http theme={null}
    POST /v2/transactions/payouts/sepa
    ```

    ```json theme={null}
    {
      "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"
    }
    ```

    <Warning>
      El IBAN del ejemplo es únicamente para pruebas en sandbox. No lo uses para transferencias reales.
    </Warning>
  </Tab>
</Tabs>

### 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:

```json theme={null}
{
  "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
}
```

<Warning>
  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.
</Warning>