> 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/hosted-ramp/deposits.md).

# Deposits

## Initiate Deposit

Create a hosted **deposit** with the `initiateHostedPayment` mutation.

```graphql
mutation {
  initiateHostedPayment(
    paymentType: deposit
    amount: 100
    currency: usd
    countryCode: "NG"
    reference: "test_ref_1"
    metadata: { customer_id: "2e7d57e2-a10e-4420-9d05-e109627a157a" }
    redirectUrl: "https://useaccrue.com"
    firstName: "Clinton"
    lastName: "Mbah"
    email: "test@useaccrue.com"
    onchainTransferInfo: { address: "0x1234567890abcdef1234567890abcdef12345678", cryptocurrency: usd_coin, network: base }
  ) {
    id
    hostedLink
    status
  }
}
```

### Arguments

<table><thead><tr><th width="146.88885498046875">Name</th><th width="114.77783203125">Type</th><th width="96.5555419921875">Required</th><th>Description</th></tr></thead><tbody><tr><td><code>paymentType</code></td><td><code>Enum</code></td><td><strong>Yes</strong></td><td>Must be <code>deposit</code>.</td></tr><tr><td><code>amount</code></td><td><code>Decimal</code></td><td><strong>Yes</strong></td><td>Amount to charge the customer.</td></tr><tr><td><code>currency</code></td><td><code>Enum</code></td><td><strong>Yes</strong></td><td><code>usd</code> to charge in USD, or <code>local_currency</code> to charge in the currency derived from <code>countryCode</code>.</td></tr><tr><td><code>countryCode</code></td><td><code>String</code></td><td><strong>Yes</strong></td><td>ISO-3166 alpha-2 code of the customer’s country (e.g., <code>NG</code>).</td></tr><tr><td><code>reference</code></td><td><code>String</code></td><td>No</td><td>Your idempotent reference for reconciliation.</td></tr><tr><td><code>metadata</code></td><td><code>JSON</code></td><td>No</td><td>Arbitrary key–value data echoed in webhooks.</td></tr><tr><td><code>developerSurcharge</code></td><td><code>Decimal</code></td><td>No</td><td>Your margin on this payment as a percentage of the exchange rate (e.g. <code>0.5</code> for 0.5%), credited to your balance when it completes. Overrides the developer surcharge set in your dashboard for this payment only. Between <code>0</code> and <code>5</code>; <code>0</code> charges none. Omit it to use your dashboard setting.</td></tr><tr><td><code>redirectUrl</code></td><td><code>String</code></td><td>No</td><td>URL to send the customer to after payment.</td></tr><tr><td><code>firstName</code></td><td><code>String</code></td><td><strong>Yes</strong></td><td>Customer’s first name.</td></tr><tr><td><code>lastName</code></td><td><code>String</code></td><td><strong>Yes</strong></td><td>Customer’s last name.</td></tr><tr><td><code>email</code></td><td><code>String</code></td><td><strong>Yes</strong></td><td>Customer’s email address.</td></tr><tr><td><code>onchainTransferInfo</code></td><td><code>OnchainTransferInfo</code></td><td>No</td><td>Deliver the stablecoins onchain when the deposit completes. Provide <code>address</code>, <code>cryptocurrency</code> (<code>usd_coin</code> or <code>usd_tether</code>) and <code>network</code>. The network fee is the one <code>withdrawableAssets(caller: ramp)</code> returns. See <a href="#onchain-delivery">Onchain delivery</a>.</td></tr></tbody></table>

### Response

<table><thead><tr><th width="127.88885498046875">Field</th><th width="111.111083984375">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>id</code></td><td><code>ID!</code></td><td>Global ID of the payment request.</td></tr><tr><td><code>hostedLink</code></td><td><code>String!</code></td><td>URL of the hosted checkout page—redirect the customer here.</td></tr><tr><td><code>status</code></td><td><code>Enum!</code></td><td>Current state of the request (values below).</td></tr></tbody></table>

`status` values:

* **`created`** — Payment request has been created.
* **`picked_up`** — Customer has selected an agent and is making the deposit.
* **`completed`** — Deposit succeeded; your Cashramp balance is credited, or the stablecoins are sent to the `onchainTransferInfo` address.
* **`canceled`** — Request was cancelled by the customer or via dispute resolution.

## Onchain delivery

Pass `onchainTransferInfo` to send the deposit to a wallet when it completes instead of crediting your balance. Your usual Cashramp fee applies and is taken off the amount delivered. The network fee depends on your **Debit network fees from customer deposit** setting:

| Setting       | `currency: usd`                                                             | `currency: local_currency`                                                              |
| ------------- | --------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- |
| Off (default) | The customer pays `amount` plus the network fee.                            | The customer pays `amount` plus the network fee in local currency, at the agent's rate. |
| On            | The customer pays `amount`; the network fee comes off the amount delivered. | The customer pays exactly `amount`; the network fee comes off its USD equivalent.       |
