Onramp events

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

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.

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.

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

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.

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.

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 to get the transaction_hash your customer can look up on the blockchain.

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.

payment.onramp.canceled

What it means: The payment was canceled before it finished. Final.What to do: Tell your customer.

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.

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.

payment.onramp.paused

What it means: The payment is on hold.What usually comes next: resumed.What to do: Wait.

payment.onramp.resumed

What it means: A paused payment is moving again.What to do: Keep listening for the next event.

Example payloads

fiat_received
completed
failed

{
  "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"
  }
}

{
  "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"
  }
}

{
  "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.

Get started

Set up your account

Before you build

Core flows

Webhooks

Errors

Summary

Each event in detail

Example payloads

​Summary

​Each event in detail

​Example payloads

Summary

Each event in detail

Example payloads