> ## 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.
# Global bank transfers
> Bank payouts through ACH, Wire, SWIFT, and SEPA.
The global bank transfers module sends funds from `USDC` or `USDT` to bank accounts through ACH, Wire, SWIFT, and SEPA.
Each operation returns funding instructions containing an address, amount, asset, and network. The bank transfer is processed after the specified amount is received.
## Endpoints
| Operation | Method | Path |
| ----------------------- | ------ | ----------------------------------- |
| List available rails | `GET` | `/v2/transactions/payouts/rails` |
| Estimate a transfer | `POST` | `/v2/transactions/payouts/estimate` |
| Create an ACH transfer | `POST` | `/v2/transactions/payouts/ach` |
| Create a Wire transfer | `POST` | `/v2/transactions/payouts/wire` |
| Create a SWIFT transfer | `POST` | `/v2/transactions/payouts/swift` |
| Create a SEPA transfer | `POST` | `/v2/transactions/payouts/sepa` |
All requests require a valid [authentication token](/en/auth).
## Recommended flow
1. Call `GET /v2/transactions/payouts/rails` to retrieve the rails, corridors, limits, and fields enabled for the account.
2. Request an estimate through `POST /v2/transactions/payouts/estimate`.
3. Create the transfer through the selected rail endpoint.
4. Send exactly `paymentInstructions.amount` to `paymentInstructions.depositAddress` using the specified asset and network.
5. Query the transaction or process its updates through [webhooks](/en/webhooks).
## List available rails
```http theme={null}
GET /v2/transactions/payouts/rails
```
The response only includes withdrawal rails that are currently enabled. Each corridor provides its currency, limits, eligible or restricted countries, and purpose codes.
```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
}
}
}
]
```
Corridors and limits may vary by environment and account. Treat this response
as the source of truth before creating a transfer.
## Estimate a transfer
```http theme={null}
POST /v2/transactions/payouts/estimate
```
You can fix the source amount with `sourceAmount` or the amount received by the beneficiary with `destinationAmount`. You must provide at least one of them.
```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
}
```
## Common fields
| Field | Type | Required | Description |
| ----------------------- | ------ | ----------- | --------------------------------------------------------------------------------- |
| `clientId` | UUID | Yes | Business client funding the payout. Retrieve it from the Business Clients module. |
| `externalReference` | UUID | Yes | Unique, idempotent operation reference. |
| `sourceCurrency` | string | Yes | `USDC` or `USDT`. |
| `sourceNetwork` | string | Yes | `polygon`, `ethereum`, or `sepolia`; availability depends on the environment. |
| `sourceAmount` | number | Conditional | Source crypto amount. Required when `destinationAmount` is omitted. |
| `destinationAmount` | number | Conditional | Fiat amount received by the beneficiary. Required when `sourceAmount` is omitted. |
| `destinationCurrency` | string | Yes | ISO 4217 currency enabled for the corridor. |
| `accountType` | string | Yes | `individual` or `business`. |
| `firstName`, `lastName` | string | Conditional | Required for an `individual` beneficiary. |
| `companyName` | string | Conditional | Required for a `business` beneficiary. |
| `purposeCode` | string | By corridor | Must be included in `corridors[].purposeCodes` when required by the corridor. |
| `description` | string | No | Transfer memo or visible reference. |
## Create a transfer
ACH uses an account number and a nine-digit ABA routing number.
```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"
}
}
```
Wire uses an account number and a nine-digit ABA routing number.
```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"
}
}
```
SWIFT requires the bank BIC and either `accountNumber` or `iban`. Check the corridor schema because some channels only support an account number.
```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"
}
}
```
SEPA uses an IBAN between 15 and 34 characters. The BIC is optional.
```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": "Supplier payment",
"accountType": "individual",
"firstName": "Marie",
"lastName": "Dubois",
"bankName": "Example Bank",
"iban": "FR1420041010050500013M02606",
"bic": "PSSTFRPPMON"
}
```
The sample IBAN is for sandbox testing only. Do not use it for real transfers.
### Beneficiary address
ACH, Wire, and SWIFT require `beneficiaryAddress`:
| Field | Format |
| ------------- | --------------------------------------------------- |
| `streetLine1` | Beneficiary street address. |
| `city` | City. |
| `postalCode` | Postal code. |
| `country` | ISO 3166-1 alpha-3, such as `USA` or `DEU`. |
| `state` | ISO 3166-2 subdivision, such as `US-NY` or `DE-BE`. |
## Creation response
All four endpoints return the same contract:
```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
}
```
Send the exact amount and asset over the network specified in
`paymentInstructions`. A different amount or network may prevent
reconciliation.