Bank Account SWIFT
Introduction
SWIFT Bank Account is the destination bank account when you off-ramp to fiat over the international SWIFT network. Avenia supports 16 corridors: USD, GBP, EUR, HKD, SGD, CHF, AUD, CAD, NZD, JPY, CNY, THB, PHP, INR, KRW and IDR.
A quote in a SWIFT currency is an international transfer, against BRL or crypto: add the BCB purpose code of that leg to it, outputPurposeCode when you pay out in it and inputPurposeCode when you receive it. It is optional through November 14, 2026 and required from November 15, 2026. See International Transfers (ACAM).
Correspondent bank
Some banks cannot be reached directly over SWIFT and the payment has to hop through a
correspondent. When that is the case, send intermediaryBic with the correspondent's BIC.
Leave it out when there is none. Do not guess it — a wrong BIC is worse than no BIC, because the payment is then routed through a bank that has no relationship with the destination, and it comes back days later. If the beneficiary's bank has not told you a correspondent is needed, there is none.
Accepted currencies
currency accepts any of the 16 corridors:
USD | GBP | EUR | HKD |
SGD | CHF | AUD | CAD |
NZD | JPY | CNY | THB |
PHP | INR | KRW | IDR |
A beneficiary belongs to one currency. The currency you register is the currency it
can be paid in, and it has to match the outputCurrency of the ticket — a beneficiary
registered for EUR cannot receive a GBP payout. The payout is created in the
beneficiary's currency, so allowing a mismatch would charge for one currency and deliver
another.
To pay the same bank account in more than one currency, register it once per currency.
The bank details are identical; only currency and alias change:
{ "alias": "Supplier · USD", "currency": "USD", "accountValue": "GB33BUKB20201555555555", "bic": "BUKBGB22", "...": "same bank fields" }
{ "alias": "Supplier · GBP", "currency": "GBP", "accountValue": "GB33BUKB20201555555555", "bic": "BUKBGB22", "...": "same bank fields" }
Each registration returns its own id. Use the one whose currency matches the quote.
Register the account here first, then reference its id when you create a SWIFT ticket.
SWIFT off-ramp requires a company account with an active SWIFT onboarding. See the KYB section to complete SWIFT activation.
All the endpoints here are applicable to subAccounts, just pass the subAccountId field followed by the subaccount id as the request parameter.
Register a SWIFT Beneficiary Account
Endpoint
Request example:
curl -X POST "https://api.sandbox.avenia.io:10952/v2/account/beneficiaries/bank-accounts/swift/" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer eyJhdXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" \
-d '{
"alias": "UK supplier",
"description": "Primary GBP supplier account",
"beneficiaryName": "Example Supplier LLC",
"beneficiaryType": "company",
"accountStandard": "iban",
"accountValue": "GB29NWBK60161331926819",
"bic": "NWBKGB2L",
"bankName": "NatWest",
"bankCountry": "GB",
"beneficiaryStreet": "1 King Street",
"beneficiaryCity": "London",
"beneficiaryState": "England",
"beneficiaryPostalCode": "EC2V 8AU",
"beneficiaryCountry": "GB"
}'
Fields
| Field | Type | Required | Description |
|---|---|---|---|
| alias | string | Yes (1–100 chars) | Custom name to identify the account. |
| description | string | No | Brief description of the bank account. |
| beneficiaryName | string | Yes | Full legal name of the account holder (person or company). |
| beneficiaryType | string | Yes | company or individual. |
| accountStandard | string | Yes | Identifier format: account_number or iban. Depends on the receiving bank. |
| accountValue | string | Yes | The account number or IBAN, matching accountStandard. |
| bic | string | Yes | The bank's SWIFT/BIC code (8 or 11 chars). |
| bankName | string | Yes | Name of the receiving bank. |
| bankCountry | string | Yes | Bank country, ISO 3166-1 alpha-2 (e.g. GB). |
| beneficiaryStreet | string | Yes | Beneficiary street address. |
| beneficiaryCity | string | Yes | Beneficiary city. |
| beneficiaryState | string | No | Beneficiary state/province. |
| beneficiaryPostalCode | string | No | Beneficiary postal/ZIP code. |
| beneficiaryCountry | string | Yes | Beneficiary country, ISO 3166-1 alpha-2. |
| currency | string | No | Receiving currency, one of the 16 corridors (e.g. USD, GBP). Defaults to USD when omitted, and must match the ticket's outputCurrency |
| intermediaryBic | string | No | BIC of the correspondent bank, when the beneficiary's bank cannot be reached directly. Validated as a BIC when sent; omit it if there is none |
| bankOtherIdentifier | string | No | Any extra identifier the receiving bank requires beyond its BIC — a sort code or routing number, for example |
SWIFT abstracts every corridor down to two identifier formats plus a BIC: account_number (e.g. USD, CAD, AUD) and iban (e.g. GBP, EUR). The receiving bank/country determines which one to use.
Response
{
"id": "00000000-0000-0000-0000-000000000000"
}
Use the returned id as beneficiarySwiftBankAccountId when creating a SWIFT ticket.
List all SWIFT beneficiaries bank accounts
Endpoint
Filter Fields
| Field | Type | Description |
|---|---|---|
| subAccountId | string | The ID of a sub-account. If provided, data is fetched for the sub-account; leave empty for the main account. |
| createdAfter | int64 | Filters results created after this timestamp. |
| createdBefore | int64 | Filters results created before this timestamp. |
| cursor | string | Cursor for pagination. Pass the value from the previous response to retrieve the next set of results. |
| alias | string | Filters results with the specified alias. |
Request example
curl -X GET "https://api.sandbox.avenia.io:10952/v2/account/beneficiaries/bank-accounts/swift/" \
-H "Authorization: Bearer eyJhdXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
Response
{
"bankAccounts": [
{
"id": "00000000-0000-0000-0000-000000000000",
"alias": "UK supplier",
"description": "Primary GBP supplier account",
"beneficiaryName": "Example Supplier LLC",
"beneficiaryType": "company",
"accountStandard": "iban",
"accountValue": "GB29NWBK60161331926819",
"bic": "NWBKGB2L",
"bankName": "NatWest",
"bankCountry": "GB",
"beneficiaryStreet": "1 King Street",
"beneficiaryCity": "London",
"beneficiaryState": "England",
"beneficiaryPostalCode": "EC2V 8AU",
"beneficiaryCountry": "GB",
"currency": "GBP",
"createdAt": "2026-08-03T15:13:08.320462Z"
}
],
"cursor": "MzItMTc0MDA2NDM4ODMyMA..."
}
Get SWIFT beneficiary bank account by ID
Endpoint
Request example
curl -X GET "https://api.sandbox.avenia.io:10952/v2/account/beneficiaries/bank-accounts/swift/00000000-0000-0000-0000-000000000000" \
-H "Authorization: Bearer eyJhdXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
Response
{
"bankAccount": {
"id": "00000000-0000-0000-0000-000000000000",
"alias": "UK supplier",
"beneficiaryName": "Example Supplier LLC",
"beneficiaryType": "company",
"accountStandard": "iban",
"accountValue": "GB29NWBK60161331926819",
"bic": "NWBKGB2L",
"bankName": "NatWest",
"bankCountry": "GB",
"beneficiaryStreet": "1 King Street",
"beneficiaryCity": "London",
"beneficiaryState": "England",
"beneficiaryPostalCode": "EC2V 8AU",
"beneficiaryCountry": "GB",
"currency": "GBP",
"createdAt": "2026-08-03T15:13:08.320462Z"
}
}
Delete SWIFT beneficiary bank Account
Endpoint
Request example
curl -X DELETE "https://api.sandbox.avenia.io:10952/v2/account/beneficiaries/bank-accounts/swift/00000000-0000-0000-0000-000000000000" \
-H "Authorization: Bearer eyJhdXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
Your SWIFT bank account has been deleted!
Conclusion
In this section you have learned how to manage SWIFT bank accounts within the Avenia API.
What we've covered:
- ✅ Creating a SWIFT Bank Account – Register a beneficiary for international SWIFT payouts (any supported corridor).
- ✅ Fetching All SWIFT Bank Accounts – Retrieve all your SWIFT bank accounts.
- ✅ Fetching a Specific SWIFT Bank Account by ID – Retrieve details by UUID.
- ✅ Deleting a SWIFT Bank Account – Permanently remove a SWIFT bank account.
Use the returned id as beneficiarySwiftBankAccountId when creating a SWIFT off-ramp ticket (see Operations → Available Combinations).