Skip to main content

​
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

ParameterTypeDescriptionRequired
tokenstringApplication token from payout/account widgetYes
currencystringCurrency code (e.g., USD)Yes
stepstringUsually 1Yes

​
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

FieldTypeDescriptionRequired
labelstringDisplay name for the linked accountYes
data.firstNamestringFirst name of recipientYes
data.lastNamestringLast name of recipientYes
data.namestringBusiness/account nameYes
data.accountNumberstringInternational bank account numberYes
data.swiftOrBicstringSWIFT/BIC codeYes
data.bankNamestringName of the international bankYes
data.recipientAddressstringFull address of the recipientYes
data.recipientCitystringCity of the recipientYes
data.recipientStatestringState/region of the recipientYes
data.recipientPostalCodestringPostal code of the recipientYes
data.emailstringEmail of the recipientYes
data.recipientCountrystringISO country code (2 letters, e.g., NG)Yes
data.recipientTypestringRecipient type: personal or businessYes
data.nickNamestringNickname 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

FieldTypeDescription
successbooltrue on success
messagestring"Account successfully linked!"
data.idstringLinked 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