Skip to main content

​
Endpoint

  • Method: POST
  • URL: {{LIQUIDITY_URL}}/v1/ext/linked-accounts/:currency/:linkedAccountId/withdrawal
  • Auth: Bearer {{accessToken}} (scope external.apis)
  • Rate limit: 1 withdrawal per minute per user (and IP). Returns 429 if exceeded.

​
Path Parameters

ParameterTypeRequiredDescription
currencystringYesCurrency code. Supported: USD only.
linkedAccountIdstringYesUUID of the linked payout account (bank or card) to send funds to. Must be a valid UUID of an existing linked account whose wallet is associated with the authenticated entity. See Link Bank Account, Link Card Account, or Link International Bank Account for how to link an account.

​
Headers

HeaderRequiredDescription
AuthorizationYesBearer <token> with scope external.apis.
Content-TypeYesapplication/json.

​
Request Body

FieldTypeRequiredDescription
amountnumberYesPayout amount (e.g. dollars for USD). Must be > 0.
walletTypestringYesMust be "SPEND". Withdrawal is from the SPEND wallet tied to the linked account.
reasonstringYesReason or reference for the payout (e.g. “Contractor payment”, “Payout”).
routingTypestringNoAllowed: ACH, RTP, WIRE, BANK. Used for bank linked accounts; ignored for card (push-to-card).
transactionTypestringNoIf "payout" (case-insensitive), treated as PAYMENT; otherwise PAYOUT.
Note: MFA is not required. Do not send mfaCode.

​
Request

curl -X POST "{{LIQUIDITY_URL}}/v1/ext/linked-accounts/USD/{{linkedAccountId}}/withdrawal" \
  -H "Authorization: Bearer {{accessToken}}" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 100.50,
    "walletType": "SPEND",
    "reason": "Contractor payment",
    "routingType": "RTP"
  }'

​
Response (200)

{
  "success": true,
  "message": "Payment queued",
  "data": {
    "id": "<transaction-uuid>",
    "status": "<TransactionStatus>",
    "fees": "<fee amount as string>",
    "amount": "<total debit amount (amount + fees) as string>"
  }
}

​
Response Fields

FieldTypeDescription
successbooleanWhether the request succeeded.
messagestringStatus message (e.g. “Payment queued”).
data.idstringTransaction UUID for tracking.
data.statusstringTransaction status (e.g. SUCCESS, PENDING).
data.feesstringFee amount as string.
data.amountstringTotal debit amount (amount + fees) as string.

​
Error (4xx / 5xx)

{
  "success": false,
  "message": "<error detail>",
  "fatal": true
}

​
Typical Error Cases

SituationHTTPMessage / cause
Invalid or missing body400Validation errors (e.g. missing amount, walletType, reason).
Invalid routingType400Only ACH, RTP, WIRE, BANK allowed.
Unauthorized / wrong scope401Invalid or expired token, or missing external.apis scope.
Linked account not found404Wrong ID or linked account not accessible.
Application token expired400Payment-link token expired/inactive.
Amount mismatch (payment link)400Merchant-funded and amount ≠ token amount.
Insufficient balance400"Insufficient Funds #912".
Rate limit4291 withdrawal per minute per user.
Server / processing error500Server or processing error.

​
Supported Payout Types

Linked account typeroutingType (optional)Result
BANKRTPReal-time payment (RTP).
BANKACH or BANK or omittedACH transfer.
BANKWIREWire (method-dependent).
CARDany or omittedPush-to-card; routingType ignored.

​
Validation Rules

  • amount – Required, number, > 0.
  • walletType – Required, must be "SPEND".
  • reason – Required, string.
  • routingType – Optional. If present: ACH, RTP, WIRE, BANK only.
  • currency – From path; must be USD (only supported currency).
  • linkedAccountId – From path; valid UUID of existing linked account for the authenticated entity. See Link Bank Account, Link Card Account, or Link International Bank Account for how to link an account.
  • MFA – Not required; do not send mfaCode.
If the request is in the context of a payment link with withdrawalSource === 'MERCHANT_WALLET':
  • amount in the body must equal the amount on the application token; otherwise 400 “Malformed request”.
  • On success, the application token is invalidated immediately.

​
Notes

  • Linked account must exist and be associated with the entity’s SPEND wallet.
  • Success response means “queued”; final status may come via webhooks or status API.
  • 1 request per minute per user (and IP). No idempotency keys; implement client-side idempotency if needed.