Withdraw to Linked Account

​

Overview

​

How it works

1. Auth – Request must include a valid Bearer token; claims.sub is the entity (user/business) making the withdrawal.
2. Linked account – linkedAccountId must exist and its wallet must be associated with that entity.
3. Validation – Body is validated (amount, currency, walletType, reason; MFA is not required for this external endpoint).
4. Balance – Wallet balance must be at least amount + fees.
5. Payout – Debit wallet, create transaction, and process payout. If the linked account is a bank and routingType is RTP, real-time payment (RTP) is used; otherwise ACH is used. For card linked accounts, push-to-card is used regardless of routingType.

​

Endpoint

• POST {{LIQUIDITY_URL}}/v1/ext/linked-accounts/:currency/:linkedAccountId/withdrawal
• Auth: Bearer {{accessToken}} (scope external.apis)

​

Path Parameters

​

Headers

​

Request Body

​

Request Examples

​

RTP bank payout

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

​

ACH bank payout

{
  "amount": 250.00,
  "walletType": "SPEND",
  "reason": "Contractor payment",
  "routingType": "ACH"
}

​

Card payout (routingType optional)

{
  "amount": 50.00,
  "walletType": "SPEND",
  "reason": "Refund"
}

​

Supported Payout Types

​

Response

​

Success (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>"
  }
}

• Queued means the withdrawal was accepted and processing started. Final status may be delivered via webhooks or a separate status API.
• data.amount is the total debited from the wallet (payout amount + fees).

​

Response Fields

​

Error (4xx / 5xx)

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

​

Typical Error Cases

​

Validation Rules (Summary)

• amount – Required, number, > 0.
• walletType – Required, must be "SPEND".
• reason – Required, string.
• routingType – Optional. If present, must be one of: ACH, RTP, WIRE, BANK.
• currency – From path; must be USD (only supported currency).
• linkedAccountId – From path; 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.
• MFA – Not required for this external endpoint. Do not send mfaCode.

​

Payment-Link / Merchant-Funded Withdrawals

• amount in the body must equal the amount on the application token; otherwise the response is 400 "Malformed request".
• On success, the application token is invalidated immediately.

​

Notes for External Engineers

1. Linked account first – Ensure the payout destination is already linked (e.g. via the link-account widget/API) and that you have the correct linkedAccountId for the entity’s SPEND wallet.
2. No MFA – This external payout endpoint does not require MFA. Omit mfaCode from the request.
3. RTP for faster bank payouts – For bank linked accounts, send routingType: "RTP" to use real-time payment when supported.
4. Fees – Fees depend on payout method and configuration. The response data.fees and data.amount reflect the fee and total debit.
5. Async outcome – Success means “queued”; final success/failure may be delivered asynchronously (e.g. webhooks). Use your transaction/withdrawal status APIs or webhooks to track final state.
6. Rate limit – 1 request per minute per user (and IP). Design retries and UX accordingly.
7. Idempotency – The API does not expose idempotency keys. Retrying the same request can create multiple withdrawals. Implement your own idempotency (e.g. linkedAccountId + amount + reason + timestamp) if you need to avoid duplicates.