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.
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-rampcapability enabled. Call Get user capability to check it. If it listsrequirements, 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:createandon-off-ramp.orders:readscopes. - The Payment Widget is set up in your frontend. See Installation and setup.
Walkthrough
Select the origin
Theon-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 theon-ramp:select-deposit-origin flow. To customize the theme and layout, see Create a session.
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
Thecomplete event fires after the user selects a payment method. Map the selection to the origin of the quote:
Handle cancellations and errors
Thecancel 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.
Select the destination
Theon-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 theon-ramp:select-withdrawal-destination flow.
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
Thecomplete 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 theorigin and destination from the widget, and the denomination the user chose.
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 therequirements 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 asauthorize:3dsfor a card orauthorize:apple-pay, are resolved by the widget in theorder:authorize-depositflow. Pass them to the session as they are, as described in Create an authorize session. travel-rulemust be resolved before creating the authorize session, as described in Travel rule.
Travel rule
When the quote lists thetravel-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-formflow, passing thequoteIdof the requirement asdata.quoteId. The widget collects the data from the user and resolves the RFI. - Through the API: call List requests for information with the
quoteIdasreferenceto find the RFI, and resolve it with Update request for information.
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 theorder: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 theorder:authorize-deposit flow, with:
data.quoteId— theidof the on-ramp quote.data.requirements— theauthorize:*requirements of the quote, as returned, with theirnameandquoteId. Includeauthorize:3dsfor a card origin: without it, the widget does not send areturnUrland 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.
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, usingPaymentWidget<'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
Thecomplete 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.
order is the full Order, as Get order returns it.
Handle cancellations
Thecancel 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
Theerror 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:
authorize_order_failed is retryable for Apple Pay and Google Pay: keep the widget mounted if you want the user to try again.
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 iscompleted, and send an email if applicable.
Handle on-hold orders
An order ison-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.