Link International Bank Account

Overview

Link an international bank account to enable cross-border wire transfers and international payouts. This endpoint allows you to connect a customer’s international bank account as a payout destination.

Prerequisites

An application token (obtained from creating a withdrawal widget or account widget)
Valid access token

Endpoint

POST {{LIQUIDITY_URL}}/v1/ext/application-token/:token/linked-accounts/:currency/link/international_bank/:step
Auth: Bearer {{accessToken}}

Path Parameters

Parameter	Type	Description	Required
`token`	string	Application token from payout/account widget	Yes
`currency`	string	Currency code (e.g., `USD`)	Yes
`step`	string	Usually `1`	Yes

Request

curl -X POST "{{LIQUIDITY_URL}}/v1/ext/application-token/{{token}}/linked-accounts/USD/link/international_bank/1" \
  -H "Authorization: Bearer {{accessToken}}" \
  -H "Content-Type: application/json" \
  -d '{
    "label": "My UK Business Account",
    "data": {
      "firstName": "John",
      "lastName": "Doe",
      "name": "Quantum Works LLC",
      "accountNumber": "8991026399",
      "swiftOrBic": "031000053",
      "bankName": "ABC bank",
      "recipientAddress": "9401 San francisco",
      "recipientCity": "San francisco",
      "recipientState": "CA",
      "recipientPostalCode": "9401",
      "email": "timi@gradientfi.com",
      "recipientCountry": "NG",
      "recipientType": "personal",
      "nickName": "MayetopsC"
    }
  }'

Request Body Fields

Field	Type	Description	Required
`label`	string	Display name for the linked account	Yes
`data.firstName`	string	First name of recipient	Yes
`data.lastName`	string	Last name of recipient	Yes
`data.name`	string	Business/account name	Yes
`data.accountNumber`	string	International bank account number	Yes
`data.swiftOrBic`	string	SWIFT/BIC code	Yes
`data.bankName`	string	Name of the international bank	Yes
`data.recipientAddress`	string	Full address of the recipient	Yes
`data.recipientCity`	string	City of the recipient	Yes
`data.recipientState`	string	State/region of the recipient	Yes
`data.recipientPostalCode`	string	Postal code of the recipient	Yes
`data.email`	string	Email of the recipient	Yes
`data.recipientCountry`	string	ISO country code (2 letters, e.g., `NG`)	Yes
`data.recipientType`	string	Recipient type: `personal` or `business`	Yes
`data.nickName`	string	Nickname for this linked account (e.g. “MayetopsC”). If omitted, top-level `label` is used.	No

Response (200)

{
  "success": true,
  "message": "Account successfully linked!",
  "data": {
    "id": "6b7c509b-93f4-4b51-a8e4-61cabed5eea0"
  }
}

Response Fields

Field	Type	Description
`success`	bool	`true` on success
`message`	string	`"Account successfully linked!"`
`data.id`	string	Linked account ID — use this for withdrawal requests

Notes

Store the id from the response for use in withdrawal requests
Provide accurate recipient address/country data for compliance
SWIFT/BIC should match the destination bank
International wire transfers may have higher fees and longer processing times
The linked account can be used for withdrawals once successfully created

Getting Started

Authentication

Account

Wallets

Transactions

Payin

Payout

Linked Accounts

Webhooks

Link International Bank Account

Overview

Prerequisites

Endpoint

Path Parameters

Request

Request Body Fields

Response (200)

Response Fields

Notes

​Overview

​Prerequisites

​Endpoint

​Path Parameters

​Request

​Request Body Fields

​Response (200)

​Response Fields

​Notes

Overview

Prerequisites

Endpoint

Path Parameters

Request

Request Body Fields

Response (200)

Response Fields

Notes