# Withdrawals

Convert USD stablecoins to local African currencies using Direct Ramp withdrawals. This guide covers the complete withdrawal lifecycle, from initiation to settlement.

## Withdrawal Flow

1. Get a valid [ramp quote](https://docs.cashramp.co/cashramp/direct-ramp/ramp-quotes)
2. Initiate withdrawal with quote
3. Wait for withdrawal to be processed
4. Mark withdrawal as received

## Initiating a Withdrawal

Use `initiateRampQuoteWithdrawal` to create a new withdrawal request.

### Arguments

| Argument        | Type     | Required | Description                                                                                                                |
| --------------- | -------- | -------- | -------------------------------------------------------------------------------------------------------------------------- |
| `rampQuote`     | `ID!`    | **Yes**  | Quote ID from `rampQuote` query                                                                                            |
| `paymentMethod` | `ID!`    | **Yes**  | Your customer's payment method ID ([Add a Payment Method](https://docs.cashramp.co/cashramp/cashramp-api/payment-methods)) |
| `reference`     | `String` | No       | Your unique reference for reconciliation                                                                                   |

```graphql
mutation {
  initiateRampQuoteWithdrawal(
    rampQuote: "quote_id"
    paymentMethod: "payment_method_id"
    reference: "order_123"
  ) {
    id
    status
    agent
    paymentDetails
    exchangeRate
    amountUsd
    amountLocal
  }
}
```

### Response

| Field            | Type       | Description                                                    |
| ---------------- | ---------- | -------------------------------------------------------------- |
| `id`             | `ID!`      | Global ID for the deposit request                              |
| `status`         | `String!`  | Current status (see Status Lifecycle)                          |
| `agent`          | `String!`  | Assigned payout agent                                          |
| `paymentDetails` | `String!`  | User's payout instructions (bank details, mobile money number) |
| `exchangeRate`   | `Decimal!` | Locked FX rate for this withdrawal                             |
| `amountLocal`    | `Decimal!` | Amount in local currency                                       |
| `amountUsd`      | `Decimal!` | Amount in USD stablecoins                                      |

## Status Lifecycle

| Status      | Description                     | Next Steps              |
| ----------- | ------------------------------- | ----------------------- |
| `accepted`  | Initial state                   | Awaiting payout         |
| `paid`      | Local currency payout completed | Customer received funds |
| `completed` | Transaction settled             | -                       |
| `canceled`  | Manually canceled               | -                       |

## Marking as Received

Use `markWithdrawalAsReceived` to allow your customer to indicate that they have received the funds.

{% hint style="success" %}
We recommend adding a "I've received the payment" button which triggers `markWithdrawalAsReceived` .
{% endhint %}

### Arguments

| Argument         | Type  | Required | Description           |
| ---------------- | ----- | -------- | --------------------- |
| `paymentRequest` | `ID!` | **Yes**  | Withdrawal request ID |

```graphql
mutation {
  markWithdrawalAsReceived(paymentRequest: "withdrawal_id")
}
```