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-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, pluson-off-ramp.orders.metadata:writeif 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 withrampType=on-ramp and type=card to verify that a card rail with the deposit feature is available for on-ramp orders.
Link or select the card
Let the user link a new card or select an existing one. The card external account is theorigin of the quote.
Call List external accounts to fetch the user’s saved cards.
status: "ok" and deposit in features.
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.
status: "processing" while the card is validated.
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.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 withrampType=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
apmnode with themethodthe user pays with, such aspaypal. No external account is needed. - A saved APM account, referenced by the
idof its external account, withvia: apm.
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,networkandaddressto send to, and areference(such as a memo or destination tag) for networks that require one. - A crypto external account, referenced by its
id.
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.
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 thetype, 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.
{ "type": "apm", "method": "apple-pay" }.
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 therequirements 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:3dsis resolved when creating the order, as described in Pay with a card.- The
authorize:*requirements of APMs, such asauthorize:paypal, are handled by the Payment Widget, which authorizes the payment and creates the order, as described in Pay with an APM. travel-rulemust be resolved before creating the order, 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.
Create the order
Once the user confirms, call Create order with thequoteId. Optionally, attach your own metadata to the order.
Pay with a card
The quote of a card origin lists theauthorize: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.
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 asauthorize: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:- Order status changed, when the
statusof the order changes. - Order timeline updated, when an event is added to the
timeline, such asdeposit-completedorwithdrawal-sent.
Via polling
Call Get order as a fallback, when webhook delivery cannot be guaranteed.Notify the user
Display an in-app confirmation when the order iscompleted, 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 becomesfailed 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 itserror 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: itsstatus 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 becomesfailed 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 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.