> ## Documentation Index
> Fetch the complete documentation index at: https://docs.singapay.id/llms.txt
> Use this file to discover all available pages before exploring further.

# Overview

> Enable customers to withdraw cash from ATMs without a card — using an OTP issued by SingaPay and the customer's registered phone number.

Cardless Withdrawal lets your customers withdraw cash at supported ATMs without a physical card. Your platform requests a withdrawal on behalf of the customer, SingaPay locks the merchant balance and issues an OTP, and the customer redeems it at the ATM using their phone number and OTP code.

<Info>
  This is a **Money Out** operation. Each successful withdrawal debits funds from your Singapay Payment Gateway merchant balance.
</Info>

<CardGroup cols={3}>
  <Card title="No card required" icon="mobile">
    Customers withdraw using only their phone number and a one-time OTP — no physical card needed.
  </Card>

  <Card title="Balance locked on issuance" icon="lock">
    Merchant balance is locked immediately when the OTP is generated — guaranteeing funds are available at ATM redemption.
  </Card>

  <Card title="Auto-reverse on failure" icon="rotate-left">
    If the OTP expires or the ATM rejects the transaction, SingaPay automatically reverses the locked balance back to the merchant.
  </Card>
</CardGroup>

***

## Withdrawal Flow

```mermaid theme={null}
sequenceDiagram
    participant C as Customer
    participant M as Merchant System
    participant S as SingaPay API
    participant A as ATM

    C->>M: Request withdrawal (bank type, amount, CustID/phone number)
    M->>M: Validate request
    M->>S: POST /cardless-withdrawals/{account_id}
    Note over M,S: bank_type, amount, cust_id

    S->>S: Lock merchant balance, generate OTP & expired_at (status: OPEN)
    S-->>M: OTP, CustID, expired_at

    M->>C: Forward OTP, CustID, expired_at & withdrawal instructions

    C->>A: Select cardless menu, input CustID + OTP
    A->>S: Validate CustID + OTP

    alt Success — Data Valid
        A->>C: Dispense cash
        A->>S: Withdrawal success notification
        S->>S: Status: OPEN → SUCCESS
        S-->>M: Webhook callback (SUCCESS)
        M->>C: Notify withdrawal successful
    else Failed / Expired — Invalid data or OTP expired
        A->>S: Withdrawal failed / expired notification
        S->>S: Reverse merchant balance
        S->>S: Status: OPEN → FAILED / EXPIRED
        S-->>M: Webhook callback (FAILED / EXPIRED)
        M->>C: Notify failure (FAILED / EXPIRED)
        M->>M: Refund customer internal balance (if applicable)
    end
```

***

## Transaction Status

| Status    | Description                                                                      |
| --------- | -------------------------------------------------------------------------------- |
| `OPEN`    | OTP issued and active — awaiting customer ATM input. Merchant balance is locked. |
| `SUCCESS` | Cash dispensed at ATM. Funds deducted from merchant balance.                     |
| `FAILED`  | ATM rejected the transaction — invalid OTP or CustID. Merchant balance reversed. |
| `EXPIRED` | OTP expired before ATM redemption. Merchant balance automatically reversed.      |

***

## Recommended Flow

<Steps>
  <Step title="Customer initiates withdrawal">
    Customer submits a cardless withdrawal request on your platform — providing the desired amount and their registered phone number (CustID).
  </Step>

  <Step title="Request OTP from SingaPay">
    Call **Create Cardless Withdrawal** with the bank type, amount, and CustID. SingaPay locks the merchant balance and returns an OTP with an expiry time.
  </Step>

  <Step title="Deliver credentials to customer">
    Forward the OTP, CustID, and expiry time to the customer along with ATM usage instructions.
  </Step>

  <Step title="Customer redeems at ATM">
    Customer visits the supported ATM, selects the cardless withdrawal menu, and enters their CustID and OTP.
  </Step>

  <Step title="Receive webhook notification">
    SingaPay sends a webhook callback to your system with the final transaction status — `SUCCESS`, `FAILED`, or `EXPIRED`.
  </Step>

  <Step title="Verify status (optional)">
    Call **Show Cardless Withdrawal** or **List Cardless Withdrawals** to confirm the final status and reconcile your records.
  </Step>
</Steps>

***

## Important Notes

<AccordionGroup>
  <Accordion title="Balance locked on OTP issuance" icon="lock">
    The merchant balance is locked the moment a withdrawal request is created. If the transaction fails or expires, SingaPay automatically reverses the locked amount back to the merchant balance — no manual action required.
  </Accordion>

  <Accordion title="OTP expiry" icon="clock">
    Each OTP has a fixed expiry defined by the `expired_at` field returned in the API response. Customers must redeem the OTP at an ATM before this timestamp. Expired transactions cannot be re-used — create a new withdrawal request instead.
  </Accordion>

  <Accordion title="Supported ATM banks" icon="building-columns">
    Only ATMs from the bank specified in the `bank_type` parameter can process the withdrawal. Ensure customers are directed to the correct ATM network.
  </Accordion>

  <Accordion title="Cancellation" icon="ban">
    Only transactions with status `OPEN` can be cancelled. Once a transaction reaches `SUCCESS`, `FAILED`, or `EXPIRED`, it cannot be cancelled.
  </Accordion>

  <Accordion title="Customer internal balance" icon="rotate-left">
    If your platform maintains an internal customer balance, remember to refund it when a transaction results in `FAILED` or `EXPIRED` — SingaPay reverses the merchant balance, but internal platform balance adjustments are the merchant's responsibility.
  </Accordion>
</AccordionGroup>

***

## Available Endpoints

<CardGroup cols={2}>
  <Card title="Create Cardless Withdrawal" icon="plus" href="./create">
    Initiate a withdrawal request and receive the OTP and CustID credentials to deliver to the customer.
  </Card>

  <Card title="List Cardless Withdrawals" icon="list" href="./list">
    Retrieve a paginated list of all cardless withdrawal transactions for an account.
  </Card>

  <Card title="Show Cardless Withdrawal" icon="eye" href="./show-detail">
    Get detailed information about a specific cardless withdrawal transaction.
  </Card>

  <Card title="Cancel Cardless Withdrawal" icon="ban" href="./cancel">
    Cancel an `OPEN` cardless withdrawal transaction before it is redeemed at an ATM.
  </Card>
</CardGroup>

<Note>
  All endpoints require authentication. See [Authentication](/api-reference/authentication).
</Note>