Skip to main content

​
Overview

Withdraw funds from a wallet to a linked account (bank, card, or international bank). This endpoint allows you to initiate payouts to any account that has been previously linked.

​
Prerequisites

  • A linked account ID (obtained from linking an account)
  • Valid access token
  • Sufficient wallet balance

​
Endpoint

  • POST {{LIQUIDITY_URL}}/v1/ext/linked-accounts/:currency/:linkedAccountId/withdrawal
  • Auth: Bearer {{accessToken}}

​
Path Parameters

ParameterTypeDescriptionRequired
currencystringCurrency code (e.g., USD)Yes
linkedAccountIdstringID of the linked account (from link response)Yes

​
Query Parameters

ParameterTypeDescriptionRequired
walletIdstringSource wallet ID (optional, uses default if omitted)No

​
Request

curl -X POST "{{LIQUIDITY_URL}}/v1/ext/linked-accounts/USD/{{linkedAccountId}}/withdrawal?walletId={{walletId}}" \
  -H "Authorization: Bearer {{accessToken}}" \
  -H "Content-Type: application/json" \
  -d '{
    "reason": "Payout to Samuel",
    "amount": 0.12,
    "transactionType": "PAYOUT",
    "routingType": "ACH"
  }'

​
Request Body Fields

FieldTypeDescriptionRequired
reasonstringDescription/reason for the withdrawalYes
amountnumberAmount to withdraw (decimal)Yes
transactionTypestringTransaction type: PAYOUTYes
routingTypestringRouting type: ACH, WIRE, or INTERNATIONAL_WIREYes

​
Routing Types

  • ACH - For US bank accounts (domestic transfers)
  • WIRE - For domestic wire transfers
  • INTERNATIONAL_WIRE - For international bank accounts

​
Response (200)

{
  "message": "Payment queued",
  "data": {
    "id": "0040acde-4b8a-4f46-9468-bacd64e70cbf",
    "status": "SUCCESS",
    "fees": "25.00",
    "amount": "2.10"
  }
}

​
Response Fields

FieldTypeDescription
messagestringStatus message
data.idstringTransaction ID for tracking
data.statusstringTransaction status (e.g., SUCCESS, PENDING)
data.feesstringFees charged for the withdrawal
data.amountstringFinal amount after fees

​
Notes

  • The linkedAccountId must be from a successfully linked account
  • Use the appropriate routingType based on the linked account type:
    • ACH for US bank accounts
    • INTERNATIONAL_WIRE for international bank accounts
    • WIRE for domestic wire transfers
  • If walletId is not provided, the system will use the default wallet for the entity
  • Ensure sufficient balance in the source wallet to cover the amount plus fees
  • Withdrawal processing times vary by routing type:
    • ACH: Typically 1-3 business days
    • Wire: Typically same day or next business day
    • International Wire: Typically 3-5 business days
  • Store the transaction id for tracking and reconciliation purposes
  • Fees may vary based on routing type and amount
  • Works for all linked account option types (bank, card, international_bank, zelle, venmo, paypal, prepaid_card)