---
updatedAt: 2026-08-27T09:31:28.000Z
agentTools:
  projectIndex: https://docs.praxis.tech/llms.txt
---

# Withdrawal Management

Withdrawal management is the process of handling a customer's request for funds, including merchant approval, processing, and eventual fulfillment via subsequent payout or refund transactions.

# 1. Core Definitions

Understanding these terms is critical for managing fund reversals and disbursements:

| Term           | Purpose                                                                                                     | Relationship                                                                                     |
| :------------- | :---------------------------------------------------------------------------------------------------------- | :----------------------------------------------------------------------------------------------- |
| **Withdrawal** | Represents the customer's request (a trigger) to receive funds from the merchant.                           | Deducts the amount from the customer's account balance, but **is not the fund transfer itself**. |
| **Payout**     | An actual fund transfer initiated by the merchant to the customer's credit card, bank account, or e-wallet. | **Disbursement** of funds, often associated with a Withdrawal Request.                           |
| **Refund**     | The reversal of a **previous deposit** transaction.                                                         | Funds are always processed back to the **original payment method**.                              |

<Callout icon="⚠️" theme="warn">
   **Key Distinction:** A cancelled authorization is **not** a refund. Cancellation simply lifts a temporary lock on funds in the customer's account; it does not involve any actual fund transfer.
</Callout>

***

# 2. Withdrawal Management Process

The withdrawal process involves two distinct stages: the initial request and the subsequent fulfillment transaction(s).

## A. Initiation

The process begins when a customer submits a request via the **Cashier** or **Virtual Terminal** (with the `intent` set to `withdrawal`).

<Callout icon="🛑" theme="error">
  **IMPORTANT:** The initial withdrawal request only **records the liability** in the system. It **does not initiate a fund transfer**. The transfer awaits merchant approval.
</Callout>

## B. Fulfillment (Disbursement)

Once a withdrawal request is created and approved, the merchant fulfills the request by initiating one or more of the following **transfer transactions** via the **Server to Server API** or the Atlas dashboard.

<Callout icon="📘" theme="info">
  You can manage the withdrawal request using <Anchor target="_blank" href="/reference/completeorcancelwithdrawalrequest">Complete or Cancel Withdrawal Request API</Anchor>  or split the withdrawal request using <Anchor target="_blank" href="/reference/createsplitwithdrawalrequest">Create Split Withdrawal Request API</Anchor>
</Callout>

* <Anchor target="_blank" href="/reference/createpayoutcard">**Card Payout**</Anchor>
* **APM Payout**
  * <Anchor target="_blank" href="/reference/createpayoutapmrequest">**Payout with wallet data**</Anchor>
  * <Anchor target="_blank" href="/reference/createpayoutapmwallettokenrequest">**Payout wallet token**</Anchor>
* <Anchor target="_blank" href="/reference/createrefund">**Refund**</Anchor>

## C. Linking Transactions

Fulfillment may involve one or multiple transactions (payouts or refunds) to cover the total withdrawal amount.

<Callout icon="🚧" theme="warn">
  **CRITICAL LINKAGE:** To ensure the system correctly associates the fund transfer with the customer's withdrawal request, you **must** pass the `withdrawal_request_id` parameter, set to the `tid` of the original withdrawal request, in the body of the payout or refund API call. If this parameter is omitted, the transaction is treated as a standalone transfer.
</Callout>

# 3. Cashier Withdrawal Sequence Flow

The following sequence illustrates the three primary stages of processing a withdrawal request through the Cashier: **Initiation**, **Validation** (e.g., checking user balance), and **Notification**.

```mermaid
---
config:
  theme: dark
---
sequenceDiagram
    autonumber
    actor User as Customer
    participant Merchant as Merchant
    participant Cashier as Praxis Cashier
    participant BackOffice as Praxis Backoffice

     
        Note over User,BackOffice: Stage 1 — Transaction Initiation

        User ->> Merchant: Submits withdrawal request

        Merchant ->> Cashier: POST /cashier/cashier<br/>intent=withdrawal, notification_url,<br/>validation_url, order_id, cid, currency
        Cashier -->> Merchant: Returns redirect_url + auth_token
        Merchant ->> User: Redirect to Cashier<br/>(redirect_url) or embed via iframe / SDK

        User ->> Cashier: Selects payment method,<br/>enters details and submits


     
        Note over User,BackOffice: Stage 2 — Validation - e.g. for checking balance

        Cashier ->> Merchant: POST /api/validation to validation_url<br/>Transaction + session details
        Merchant -->> Cashier: Approve or reject

        alt Validation rejected
            Cashier ->> User: Shows withdrawal rejected
        else Validation approved
            Merchant ->> Merchant: Create hold for withdrawal amount<br>so the user cannot spend it

            Cashier ->> User: Shows "Withdrawal Request Accepted"
            Cashier ->> Merchant: POST api/notification to notification_url<br/>Withdrawal Request Created


    end



Note over User,BackOffice: Stage 3 — Approval/decline
Merchant ->> BackOffice: Withdrawal request available for review
BackOffice ->> BackOffice: Merchant or Rule Engine<br/>approves or declines

alt Withdrawal Approved and processed with PSP
    Cashier ->> Merchant: POST api/notification to notification_url<br/>Withdrawal Approved
            Merchant ->> Merchant: Capture hold<br/>Deduct amount from user's balance
else Withdrawal Declined/Failed at PSP
    Cashier ->> Merchant: POST api/notification to notification_url<br/>Withdrawal Declined
            Merchant ->> Merchant: Release hold<br/>Return amount to user's available balance
        end
```