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

# Create an onramp

> Start a payment where the customer pays fiat and receives stablecoin.

Requires the **Ramps, banks & methods** scope (onramp write). See [Onramp](https://docs.bridge.linkio.world/flows/onramp.md) for a walkthrough.

Onramps are always first party: the customer pays for themselves and receives the stablecoin in their own wallet.

## Headers

**API-Version** `string` *required* (default: 2026-10-29-atlas)

Your account's API version.

**Idempotency-Key** `string`

Recommended. A unique value so retries don't create a second payment.

## Body

**customer\_id** `string` *required*

The customer. Must match the quote's customer.

**quote\_id** `string` *required*

An unexpired, unused onramp quote.

**payment\_details** `object` *required*

The wallet that receives the stablecoin.

**fields**

**type** `string` *required*

Always `stablecoin`.

**currency** `string` *required*

Must match the quote's `target_currency`.

**details.address** `string` *required*

The wallet address. Must be valid for the network.

**details.network** `string` *required*

Must match the quote's `network`.

**payer** `object`

**Required for mobile money.** The wallet that pays.

**fields**

**type** `string` *required*

`momo`. Must match the quote's `payment_method`.

**currency** `string` *required*

The fiat currency, for example `GHS`. Must match the quote's `source_currency`.

**details.bank\_code** `string` *required*

The network code, for example `0004` for MTN.

**details.account\_number** `string` *required*

The mobile money number, 10 to 12 digits.

**details.account\_name** `string` *required*

The name the wallet is registered to.

## Response

`202 Accepted`

**status** `string`

`success`

**message** `string`

`Onramp payment initiated`

**payment** `object`

**fields**

**id** `string`

Payment ID, starting with `pay_`.

**status** `string`

`pending`

**state** `string`

The current state, usually `initiated`.

**event\_id** `string`

The first event's ID.

**trace\_id** `string`

Sometimes included. Useful for support.

**deposit** `object`

Where the customer pays.

**fields**

**type** `string`

`bank_transfer` or `momo`.

**currency** `string`

The fiat currency, for example `NGN` or `GHS`.

**details** `object`

Bank transfer: `account_name`, `account_number`, `bank_name`. Mobile money: `phone_number`, `network`, `next_step`, `instruction`.

**amount** `string`

The quoted amount.

**amount\_expected** `string`

The exact amount the customer must send, including any fees.

**processor\_fee** `string`

Processing fee, if any.

**vat** `string`

VAT on the fee, if any.

**note** `string`

Sometimes included. Extra instructions.

## Errors

| Status | Code | Why |
| - | - | - |
| `422` | `validation_failed` | A field is wrong. See the [common messages](https://docs.bridge.linkio.world/flows/onramp.md#what-can-go-wrong-when-you-create-it). |
| `400` | `quote_expired` | The quote has expired. |
| `409` | `quote_locked` | The quote has already been used. |
| `404` | `quote_not_found` | No such quote. |
| `404` | `customer_not_found` | No such customer. |
| `409` | `customer_banned` | The customer is banned. |
| `403` | `pair_not_enabled` | The pair is turned off. |
| `409` | `idempotency_conflict` | Same key still running, or used with a different body. |
| `422` | `payment_processing_failed` | Our partner couldn't create the payment. |
| `503` | `route_temporarily_unavailable` | The route is temporarily down. |
| `504` | `request_timeout` | A partner took too long. Retry with the same `Idempotency-Key`. |

```bash NGN bank transfer theme={null}
curl -X POST https://sandbox.core.linkio.world/api/payments/onramp \
  -H "X-BRIDGE-API-Key: $BRIDGE_API_KEY" \
  -H "API-Version: 2026-10-29-atlas" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-1001" \
  -d '{
    "customer_id": "cus_4hT9pL2mQx8VnR3tY7wZ1cB5dE",
    "quote_id": "qte_9xLp3VnR7tY1wZ4cB6dE8fK2mQ",
    "payment_details": {
      "type": "stablecoin",
      "currency": "USDC",
      "details": { "address": "6KhMtrKUhYGqVVgV6fcr1Vr1XnQtZCrDwpXTNZHPiReR", "network": "solana" }
    }
  }'
```

```bash GHS mobile money theme={null}
curl -X POST https://sandbox.core.linkio.world/api/payments/onramp \
  -H "X-BRIDGE-API-Key: $BRIDGE_API_KEY" \
  -H "API-Version: 2026-10-29-atlas" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-1002" \
  -d '{
    "customer_id": "cus_2mQ9xLp3VnR7tY1wZ4cB6dE8fK",
    "quote_id": "qte_2mQ9xLp3VnR7tY1wZ4cB6dE8fK",
    "payment_details": {
      "type": "stablecoin",
      "currency": "USDC",
      "details": { "address": "0x5aAeb6053F3E94C9b9A09f33669435E7Ef1BeAed", "network": "base" }
    },
    "payer": {
      "type": "momo",
      "currency": "GHS",
      "details": { "bank_code": "0004", "account_number": "0241234567", "account_name": "Kwame Mensah" }
    }
  }'
```

```json 202 theme={null}
{
  "status": "success",
  "message": "Onramp payment initiated",
  "payment": {
    "id": "pay_8fK2mQ9xLp3VnR7tY1wZ4cB6dE",
    "status": "pending",
    "state": "initiated",
    "event_id": "evt_2cB6dE8fK2mQ9xLp3VnR7tY1wZ",
    "deposit": {
      "type": "bank_transfer",
      "currency": "NGN",
      "details": {
        "account_name": "Bridge / Ada Obi",
        "account_number": "9912345678",
        "bank_name": "Example Bank"
      },
      "amount": "150000",
      "amount_expected": "150150",
      "processor_fee": "150"
    }
  }
}
```

```json 400 theme={null}
{
  "error": {
    "type": "invalid_request_error",
    "code": "quote_expired",
    "message": "Quote qte_9xLp3VnR7tY1wZ4cB6dE8fK2mQ has expired",
    "request_id": "req_3VnR7tY1wZ4cB6dE8fK2mQ9xLp",
    "status": 400
  }
}
```

```json 422 theme={null}
{
  "error": {
    "type": "validation_error",
    "code": "validation_failed",
    "message": "Wallet network must match the quote network",
    "request_id": "req_3VnR7tY1wZ4cB6dE8fK2mQ9xLp",
    "status": 422,
    "errors": [
      { "field": "payment_details.details.network", "message": "Wallet network must match the quote network" }
    ]
  }
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.