Skip to main content
An on-ramp order takes fiat from the user’s card or alternative payment method (APM) and sends the resulting crypto to a crypto address. The Payment Widget lets the user pick the payment method to pay with via the on-ramp:select-deposit-origin flow, and the crypto address to receive the crypto via the on-ramp:select-withdrawal-destination flow. After the user confirms the quote, the widget creates the order and authorizes its deposit, handling any 3DS challenge or APM authorization, via the order:authorize-deposit flow. Your app builds the amount entry and review screens, and your backend creates the quote.
You can mix the widget with the REST API: for example, collect the crypto address yourself and only use the widget to select the payment method and authorize the deposit. Each flow only needs what the previous step returns. To compare all flows, see Flows.

Prerequisites

  • The user has been created. Full onboarding isn’t required: what the user must verify depends on their verification tier, which is set by their total ramp volume.
  • The user has the on-ramp capability enabled. Call Get user capability to check it. If it lists requirements, have the user complete those KYC processes first, through the KYC endpoints or the KYC Widget.
  • Your client has the on-off-ramp.orders.quotes:create, on-off-ramp.orders:create and on-off-ramp.orders:read scopes.
  • The Payment Widget is set up in your frontend. See Installation and setup.

Walkthrough


Select the origin

The on-ramp:select-deposit-origin flow lets the user link a new card or pick an existing one, or pick an APM, such as Apple Pay or PayPal. It only shows the methods that are available for on-ramp orders and that the user can use. It performs selection only: it does not create the quote or the order.

Create a widget session

Call Create widget session to start the on-ramp:select-deposit-origin flow. To customize the theme and layout, see Create a session.
To offer only some of the methods, set paymentMethods in the options, such as [{ "type": "card" }]. Methods that cannot be used as the origin of an on-ramp order, such as bank or crypto, are ignored. The response contains a session object with a url field that loads the widget. Return response.session to your frontend as is.

Set up the widget

Both examples above are for web applications — either creating the iframe yourself or letting the SDK do it. For native apps using a WebView, see Native apps with the Web SDK for the SDK’s native-bundling pattern, or Setup without the SDK for the no-SDK approach that loads the session url directly as the WebView’s top-level page.

Handle the complete event

The complete event fires after the user selects a payment method. Map the selection to the origin of the quote:

Handle cancellations and errors

The cancel event fires when the user closes the widget without selecting a method: unmount the widget and return the user to the previous screen. The error event fires for critical unrecoverable errors: unmount the widget and show a user-friendly error message. Card-specific errors, such as a duplicate card, a country mismatch or card limits, are handled by the widget internally.
The Payment Widget handles most errors internally. For unrecoverable errors, the widget fires an error event. It is the host application’s responsibility to handle these events, present an error message to the user, and unmount the widget.

Select the destination

The on-ramp:select-withdrawal-destination flow lets the user pick the crypto asset and network to buy, and enter the address to receive it, along with a reference (such as a memo or destination tag) for networks that require one. The widget only offers the assets and networks available for on-ramp orders, and validates the address before returning it. If you already know the crypto address, for example because your app provides its own wallet, skip this step and use it as the destination of the quote.

Create a widget session

Call Create widget session to start the on-ramp:select-withdrawal-destination flow.
To restrict the assets, set paymentMethods to [{ "type": "crypto", "assets": { "include": ["BTC", "XRP"] } }] in the options. Set up the widget as in Set up the widget, using PaymentWidget<'on-ramp:select-withdrawal-destination'>, and handle cancel and error the same way.

Handle the complete event

The complete event fires after the user confirms the address, with via: 'crypto-network'. Use the selection as a crypto-address destination of the quote.

Create a quote

Show the user a preview of the order before creating it. Call Create quote with the origin and destination from the widget, and the denomination the user chose.
Present origin.amount, destination.amount and the fees to the user. A locked quote holds its rate until expiresAt.
Quotes are short-lived. Use refreshAt to drive re-quoting: if the user hasn’t confirmed by then, create a new quote and show the updated amounts, since there’s no refresh endpoint. The quote’s expiresAt is equal to or later than refreshAt, to give the user time to complete an external action needed to proceed, such as authorizing an APM payment.

Resolve requirements

Check the requirements of the quote. Each requirement has a quoteId, which differs from the quote id: it identifies the leg of the order the requirement applies to.
  • The authorize:* requirements, such as authorize:3ds for a card or authorize:apple-pay, are resolved by the widget in the order:authorize-deposit flow. Pass them to the session as they are, as described in Create an authorize session.
  • travel-rule must be resolved before creating the authorize session, as described in Travel rule.
See Requirements for the full list.

Travel rule

When the quote lists the travel-rule requirement, the order cannot be created until the related request for information (RFI) is resolved. Use the quoteId of the requirement to resolve it, either:
  • Through the widget: call Create session of the Travel Rule Widget to start the withdrawal-form flow, passing the quoteId of the requirement as data.quoteId. The widget collects the data from the user and resolves the RFI.
  • Through the API: call List requests for information with the quoteId as reference to find the RFI, and resolve it with Update request for information.
Create the order once the RFI has the status ok. Creating it before then fails with a 409 operation_not_allowed error, with the reason pending-requests-for-information. Check out the travel rule withdrawal guides via widget and via API for a detailed walkthrough.

Authorize the deposit and create the order

After the user confirms the quote, hand off to the order:authorize-deposit flow. It creates the order from the quote, handles the 3DS challenge of a card or the authorization of an APM, and polls the order until the outcome of the deposit is known.

Create an authorize session

Call Create widget session to start the order:authorize-deposit flow, with:
  • data.quoteId — the id of the on-ramp quote.
  • data.requirements — the authorize:* requirements of the quote, as returned, with their name and quoteId. Include authorize:3ds for a card origin: without it, the widget does not send a returnUrl and cannot complete a 3DS challenge.
  • data.domain — for Apple Pay in web apps, the top-page domain, which must be registered with Apple Pay. See Apple Pay.
The response contains a session object with a url field that loads the widget. Return response.session to your frontend as is. For Apple Pay and Google Pay, you can set authorize.mode to headless in the options to render only the payment button inside your own layout, as in the transaction flows. See AuthorizeFlowOptions.

Set up the widget

Set up the widget as in Set up the widget, using PaymentWidget<'order:authorize-deposit'>. Without the SDK, keep payment 'src' in the iframe allow attribute: Apple Pay and Google Pay need it. What the user sees depends on the origin of the quote:
  • Card: the widget creates the order and, if the issuer requires it, redirects the user to the 3DS challenge and back.
  • PayPal and Venmo: the user signs in and authorizes the payment, unless the account is already authorized, before the widget creates the order.
  • Apple Pay and Google Pay: the user confirms the payment in the native sheet before the widget creates the order. There is no stored authorization, so the user confirms every order.

Handle the complete event

The complete event fires with the order and the trigger that ended the flow. The widget waits for the outcome of the deposit, not for the order to be completed: the crypto is sent afterwards, so the order is usually still processing when the event fires.
The complete event does not guarantee success. Always check order.status, order.timeline and trigger.reason, and keep monitoring the order until it reaches a final status.
The value of the event is the order plus what triggered the completion. The order is the full Order, as Get order returns it.

Handle cancellations

The cancel event fires when the user navigates back without authorizing the payment. No order is created: unmount the widget and return the user to the review screen.

Handle errors

The error event fires for critical unrecoverable errors. Failures to create the order, and failures of the Apple Pay or Google Pay sheet, use code: 'authorize_order_failed', with the reason in event.detail.error.details.reason: Other failures in this flow surface with their own code and are not retryable; handle those with a generic fallback. As with any Widget error, the original failure is preserved in event.detail.error.cause. When details.reason is unable-to-create-order, event.detail.error.cause.code is the error of Create order, such as:
In headless mode, authorize_order_failed is retryable for Apple Pay and Google Pay: keep the widget mounted if you want the user to try again.
The Payment Widget handles most errors internally. For unrecoverable errors, the widget fires an error event. It is the host application’s responsibility to handle these events, present an error message to the user, and unmount the widget.

Monitor the order

The widget stops once the outcome of the deposit is known. Follow the order until it reaches a final status: completed, failed or expired. Subscribe to the Order status changed and Order timeline updated webhooks, and call Get order as a fallback when webhook delivery cannot be guaranteed. Use the order.id from the complete event. See Monitor the order and Handle failures in the REST API guide for the timeline events, refund outcomes and failure reasons to handle.

Notify the user

Display an in-app confirmation when the order is completed, and send an email if applicable.

Handle on-hold orders

An order is on-hold when a leg is under review. The deposit-on-hold or withdrawal-on-hold event of the timeline carries the reason. No action is needed on your side: the order goes back to processing once released, which you can follow with the Order status changed webhook.
You now support on-ramp orders via the Payment Widget.