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.

⚠️
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.

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).

🛑
IMPORTANT: The initial withdrawal request only records the liability in the system. It does not initiate a fund transfer. The transfer awaits merchant approval.

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.

📘
You can manage the withdrawal request using Complete or Cancel Withdrawal Request API or split the withdrawal request using Create Split Withdrawal Request API

Card Payout
APM Payout
- Payout with wallet data
- Payout wallet token
Refund

C. Linking Transactions

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

🚧
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.

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.

---
config:
  theme: dark
---
sequenceDiagram
    autonumber
    actor User as Customer
    participant Merchant as Merchant
    participant Cashier as Payracks Cashier
    participant BackOffice as Payracks 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