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 or a saved crypto external account. This guide covers creating on-ramp orders paid through a pull deposit, using the REST API. With a card origin, your backend creates the quote and the order. With an APM origin, the REST API is used together with the Payment Widget: the order runs through the widget’s order:authorize-deposit flow, where the user authorizes the payment, and your backend only creates the quote and the Payment Widget session.
In a pull deposit, Uphold collects the payment from the user’s card or APM when the order is created. On-ramp orders paid through a push deposit, such as a bank transfer, will be supported in the future. See On-ramp with a push deposit.

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, plus on-off-ramp.orders.metadata:write if you attach metadata to the order.
  • For an APM origin, the Payment Widget is set up in your frontend.

Walkthrough


Define the origin

The origin is the payment method the user pays with.

Card

Check available rails

Call List rails with rampType=on-ramp and type=card to verify that a card rail with the deposit feature is available for on-ramp orders.
Let the user link a new card or select an existing one. The card external account is the origin of the quote. Call List external accounts to fetch the user’s saved cards.
Make sure the selected card has status: "ok" and deposit in features.
If the user wants to use a card not yet on file, call Create external account with the card details.
This sends the full card number and security code through your systems, which requires your organization to be PCI DSS compliant. If it isn’t, link cards through the Payment Widget, which collects the card details itself, with its flow.
The response initially returns status: "processing" while the card is validated.
Once validated, the status transitions to ok and the full details are available.
Monitor the external account status via Get external account or the core.external-account.status-changed webhook until status is ok before proceeding.
If the card can’t be linked, Create external account returns an HTTP error. These are the errors to act on, such as by showing the user a message:

EMD disclaimer

This disclaimer is required to comply with FCA regulations. Display it to users based in GB, the first time they link a credit/debit card or generate bank deposit details — it only needs to be shown once:
Uphold Europe Limited is an EMD Agent of Optimus Cards UK Limited (FRN: 902034). All received funds are held in a designated safekeeping account with a regulated bank and kept separate from Uphold’s own assets. These funds are not protected by the UK Financial Services Compensation Scheme.

Alternative payment method (APM)

Check available rails

Call List rails with rampType=on-ramp and type=apm to find the APMs the user can pay with: those whose features include deposit.

Define the APM origin

The origin is either:
  • An apm node with the method the user pays with, such as paypal. No external account is needed.
  • A saved APM account, referenced by the id of its external account, with via: apm.
The payment is authorized through the Payment Widget’s order:authorize-deposit flow, which creates the order. See Pay with an APM.

Define the destination

The destination is where the crypto is sent, and it is either:
  • A crypto address, with the asset, network and address to send to, and a reference (such as a memo or destination tag) for networks that require one.
  • A crypto external account, referenced by its id.
Call List rails with rampType=on-ramp and type=crypto and keep the rails whose features include withdraw, so you only offer assets and networks that an on-ramp order can deliver to.
Call List networks to find the networks available for the chosen asset. For a crypto address, call Validate network address before creating the quote, so an invalid address or reference is caught before the order is placed.

Create a quote

Show the user a preview of the order before creating it. Call Create quote with the type, origin, destination and denomination of the order. The denomination sets the asset and amount of the order. With target: origin (the default), the user pays exactly that amount. With target: destination, the destination receives exactly that amount.
To pay with an APM, set the origin to { "type": "apm", "method": "apple-pay" }.
Present origin.amount, destination.amount and the fees to the user.
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: they tell you what you must provide before or when creating the order. An empty array means nothing else is needed. Each requirement has a quoteId, which differs from the quote id: it identifies the leg of the order the requirement applies to.
  • authorize:3ds is resolved when creating the order, as described in Pay with a card.
  • The authorize:* requirements of APMs, such as authorize:paypal, are handled by the Payment Widget, which authorizes the payment and creates the order, as described in Pay with an APM.
  • travel-rule must be resolved before creating the order, 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.

Create the order

Once the user confirms, call Create order with the quoteId. Optionally, attach your own metadata to the order.

Pay with a card

The quote of a card origin lists the authorize:3ds requirement: provide it in params.requirements, always with a returnUrl, since the card issuer may require a 3DS challenge. You may embed state in the returnUrl query parameters to resume the flow after the redirect. Include the user context headers X-Uphold-User-Ip and X-Uphold-User-Agent. They are required with authorize:3ds: leaving them out fails with a 409 operation_not_allowed error, with the reason missing-user-ip-header or missing-user-agent-header.
If origin.node.confirmationUrl is present, redirect the user to it to complete the 3DS challenge. After completion, the issuer redirects the user back to your returnUrl. Alternatively, the Payment Widget’s order:authorize-deposit flow can create the order and handle the 3DS challenge for you, as with an APM.

Pay with an APM

An APM requirement, such as authorize:paypal, needs the provider and deviceData of the authorization, plus the tokenizedPayment for some methods, such as Apple Pay and Google Pay. The Payment Widget collects them from the payment provider’s SDK, so you don’t handle them yourself. Don’t create the order yourself. Hand off to the Payment Widget: call Create widget session to start the order:authorize-deposit flow, passing the quoteId, and the widget authorizes the payment and creates the order. See Authorize the deposit and create the order in the On-ramp via Widget guide for a walkthrough. With Google Pay, the payment may also need a 3DS challenge. When it does, the widget presents the challenge to the user, so you don’t need to handle it, but these orders can take longer to complete.

Monitor the order

Follow the order until it reaches a final status: completed, failed or expired.

Via webhooks

Subscribe to the order webhooks, which are sent on every change of the order:

Via polling

Call Get order as a fallback, when webhook delivery cannot be guaranteed.
Prefer webhooks over polling in production. See Webhooks for setup instructions.

Notify the user

Display an in-app confirmation when the order is completed, and send an email if applicable.
You now support on-ramp orders via the REST API.

Handle failures

A request to create a quote or an order can be rejected, in which case no order is created. See Request errors. An order that was created becomes failed when it cannot be completed. Read its timeline to tell which leg failed:

Request errors

Create quote and Create order reject a request with an HTTP error when it can’t go ahead, in which case no order is created. The table only lists the errors your integration should act on, such as by showing the user a message. The other errors usually point to an issue in your integration. See the API reference of each endpoint for the full list. For an APM, the Payment Widget creates the order, so the errors of Create order reach you through its error event instead, with the original error in event.detail.error.cause: the status in httpStatusCode, and the same code and details as in the table. The errors of Create quote are returned to your backend as usual.

Failure reasons

An order that was created can still fail afterwards: its status becomes failed, and the reason of the matching timeline event says why. You learn about it through the order webhooks, or by polling Get order. The table only lists the reasons your integration should act on, such as by notifying the user.

Refund outcome

When the withdrawal fails, Uphold usually refunds the deposit, and the order becomes failed once the refund is done. Read the last refund-* event of the timeline: See Refunds for what each outcome means.

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.