Withdraw to Linked Account

​

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

​

Headers

​

Request Body

​

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"
  }'

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

​

Transaction Statuses

​

Error (4xx / 5xx)

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

​

Error Cases

​

Payout Types

​

Validation Rules

• amount — Required. Number greater than 0.
• walletType — Required. Must be "SPEND" (uppercase).
• reason — Optional. String.
• routingType — Optional. If provided, must be one of: ACH, RTP, WIRE, BANK. Omit for default bank transfer behaviour.
• currency — From path parameter. Must be USD.
• linkedAccountId — From path parameter. Must be a valid UUID of a linked account for the authenticated entity.
• MFA — Not required. Do not include mfaCode.

​

Payment-Link / Merchant-Funded

• The amount in the body must exactly match the amount on the application token; otherwise returns 400 "Malformed request".
• On success, the application token is invalidated immediately and cannot be reused.

​

Notes

• The linked account must be associated with the authenticated entity’s SPEND wallet.
• A success response means the payout has been queued or dispatched. Final settlement may be asynchronous — use the transaction status endpoint or webhooks to confirm.
• No idempotency keys are supported. Implement client-side deduplication if needed.
• Rate limited to 1 request per minute per user.