> For the complete documentation index, see [llms.txt](https://docs.cashramp.co/cashramp/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.cashramp.co/cashramp/direct-ramp/withdrawals.md).

# 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](/cashramp/direct-ramp/ramp-quotes.md)
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](/cashramp/cashramp-api/payment-methods.md)) |
| `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")
}
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.cashramp.co/cashramp/direct-ramp/withdrawals.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.