# Deposits

Convert local African currency payments into USD stablecoins using Direct Ramp deposits. This guide covers the complete deposit lifecycle, from initiation to settlement.

## Deposit Flow

1. Get a valid [ramp quote](https://docs.cashramp.co/cashramp/direct-ramp/ramp-quotes)
2. Initiate deposit with quote
3. Share payment details with customer
4. Mark deposit as paid
5. Receive stablecoin settlement

## Initiating a Deposit

Use `initiateRampQuoteDeposit` to create a new deposit request.

### Arguments

| Argument              | Type                | Required | Description                                                                                    |
| --------------------- | ------------------- | -------- | ---------------------------------------------------------------------------------------------- |
| `rampQuote`           | `ID!`               | **Yes**  | Quote ID from `rampQuote` query                                                                |
| `reference`           | `String`            | No       | Your unique reference for reconciliation                                                       |
| `phoneNumber`         | String              | No       | Customer's phone number if paying via MoMo                                                     |
| `bankAccountNumber`   | String              | No       | Customer's bank account number if paying via bank                                              |
| `onchainTransferInfo` | OnchainTransferInfo | No       | If you want to deliver the stablecoins onchain, provide `address`, `cryptocurrency`, `network` |

{% code overflow="wrap" %}

```graphql
mutation {
  initiateRampQuoteDeposit(rampQuote: "quote_id", reference: "order_123", phoneNumber: "", bankAccountNumber: "", onchainTransferInfo: { address: "0x1234567890abcdef1234567890abcdef12345678", cryptocurrency: "usd_tether", network: "celo" }) {
    id
    status
    agent
    paymentDetails
    exchangeRate
    amountLocal
    amountUsd
    expiresAt
  }
}
```

{% endcode %}

{% hint style="success" %}
Provide your customer's payment method information (phone number for MoMo payments or bank account number for bank transfers) to help our agents quickly verify and confirm payments.
{% endhint %}

### Response

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

## Status Lifecycle

| Status      | Description                                 | Next Steps                          |
| ----------- | ------------------------------------------- | ----------------------------------- |
| `pending`   | Initial state                               | Share payment details with customer |
| `paid`      | Customer funds transferred & marked as paid | Await settlement                    |
| `completed` | Funds settled                               | -                                   |
| `canceled`  | Manually canceled                           | -                                   |

## Marking as Paid

After your customer transfers the local currency to the payment instructions we provide, use the `markDepositAsPaid`  mutation to begin the settlement process.

{% hint style="success" %}
We recommend adding an "I've made the payment" button which triggers `markDepositAsPaid`.
{% endhint %}

### Arguments

| Argument         | Type     | Required | Description        |
| ---------------- | -------- | -------- | ------------------ |
| `paymentRequest` | `ID!`    | **Yes**  | Deposit request ID |
| `receipt`        | `String` | No       | Payment proof URL  |

```graphql
mutation {
  markDepositAsPaid(
    paymentRequest: "deposit_id"
    receipt: "https://example.com/receipt.png"
  )
}
```

## Cancelling a Deposit

Cancel an initiated but unpaid deposit with `cancelDeposit` (only possible if the status is `created`).

```graphql
mutation {
  cancelDeposit(paymentRequest: "deposit_id")
}
```