> ## Documentation Index
> Fetch the complete documentation index at: https://developer.uphold.com/llms.txt
> Use this file to discover all available pages before exploring further.

# On-ramp via the Payment Widget

> Let users buy crypto with a card or an alternative payment method in a single on-ramp order, using the Uphold Payment Widget to select the payment methods and authorize the deposit.

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.

> [!NOTE]
>
> You can mix the widget with the [REST API](https://developer.uphold.com/developer-guides/on-off-ramp/on-ramp/via-rest-api/pull-deposit.md): 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](https://developer.uphold.com/widgets/payment/flows.md).

## Prerequisites

* The user has been [created](https://developer.uphold.com/rest-apis/core-api/users/create-user.md). Full onboarding isn't required: what the user must verify depends on their [verification tier](https://developer.uphold.com/rest-apis/on-off-ramp-api/introduction.md#capabilities-and-verification-tiers), which is set by their total ramp volume.
* The user has the `on-ramp` capability enabled. Call [Get user capability](https://developer.uphold.com/rest-apis/core-api/capabilities/get-user-capability.md) to check it. If it lists `requirements`, have the user complete those KYC processes first, through the [KYC endpoints](https://developer.uphold.com/rest-apis/core-api/kyc/overview.md) or the [KYC Widget](https://developer.uphold.com/widgets/kyc/introduction.md).
* 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](https://developer.uphold.com/widgets/payment/installation-and-setup.md).

## Walkthrough

```mermaid theme={null}
sequenceDiagram
  autonumber
  participant Usr as User
  participant U as Your App
  participant B as Your Backend
  participant P as Payment Widget
  participant A as Uphold

  Usr->>U: Start on-ramp
  U->>B: Create widget session
  B->>A: Create widget session (on-ramp:select-deposit-origin)
  A-->>B: { session }
  B-->>U: { session }
  U->>P: Initialize widget
  Usr->>P: Select card or APM
  P-->>U: complete { via, selection }
  U->>B: Create widget session
  B->>A: Create widget session (on-ramp:select-withdrawal-destination)
  A-->>B: { session }
  B-->>U: { session }
  U->>P: Initialize widget
  Usr->>P: Select asset and network, enter address
  P-->>U: complete { via, selection }
  Usr->>U: Choose amount
  U->>B: Create quote
  B->>A: POST /on-off-ramp/orders/quote
  A-->>B: { quote }
  B-->>U: { quote }
  U->>Usr: Show amounts, rates and fees
  Usr->>U: Confirm
  alt Quote has travel-rule requirement
    U->>Usr: Collect travel rule data
    Note over U,A: Resolve the RFI, then continue
  end
  U->>B: Create widget session
  B->>A: Create widget session (order:authorize-deposit)
  A-->>B: { session }
  B-->>U: { session }
  U->>P: Initialize widget
  opt APM origin
    Usr->>P: Authorize the payment
  end
  P->>A: Create order
  A-->>P: { order (with confirmationUrl if 3DS is required) }
  opt confirmationUrl present
    Usr->>P: Complete the 3DS challenge
  end
  P-->>U: complete { order, trigger }
  A-->>B: Webhooks (status changed, timeline updated)
  B-->>Usr: Notify the user
```

***

## 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](https://developer.uphold.com/rest-apis/widgets-api/payment/create-session.md) to start the `on-ramp:select-deposit-origin` flow. To customize the theme and layout, see [Create a session](https://developer.uphold.com/widgets/payment/installation-and-setup.md#1-create-a-session-on-your-backend).

```http theme={null}
POST /widgets/payment/sessions
{
  "flow": "on-ramp:select-deposit-origin"
}
```

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.

```jsonc theme={null}
{
  "session": {
    "url": "https://payment-widget.enterprise.uphold.com/?sessionToken=..."
    // ...
  }
}
```

### Set up the widget

```typescript Web SDK [expandable] theme={null}
import { PaymentWidget } from '@uphold/enterprise-payment-widget-web-sdk';

// session is `response.session` from your backend
const initializeWidget = async (session) => {
  const widget = new PaymentWidget<'on-ramp:select-deposit-origin'>(session, { debug: true });

  widget.on('complete', (event) => {
    console.log('Complete', JSON.stringify(event.detail.value));
    widget.unmount();
  });

  widget.on('cancel', () => {
    console.log('Cancelled');
    widget.unmount();
  });

  widget.on('error', (event) => {
    console.error('Error', event.detail.error);
    widget.unmount();
  });

  widget.mountIframe(document.getElementById('payment-container'));
};
```

```html Without SDK [expandable] theme={null}
<div id="payment-container"></div>

<script>
  // session is `response.session` from your backend
  async function initializeWidget(session) {
    const container = document.getElementById('payment-container');
    const sessionOrigin = new URL(session.url).origin;

    const iframe = document.createElement('iframe');
    iframe.src = session.url;
    iframe.setAttribute('allow', "clipboard-write 'src'; clipboard-read 'src'; payment 'src';");
    iframe.style.width = '100%';
    iframe.style.height = '100%';
    iframe.style.border = 'none';

    function teardown() {
      window.removeEventListener('message', onMessage);
      iframe.remove();
    }

    function onMessage(event) {
      if (event.origin !== sessionOrigin) return;

      switch (event.data?.type) {
        case 'load':
          // Optional: repeat theme or layout from Create session to avoid a brief flash of defaults
          iframe.contentWindow.postMessage({ options: {}, type: 'init' }, sessionOrigin);
          break;
        case 'ready':
          break;
        case 'complete':
          console.log('Complete', JSON.stringify(event.data.value));
          teardown();
          break;
        case 'cancel':
          console.log('Cancelled');
          teardown();
          break;
        case 'error':
          console.error('Error', event.data.error);
          teardown();
          break;
      }
    }

    window.addEventListener('message', onMessage);
    container.appendChild(iframe);
  }
</script>
```

> [!NOTE]
>
> 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](https://developer.uphold.com/widgets/payment/installation-and-setup.md#native-apps-with-the-web-sdk) for the SDK's native-bundling pattern, or [Setup without the SDK](https://developer.uphold.com/widgets/payment/installation-and-setup.md#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:

| `via` | `selection` | Quote `origin` |
| - | - | - |
| `external-account` | The selected card external account | `{ "type": "external-account", "id": selection.id }` |
| `apm` | The selected `method`, and the `externalAccount` of the APM if the user already authorized one | `{ "type": "external-account", "id": selection.externalAccount.id }` when the `externalAccount` is present, otherwise `{ "type": "apm", "method": selection.method }` |

```javascript Web SDK theme={null}
widget.on('complete', (event) => {
  const { via, selection } = event.detail.value;

  if (via === 'external-account') {
    // The user selected a card
    setOrigin({ type: 'external-account', id: selection.id });
  } else if (via === 'apm') {
    // The user selected an APM, such as Apple Pay or PayPal
    if (selection.externalAccount) {
      // The user already authorized this APM, so reuse the saved account
      setOrigin({ type: 'external-account', id: selection.externalAccount.id });
    } else {
      setOrigin({ type: 'apm', method: selection.method });
    }
  }

  widget.unmount();
});
```

```javascript Without SDK theme={null}
// Inside the onMessage switch from Set up the widget
case 'complete': {
  const { via, selection } = event.data.value;

  if (via === 'external-account') {
    // The user selected a card
    setOrigin({ type: 'external-account', id: selection.id });
  } else if (via === 'apm') {
    // The user selected an APM, such as Apple Pay or PayPal
    if (selection.externalAccount) {
      // The user already authorized this APM, so reuse the saved account
      setOrigin({ type: 'external-account', id: selection.externalAccount.id });
    } else {
      setOrigin({ type: 'apm', method: selection.method });
    }
  }

  teardown();
  break;
}
```

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

> [!WARNING]
>
> 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](https://developer.uphold.com/rest-apis/widgets-api/payment/create-session.md) to start the `on-ramp:select-withdrawal-destination` flow.

```http theme={null}
POST /widgets/payment/sessions
{
  "flow": "on-ramp:select-withdrawal-destination"
}
```

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](#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.

```javascript Web SDK theme={null}
widget.on('complete', (event) => {
  const { via, selection } = event.detail.value;

  if (via === 'crypto-network') {
    const { asset, network, address, reference } = selection;

    setDestination({ type: 'crypto-address', asset, network, address, reference });
  }

  widget.unmount();
});
```

```javascript Without SDK theme={null}
// Inside the onMessage switch from Set up the widget
case 'complete': {
  const { via, selection } = event.data.value;

  if (via === 'crypto-network') {
    const { asset, network, address, reference } = selection;

    setDestination({ type: 'crypto-address', asset, network, address, reference });
  }

  teardown();
  break;
}
```

***

## Create a quote

Show the user a preview of the order before creating it. Call [Create quote](https://developer.uphold.com/rest-apis/on-off-ramp-api/orders/create-quote.md) with the `origin` and `destination` from the widget, and the `denomination` the user chose.

```http theme={null}
POST /on-off-ramp/orders/quote
{
  "type": "on-ramp",
  "origin": {
    "type": "apm",
    "method": "apple-pay"
  },
  "destination": {
    "type": "crypto-address",
    "asset": "XRP",
    "network": "xrp-ledger",
    "address": "rfBtmHiLwwWH5maH2PT78GxubrSydRF9aY",
    "reference": "67809592"
  },
  "denomination": {
    "asset": "USD",
    "amount": "100.00",
    "target": "origin"
  }
}
```

```json [expandable] theme={null}
{
  "quote": {
    "id": "623000c8-9bdf-4a2b-aa3d-6a6b44a7f6a0",
    "type": "on-ramp",
    "pricing": "locked",
    "origin": {
      "asset": "USD",
      "amount": "100.00",
      "rate": "2.07021435361804542440",
      "node": {
        "type": "apm",
        "method": "apple-pay"
      }
    },
    "destination": {
      "asset": "XRP",
      "amount": "46.125658",
      "rate": "0.48304176727029881912",
      "node": {
        "type": "crypto-address",
        "network": "xrp-ledger",
        "address": "rfBtmHiLwwWH5maH2PT78GxubrSydRF9aY",
        "reference": "67809592"
      }
    },
    "denomination": {
      "asset": "USD",
      "amount": "100.00",
      "rate": "1.00000000000000000000",
      "target": "origin"
    },
    "fees": [
      {
        "type": "deposit",
        "code": "on-ramp-deposit",
        "asset": "USD",
        "amount": "1.00",
        "percentage": "1",
        "beneficiary": "uphold"
      },
      {
        "type": "network",
        "code": "crypto-network",
        "asset": "USD",
        "amount": "3.51"
      }
    ],
    "requirements": [
      {
        "name": "authorize:apple-pay",
        "quoteId": "b0a0e8d4-3c4e-4f3a-9d1e-6f5b2c7a8e91"
      }
    ],
    "refreshAt": "2024-07-24T15:22:39.000Z",
    "expiresAt": "2024-07-24T15:37:39.000Z"
  }
}
```

Present `origin.amount`, `destination.amount` and the `fees` to the user. A `locked` quote holds its rate until `expiresAt`.

> [!NOTE]
>
> 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](#create-an-authorize-session).
* `travel-rule` must be resolved before creating the authorize session, as described in [Travel rule](#travel-rule).

See [Requirements](https://developer.uphold.com/rest-apis/on-off-ramp-api/orders/overview.md#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](https://developer.uphold.com/rest-apis/widgets-api/travel-rule/create-session.md) 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](https://developer.uphold.com/rest-apis/core-api/requests-for-information/list-requests-for-information.md) with the `quoteId` as `reference` to find the RFI, and resolve it with [Update request for information](https://developer.uphold.com/rest-apis/core-api/requests-for-information/update-request-for-information.md).

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](https://developer.uphold.com/developer-guides/travel-rule/withdrawal/via-widget.md) and [via API](https://developer.uphold.com/developer-guides/travel-rule/withdrawal/via-api.md) 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](https://developer.uphold.com/rest-apis/widgets-api/payment/create-session.md) 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](https://developer.uphold.com/developer-guides/apm-transfers/introduction.md#apple-pay).

```http theme={null}
POST /widgets/payment/sessions
{
  "flow": "order:authorize-deposit",
  "data": {
    "quoteId": "623000c8-9bdf-4a2b-aa3d-6a6b44a7f6a0",
    "requirements": [
      {
        "name": "authorize:apple-pay",
        "quoteId": "b0a0e8d4-3c4e-4f3a-9d1e-6f5b2c7a8e91"
      }
    ],
    "domain": "<top-page-domain>" // For Apple Pay in web apps only
  }
}
```

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](https://developer.uphold.com/widgets/payment/sdk-reference.md#authorizeflowoptions).

### Set up the widget

Set up the widget as in [Set up the widget](#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.

> [!WARNING]
>
> 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.

| `trigger.reason` | Meaning |
| - | - |
| `deposit-status-changed` | The outcome of the deposit is known: the `timeline` has a `deposit-completed`, `deposit-failed` or `deposit-on-hold` event, or the order is already `failed`, `expired` or `on-hold`. |
| `max-retries-reached` | The widget stopped polling before the outcome was known. Continue monitoring the order via webhooks or polling. |

```javascript Web SDK theme={null}
widget.on('complete', (event) => {
  const { order, trigger } = event.detail.value;
  const events = order.timeline.map(({ event }) => event);

  if (trigger.reason === 'deposit-status-changed') {
    if (order.status === 'failed' || order.status === 'expired' || events.includes('deposit-failed')) {
      // The order failed or expired — read the reason from the timeline, and let the user try again with a new quote
    } else if (order.status === 'on-hold') {
      // The order is under review — see Handle on-hold orders
    } else if (events.includes('deposit-completed')) {
      // The payment was taken — the crypto is on its way, follow the order until it is completed
    }
  } else if (trigger.reason === 'max-retries-reached') {
    // Widget stopped polling — continue monitoring via webhooks or polling
  }

  widget.unmount();
});
```

```javascript Without SDK theme={null}
// Inside the onMessage switch from Set up the widget
case 'complete': {
  const { order, trigger } = event.data.value;
  const events = order.timeline.map(({ event }) => event);

  if (trigger.reason === 'deposit-status-changed') {
    if (order.status === 'failed' || order.status === 'expired' || events.includes('deposit-failed')) {
      // The order failed or expired — read the reason from the timeline, and let the user try again with a new quote
    } else if (order.status === 'on-hold') {
      // The order is under review — see Handle on-hold orders
    } else if (events.includes('deposit-completed')) {
      // The payment was taken — the crypto is on its way, follow the order until it is completed
    }
  } else if (trigger.reason === 'max-retries-reached') {
    // Widget stopped polling — continue monitoring via webhooks or polling
  }

  teardown();
  break;
}
```

The value of the event is the order plus what triggered the completion. The `order` is the full [Order](https://developer.uphold.com/rest-apis/on-off-ramp-api/orders/overview.md), as [Get order](https://developer.uphold.com/rest-apis/on-off-ramp-api/orders/get-order.md) 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`:

| Reason | Description |
| - | - |
| `unable-to-create-order` | The payment was authorized, but the order could not be created — see `event.detail.error.cause` below for the underlying reason |
| `unable-to-create-payment-request` | The browser could not build the Apple Pay or Google Pay payment request |
| `unable-to-make-payment` | The device or browser reported it cannot make this payment |
| `unable-to-create-merchant-session` | Merchant session validation with Apple failed, typically because the `domain` is not registered |
| `unable-to-show-payment-request` | The Apple Pay or Google Pay sheet could not be shown |
| `invalid-payment-response` | The Apple Pay or Google Pay sheet returned a response without the expected payment token |

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`](https://developer.uphold.com/widgets/payment/sdk-reference#error). When `details.reason` is `unable-to-create-order`, `event.detail.error.cause.code` is the error of [Create order](https://developer.uphold.com/rest-apis/on-off-ramp-api/orders/create-order.md), such as:

| Code | Description |
| - | - |
| `entity_not_found` | The quote was not found, has expired or was already used |
| `operation_not_allowed` | The order is not allowed, such as a quote with a pending `travel-rule` requirement. See [Request errors](https://developer.uphold.com/developer-guides/on-off-ramp/on-ramp/via-rest-api/pull-deposit.md#request-errors) for the reasons |
| `user_capability_failure` | The user lacks the `on-ramp` capability |

```javascript Web SDK theme={null}
widget.on('error', (event) => {
  const { code, cause, details } = event.detail.error;
  console.error('Widget error:', code, details, cause);

  if (code === 'authorize_order_failed' && details?.reason === 'unable-to-create-order') {
    // The real reason is nested here, not in the top-level `code`
    console.error('Create order failed:', cause?.code);
  }

  widget.unmount();
  // Show a user-friendly error message, and create a new quote if the user tries again
});
```

```javascript Without SDK theme={null}
// Inside the onMessage switch from Set up the widget
case 'error': {
  const { code, cause, details } = event.data.error;
  console.error('Widget error:', code, details, cause);

  if (code === 'authorize_order_failed' && details?.reason === 'unable-to-create-order') {
    console.error('Create order failed:', cause?.code);
  }

  teardown();
  // Show a user-friendly error message, and create a new quote if the user tries again
  break;
}
```

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.

> [!WARNING]
>
> 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](https://developer.uphold.com/rest-apis/on-off-ramp-api/orders/webhooks/order-status-changed.md) and [Order timeline updated](https://developer.uphold.com/rest-apis/on-off-ramp-api/orders/webhooks/order-timeline-updated.md) webhooks, and call [Get order](https://developer.uphold.com/rest-apis/on-off-ramp-api/orders/get-order.md) as a fallback when webhook delivery cannot be guaranteed. Use the `order.id` from the `complete` event.

See [Monitor the order](https://developer.uphold.com/developer-guides/on-off-ramp/on-ramp/via-rest-api/pull-deposit.md#monitor-the-order) and [Handle failures](https://developer.uphold.com/developer-guides/on-off-ramp/on-ramp/via-rest-api/pull-deposit.md#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](https://developer.uphold.com/rest-apis/on-off-ramp-api/orders/webhooks/order-status-changed.md) webhook.

> [!TIP]
>
> You now support on-ramp orders via the Payment Widget.
