Skip to main content

​
Endpoint

  • Method: POST
  • URL: {{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 Body

FieldTypeDescriptionRequired
labelstringDisplay name for the linked accountYes
data.recipientTypestringpersonal or businessYes
data.firstNamestringFirst name (required if personal)Conditional
data.lastNamestringLast name (required if personal)Conditional
data.namestringBusiness name (required if business)Conditional
data.emailstringEmail of the recipientYes
data.accountNumberstringInternational bank account number (IBAN or local)Yes
data.swiftOrBicstringSWIFT/BIC codeYes
data.bankNamestringName of the international bankYes
data.recipientAddressstringStreet address of the recipientYes
data.recipientCitystringCity of the recipientYes
data.recipientStatestringState/region of the recipientYes
data.recipientCountrystringISO 3166-1 alpha-2 country code (e.g., NG, GB)Yes
data.recipientPostalCodestringPostal code of the recipientYes
data.nickNamestringOptional nickname for this account. If omitted, top-level label is used.No

​
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": "International Wire",
    "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"
    }
  }'

​
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

  • Country codes should use ISO 3166-1 alpha-2 format (e.g., GB, NG, US)
  • SWIFT/BIC codes should match the destination bank
  • Store the id from the response for withdrawal requests