> ## 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.

# Onramp events

> Every event we send during an onramp: what it means and when it fires.

These events are sent while a customer pays fiat and receives stablecoin. Each one tells you the payment moved to a new state.

## Summary

| Event | State | Status | Fires when |
| - | - | - | - |
| `payment.onramp.initiated` | `initiated` | `pending` | You created the onramp. |
| `payment.onramp.quote_locked` | `quote_locked` | `pending` | The quote's price is held for this payment. |
| `payment.onramp.fiat_pending` | `fiat_pending` | `pending` | We're ready and waiting for your customer's money. |
| `payment.onramp.fiat_received` | `fiat_received` | `pending` | Your customer's money has arrived. |
| `payment.onramp.processing` | `processing` | `pending` | We're sending the stablecoin. |
| `payment.onramp.completed` | `completed` | `success` | The stablecoin has been sent to the wallet. **Final.** |
| `payment.onramp.failed` | `failed` | `failed` | The payment couldn't be finished. **Final.** |
| `payment.onramp.canceled` | `canceled` | `failed` | The payment was canceled. **Final.** |
| `payment.onramp.reversed` | `reversed` | `failed` | A finished payment was undone. **Final.** |
| `payment.onramp.flagged` | `flagged` | `pending` | The payment is on hold for a review. |
| `payment.onramp.paused` | `paused` | `pending` | The payment is on hold. |
| `payment.onramp.resumed` | (the state it continues from) | `pending` | A held payment carries on. |

## Each event in detail

> [accordion] payment.onramp.initiated
>
> **What it means:** The payment exists. You already have the deposit instructions from the create response.
>
> **What usually comes next:** `quote_locked`.
>
> **What to do:** Save the payment ID against your order.

> [accordion] payment.onramp.quote\_locked
>
> **What it means:** The quote is tied to this payment and can't be used again.
>
> **What usually comes next:** `fiat_pending`.
>
> **What to do:** Nothing.

> [accordion] payment.onramp.fiat\_pending
>
> **What it means:** We're waiting for your customer to pay. They have 30 minutes. For mobile money they also need to approve on their phone (and you may need to [send a code](https://docs.bridge.linkio.world/flows/mobile-money.md)).
>
> **What usually comes next:** `fiat_received`. It's `failed` if no money arrives within 30 minutes, or `flagged` if the wrong amount arrives.
>
> **What to do:** Show the deposit instructions and remind your customer to pay.

> [accordion] payment.onramp.fiat\_received
>
> **What it means:** Your customer's fiat has arrived.
>
> **What usually comes next:** `processing`.
>
> **What to do:** Tell your customer their payment was received.

> [accordion] payment.onramp.processing
>
> **What it means:** We're sending the stablecoin to the wallet.
>
> **What usually comes next:** `completed`. Sometimes `flagged` if something needs checking.
>
> **What to do:** Nothing.

> [accordion] payment.onramp.completed
>
> **What it means:** The stablecoin was sent. This is a success, and it's final.
>
> **What to do:** Show success. Call [Get a payment](https://docs.bridge.linkio.world/api-reference/payments/details.md) to get the `transaction_hash` your customer can look up on the blockchain.

> [accordion] payment.onramp.failed
>
> **What it means:** The payment ended without finishing. Common reasons: no money arrived within 30 minutes, or the mobile money request was declined. Final.
>
> **What to do:** Tell your customer. To try again, create a new quote and a new payment.

> [accordion] payment.onramp.canceled
>
> **What it means:** The payment was canceled before it finished. Final.
>
> **What to do:** Tell your customer.

> [accordion] payment.onramp.reversed
>
> **What it means:** A payment that had gone through was undone. Final.
>
> **What to do:** Contact support with the payment ID for details.

> [accordion] payment.onramp.flagged
>
> **What it means:** The payment is on hold for a review. For example, the amount received didn't match the amount expected.
>
> **What usually comes next:** After the review, `completed` or `failed`.
>
> **What to do:** Tell your customer the payment is being checked. Don't create a duplicate payment.

> [accordion] payment.onramp.paused
>
> **What it means:** The payment is on hold.
>
> **What usually comes next:** `resumed`.
>
> **What to do:** Wait.

> [accordion] payment.onramp.resumed
>
> **What it means:** A paused payment is moving again.
>
> **What to do:** Keep listening for the next event.

## Example payloads

> [tab] fiat\_received
>
> ```json theme={null}
> {
>   "id": "wbd_1wZ4cB6dE8fK2mQ9xLp3VnR7tY",
>   "event_id": "evt_4cB6dE8fK2mQ9xLp3VnR7tY1wZ",
>   "event_type": "payment.onramp.fiat_received",
>   "api_version": "2026-10-29-atlas",
>   "business_id": "bus_0190f2a1-7c3b-7d4e-9f10-2a3b4c5d6e7f",
>   "created_at": "2026-10-28T10:20:41.118Z",
>   "data": {
>     "payment_id": "pay_8fK2mQ9xLp3VnR7tY1wZ4cB6dE",
>     "reference_id": "ref_7tY1wZ4cB6dE8fK2mQ9xLp3VnR",
>     "type": "payment.onramp.fiat_received",
>     "party": "1st",
>     "state": "fiat_received",
>     "status": "pending",
>     "created_at": "2026-10-28T10:15:02.000Z",
>     "updated_at": "2026-10-28T10:20:40.000Z"
>   }
> }
> ```

> [tab] completed
>
> ```json theme={null}
> {
>   "id": "wbd_6dE8fK2mQ9xLp3VnR7tY1wZ4cB",
>   "event_id": "evt_2cB6dE8fK2mQ9xLp3VnR7tY1wZ",
>   "event_type": "payment.onramp.completed",
>   "api_version": "2026-10-29-atlas",
>   "business_id": "bus_0190f2a1-7c3b-7d4e-9f10-2a3b4c5d6e7f",
>   "created_at": "2026-10-28T10:21:17.412Z",
>   "data": {
>     "payment_id": "pay_8fK2mQ9xLp3VnR7tY1wZ4cB6dE",
>     "reference_id": "ref_7tY1wZ4cB6dE8fK2mQ9xLp3VnR",
>     "type": "payment.onramp.completed",
>     "party": "1st",
>     "state": "completed",
>     "status": "success",
>     "created_at": "2026-10-28T10:15:02.000Z",
>     "updated_at": "2026-10-28T10:21:17.000Z"
>   }
> }
> ```

> [tab] failed
>
> ```json theme={null}
> {
>   "id": "wbd_9xLp3VnR7tY1wZ4cB6dE8fK2mQ",
>   "event_id": "evt_8fK2mQ9xLp3VnR7tY1wZ4cB6dE",
>   "event_type": "payment.onramp.failed",
>   "api_version": "2026-10-29-atlas",
>   "business_id": "bus_0190f2a1-7c3b-7d4e-9f10-2a3b4c5d6e7f",
>   "created_at": "2026-10-28T10:45:05.901Z",
>   "data": {
>     "payment_id": "pay_8fK2mQ9xLp3VnR7tY1wZ4cB6dE",
>     "reference_id": "ref_7tY1wZ4cB6dE8fK2mQ9xLp3VnR",
>     "type": "payment.onramp.failed",
>     "party": "1st",
>     "state": "failed",
>     "status": "failed",
>     "created_at": "2026-10-28T10:15:02.000Z",
>     "updated_at": "2026-10-28T10:45:05.000Z"
>   }
> }
> ```

Every onramp event has this same shape. Only `event_type`, `data.type`, `data.state`, and `data.status` change.


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