PApaymentology
Ledger API - Withdrawals

Create a withdrawal

<ul> <li class="docBullet">Creates a withdrawal (cash-out) operation. Single-currency only.</li> <li class="docBullet">Business-rule rejections (for example, insufficient funds) are returned as 201 with status REJECTED and failure_reason populated, not as a 4xx error.</li> </ul>
post/pty/account/v1/withdrawals

Request

  • Base URL
    https://api.uat.paymentology.com
  • URL
    https://api.uat.paymentology.com/pty/account/v1/withdrawals
  • Auth
    HTTP bearer

Request body

source_account_idstring required

Internal source account identifier

external_account_referencestring nullable

External destination account reference

transaction_referencestring required

Client-provided unique transaction reference (idempotency key). Must not contain whitespace.

transaction_descriptionstring

Human-readable description

Example request

{
  "source_account_id": "479823917",
  "external_account_reference": "EXT-DST-76521",
  "source_amount": {
    "amount": "10000",
    "currency": "USD"
  },
  "fee": {
    "amount": "200",
    "currency": "USD",
    "type": "WITHDRAWAL_FEE"
  },
  "transaction_reference": "cout_w1_001",
  "transaction_description": "Withdrawal"
}

Response

Withdrawal created

withdrawal_idstring uuid required

Unique withdrawal identifier.

source_account_idstring required

Internal source account identifier.

external_account_referencestring nullable

External destination account reference.

transaction_referencestring required

Client-provided unique transaction reference.

transaction_descriptionstring

Human-readable description.

status'IN_PROGRESS' | 'COMPLETED' | 'REJECTED' | 'FAILED' required

Transaction processing status (shared across transfers, deposits, and withdrawals).

  • IN_PROGRESS — request persisted, operation in progress (non-terminal).
  • COMPLETED — operation executed successfully (terminal).
  • REJECTED — operation refused by a business rule (terminal). The specific reason is carried in failure_reason.code.
  • FAILED — operation failed due to a transient error (non-terminal). The specific reason is carried in failure_reason.code.
updated_atstring date-time required

Timestamp of the last update.

source_account_balance_afterstring nullable

The source account's net available balance, in minor units, immediately after this withdrawal. Present only when status is COMPLETED.

Example response

{
  "withdrawal_id": "b2c3d4e5-f6a7-5890-1234-567890bcdef0",
  "source_account_id": "479823917",
  "external_account_reference": "EXT-DST-76521",
  "source_amount": {
    "amount": "10000",
    "currency": "USD"
  },
  "fee": {
    "amount": "200",
    "currency": "USD",
    "type": "WITHDRAWAL_FEE"
  },
  "transaction_reference": "cout_w1_001",
  "transaction_description": "Withdrawal",
  "failure_reason": {
    "code": "INSUFFICIENT_FUNDS",
    "message": "Source account has insufficient funds to complete this operation"
  },
  "updated_at": "2026-01-14T10:00:00Z"
}

Changes

No recorded changes to this operation across all 1 revision of this API.