Execute Withdrawal

Executes a withdrawal from a customer's account to a saved beneficiary (payee). This endpoint moves real money.

Prerequisites

The source account must be approved with a balance ≥ amount + fees.

beneficiary.payeeId must be a saved, verified payee of the customer.

For regulated corridors, fetch a valid purpose code first via GET /api/v1/accountwithdrawal/purpose.

Strongly recommended: get a quote first so fees and FX are known to the user.

⚠️ Important

Withdrawals are asynchronous: a 200 acknowledges acceptance with status created; settlement happens on the rails afterwards. Track completion via webhooks.

Use a fresh X-Nonce per attempt; retrying with the same nonce is rejected as a replay.

Insufficient balance returns 409 INSUFFICIENT_FUNDS — no funds are moved.

Status values

Status	Meaning
`submitted`	Accepted and queued
`pending`	Sent to the payment rails
`approved`	Settled to the beneficiary
`rejected`	Rejected; funds returned to source

Related endpoints: POST /api/v1/accountwithdrawal/quote · GET /api/v1/accountwithdrawal/purpose

⚠️ Required Fields

Field	Type	Description	Constraints
`customer`	`object`	Wrapper for the customer reference	-
`customer.id`	`string (uuid)`	Customer making the withdrawal	Required
`source`	`object`	Source account and amount	-
`source.accountId`	`string (uuid)`	ArthaPay account to debit	Required
`source.amount`	`number (double)`	Amount to debit from the source account	Required · Min: 0.01 · Max: 1,000,000,000
`beneficiary`	`object`	Target payee	-
`beneficiary.payeeId`	`string (uuid)`	Saved payee to pay	Required

Optional Fields

Field	Type	Description	Constraints
`source.currency`	`string`	ISO-4217 currency of `source.amount` (defaults to the account currency)	Nullable
`beneficiary.currency`	`string`	ISO-4217 currency the beneficiary should receive	Nullable
`payment`	`object`	Payment rail preferences	Nullable
`payment.scheme`	`string`	Rail: `sepa`, `sepa_instant`, `swift`, `faster_payments`	Max: 50 · Nullable

📤 Response Fields

Field	Type	Nullable	Description
`data.id`	`string (uuid)`	No	Withdrawal ID — use for reconciliation and webhook correlation
`data.status`	`string`	No	`created` \| `processing` \| `completed` \| `failed` \| `cancelled`
`data.sourceAmount`	`object`	No	`{ value, currency }` debited
`data.targetAmount`	`object`	Yes	`{ value, currency }` the beneficiary receives (null until FX applied)
`data.fee`	`object`	No	`{ value, currency }` fee charged
`data.scheme`	`string`	No	Payment rail used
`data.payeeId`	`string (uuid)`	No	Beneficiary paid
`data.createdAt`	`string (date-time)`	No	UTC creation timestamp

curl --location '/api/v1/accountwithdrawal/withdraw' \ --header 'X-API-Key: ak_live_8f3a9b2c1d4e5f6a7b8c' \ --header 'X-Signature: q2h8Zx0kPz5mVw7Yb3Nc1Rt6Ue9Ia4Od2Sf8Gk0Jl4=' \ --header 'X-Timestamp: 1754812800' \ --header 'X-Nonce: f47ac10b-58cc-4372-a567-0e02b2c3d479' \ --header 'X-Body-Hash: n4bQgYhMfWWaL+qgxVrQFaO/TxsrC4Is0V1sFbDwCgg=' \ --header 'Content-Type: application/json-patch+json' \ --data '{ "customer": { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "source": { "accountId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "amount": 1000000000, "currency": "string" }, "beneficiary": { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "payment": { "scheme": "string" } }'

{ "data": { "id": "e8a1c4d7-2f5b-4e8a-b1d4-7c0e3f6a9b2d", "status": "created", "sourceAmount": { "value": 2500, "currency": "EUR" }, "targetAmount": { "value": 2891.25, "currency": "USD" }, "fee": { "value": 6.5, "currency": "EUR" }, "scheme": "swift", "payeeId": "9b2f5c1e-8d3a-4f6b-b2e1-0c7d4a5e6f8b", "createdAt": "2026-08-10T09:31:12Z" } }

Request

Responses