> ## 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 with a pull deposit via the REST API

> Let users buy crypto with a card or an alternative payment method in a single on-ramp order paid through a pull deposit, using the Uphold REST API, together with the Payment Widget for alternative payment methods.

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.

> [!NOTE]
>
> In a [pull deposit](https://developer.uphold.com/rest-apis/on-off-ramp-api/introduction.md#pull-and-push-deposits), 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](https://developer.uphold.com/developer-guides/on-off-ramp/on-ramp/via-rest-api/push-deposit.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, 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](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: Check available rails
  B->>A: List rails
  A-->>B: { rails }
  Usr->>U: Choose payment method, crypto destination and 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
  alt Card origin
    U->>B: Create order
    B->>A: POST /on-off-ramp/orders
    A-->>B: { order }
    B-->>U: { order }
    opt origin.node.confirmationUrl present
      U->>Usr: Redirect to confirmationUrl (3DS)
      Usr->>U: Return to returnUrl
    end
  else APM origin
    U->>B: Create Payment Widget session
    B->>A: Create Payment Widget session (order:authorize-deposit)
    A-->>B: { session }
    B-->>U: { session }
    U->>P: Initialize widget
    Usr->>P: Authorize the payment
    P->>A: Create order
    A-->>P: { order (with confirmationUrl if 3DS is required) }
    opt confirmationUrl present (Google Pay)
      Usr->>P: Complete the 3DS challenge
    end
    P-->>U: complete { order, trigger }
  end
  A-->>B: Webhooks (status changed, timeline updated)
  B-->>Usr: Notify the user
```

***

## Define the origin

The origin is the payment method the user pays with.

### Card

#### Check available rails

Call [List rails](https://developer.uphold.com/rest-apis/on-off-ramp-api/assets/list-rails.md) with `rampType=on-ramp` and `type=card` to verify that a card rail with the `deposit` feature is available for on-ramp orders.

```http theme={null}
GET /on-off-ramp/rails?rampType=on-ramp&type=card
```

```json theme={null}
{
  "rails": [
    {
      "rampType": "on-ramp",
      "type": "card",
      "network": "visa",
      "method": "debit-card",
      "asset": "USD",
      "decimals": 2,
      "features": [
        "deposit"
      ]
    }
  ]
}
```

#### Link or select the card

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](https://developer.uphold.com/rest-apis/core-api/external-accounts/list-external-accounts.md) to fetch the user's saved cards.

```http theme={null}
GET /core/external-accounts
```

Make sure the selected card has `status: "ok"` and **deposit** in `features`.

```json theme={null}
{
  "externalAccounts": [
    {
      "id": "7d5928c5-8ac4-4b0d-8b45-f332ba6a9de7",
      "ownerId": "e4ce04dc-67b7-4e9f-af91-482cb6f9fc4a",
      "type": "card",
      "status": "ok",
      "label": "My Visa Card",
      "asset": "GBP",
      "network": "visa",
      "features": [
        "deposit",
        "withdraw"
      ],
      "details": {
        "type": "debit",
        "last4Digits": "5119",
        "expiryDate": {
          "month": 12,
          "year": 2028
        },
        "octSupport": "supported"
      },
      "createdAt": "2026-06-01T12:00:00Z",
      "updatedAt": "2026-06-01T12:00:00Z"
    }
  ]
}
```

If the user wants to use a card not yet on file, call [Create external account](https://developer.uphold.com/rest-apis/core-api/external-accounts/create-external-account.md) with the card details.

> [!NOTE]
>
> 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 [Order - Select Deposit Origin](https://developer.uphold.com/developer-guides/on-off-ramp/on-ramp/via-payment-widget.md#select-the-origin) flow.

```http theme={null}
POST /core/external-accounts
{
  "type": "card",
  "label": "My Visa Card",
  "number": "4921817844445119",
  "securityCode": "123",
  "expiryDate": {
    "month": 12,
    "year": 2028
  }
}
```

The response initially returns `status: "processing"` while the card is validated.

```jsonc theme={null}
{
  "externalAccount": {
    "id": "7d5928c5-8ac4-4b0d-8b45-f332ba6a9de7",
    "type": "card",
    "status": "processing",
    "label": "My Visa Card"
    // ...
  }
}
```

Once validated, the status transitions to `ok` and the full details are available.

```json theme={null}
{
  "externalAccount": {
    "id": "7d5928c5-8ac4-4b0d-8b45-f332ba6a9de7",
    "ownerId": "e4ce04dc-67b7-4e9f-af91-482cb6f9fc4a",
    "type": "card",
    "status": "ok",
    "label": "My Visa Card",
    "asset": "GBP",
    "network": "visa",
    "features": [
      "deposit",
      "withdraw"
    ],
    "details": {
      "type": "debit",
      "last4Digits": "5119",
      "expiryDate": {
        "month": 12,
        "year": 2028
      },
      "octSupport": "supported"
    },
    "createdAt": "2026-06-01T12:00:00Z",
    "updatedAt": "2026-06-01T12:00:00Z"
  }
}
```

> [!NOTE]
>
> Monitor the external account status via [Get external account](https://developer.uphold.com/rest-apis/core-api/external-accounts/get-external-account.md) or the [`core.external-account.status-changed`](https://developer.uphold.com/rest-apis/core-api/external-accounts/webhooks/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:

| Error | Cause | Recommended action |
| - | - | - |
| `409 duplicate` | The card is already linked. | Use the existing card account instead. |
| `409 number_invalid`, `409 date_invalid` | The card number or expiry date is invalid. | Ask the user to check the card details. |
| `409 card_type_not_allowed` | The card type, given in `details.type`, isn't accepted. | Ask the user to use another card. |
| `409 operation_not_allowed` (`card-declined`, `card-permanently-declined`) | The card can't be used. | Ask the user to use another card. |
| `409 operation_not_allowed` (`card-issuer-country-mismatch`) | The card was issued in a country other than the user's country of residence. | Ask the user to use a card issued in their country of residence. |
| `409 user_capability_failure` (`capability.code: "cards"`) with the `user-must-delete-card` requirement | The user reached the maximum number of active cards. | Ask the user to remove a card they no longer use, then link the new one. |
| `409 user_capability_failure` (`capability.code: "cards"`) with the `user-unique-card-limit-reached` restriction | The user reached the maximum number of cards they can ever link. | Explain that no more cards can be linked. |
| `409 user_capability_failure` (`capability.code: "cards"`) with other requirements, such as `user-must-submit-identity` | The user must complete verification before linking cards. | Have the user complete the requirements listed in `details.capability`. |

#### 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](https://developer.uphold.com/rest-apis/on-off-ramp-api/assets/list-rails.md) with `rampType=on-ramp` and `type=apm` to find the APMs the user can pay with: those whose `features` include `deposit`.

```http theme={null}
GET /on-off-ramp/rails?rampType=on-ramp&type=apm
```

```json theme={null}
{
  "rails": [
    {
      "rampType": "on-ramp",
      "type": "apm",
      "network": "paypal",
      "method": "paypal",
      "asset": "USD",
      "decimals": 2,
      "features": [
        "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](#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](https://developer.uphold.com/rest-apis/on-off-ramp-api/assets/list-rails.md) 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.

```http theme={null}
GET /on-off-ramp/rails?rampType=on-ramp&type=crypto
```

```json theme={null}
{
  "rails": [
    {
      "rampType": "on-ramp",
      "type": "crypto",
      "network": "bitcoin",
      "method": "crypto-transaction",
      "asset": "BTC",
      "decimals": 8,
      "features": [
        "withdraw"
      ]
    }
  ]
}
```

Call [List networks](https://developer.uphold.com/rest-apis/core-api/assets/list-networks.md) to find the networks available for the chosen asset. For a crypto address, call [Validate network address](https://developer.uphold.com/rest-apis/core-api/assets/validate-network-address.md) 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](https://developer.uphold.com/rest-apis/on-off-ramp-api/orders/create-quote.md) 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.

```http theme={null}
POST /on-off-ramp/orders/quote
{
  "type": "on-ramp",
  "origin": {
    "type": "external-account",
    "id": "7dc5c846-5ac2-4853-b67f-005cb83d4017"
  },
  "destination": {
    "type": "crypto-address",
    "asset": "XRP",
    "network": "xrp-ledger",
    "address": "rfBtmHiLwwWH5maH2PT78GxubrSydRF9aY",
    "reference": "67809592"
  },
  "denomination": {
    "asset": "USD",
    "amount": "100.00",
    "target": "origin"
  }
}
```

To pay with an APM, set the origin to `{ "type": "apm", "method": "apple-pay" }`.

```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": "external-account",
        "id": "7dc5c846-5ac2-4853-b67f-005cb83d4017",
        "ownerId": "cd21b26d-35d2-408a-9201-b8fdbef7a604",
        "via": "card",
        "network": "visa"
      }
    },
    "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:3ds",
        "quoteId": "b0a0e8d4-3c4e-4f3a-9d1e-6f5b2c7a8e91"
      }
    ],
    "refreshAt": "2024-07-24T15:22:39.000Z",
    "expiresAt": "2024-07-24T15:22:39.000Z"
  }
}
```

Present `origin.amount`, `destination.amount` and the `fees` to the user.

> [!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: 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](#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](#pay-with-an-apm).
* `travel-rule` must be resolved before creating the order, 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.

## Create the order

Once the user confirms, call [Create order](https://developer.uphold.com/rest-apis/on-off-ramp-api/orders/create-order.md) 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](https://developer.uphold.com/rest-apis/headers.md#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`.

```http theme={null}
POST /on-off-ramp/orders
X-Uphold-User-Ip: <user-ip>
X-Uphold-User-Agent: <user-agent>
{
  "quoteId": "623000c8-9bdf-4a2b-aa3d-6a6b44a7f6a0",
  "params": {
    "requirements": [
      {
        "name": "authorize:3ds",
        "returnUrl": "https://example.com/redirect"
      }
    ]
  },
  "metadata": {
    "externalId": 123
  }
}
```

```json [expandable] theme={null}
{
  "order": {
    "id": "623000c8-9bdf-4a2b-aa3d-6a6b44a7f6a0",
    "type": "on-ramp",
    "pricing": "locked",
    "origin": {
      "asset": "USD",
      "amount": "100.00",
      "rate": "2.07021435361804542440",
      "node": {
        "type": "external-account",
        "id": "7dc5c846-5ac2-4853-b67f-005cb83d4017",
        "ownerId": "cd21b26d-35d2-408a-9201-b8fdbef7a604",
        "via": "card",
        "network": "visa",
        "confirmationUrl": "https://authentication-devices.sandbox.checkout.com/sessions-interceptor/sid_zrih63pnk6ietkpuerqiyd5zga"
      }
    },
    "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"
      }
    ],
    "status": "processing",
    "timeline": [],
    "quotedAt": "2024-07-24T15:02:39.000Z",
    "createdAt": "2024-07-24T15:03:39.000Z",
    "updatedAt": "2024-07-24T15:03:39.000Z"
  }
}
```

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](https://developer.uphold.com/rest-apis/widgets-api/payment/create-session.md) 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](https://developer.uphold.com/developer-guides/on-off-ramp/on-ramp/via-payment-widget.md#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](https://developer.uphold.com/rest-apis/on-off-ramp-api/orders/webhooks/order-status-changed.md), when the `status` of the order changes.
* [Order timeline updated](https://developer.uphold.com/rest-apis/on-off-ramp-api/orders/webhooks/order-timeline-updated.md), when an event is added to the `timeline`, such as `deposit-completed` or `withdrawal-sent`.

### Via polling

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.

```http theme={null}
GET /on-off-ramp/orders/623000c8-9bdf-4a2b-aa3d-6a6b44a7f6a0
```

> [!TIP]
>
> Prefer webhooks over polling in production. See [Webhooks](https://developer.uphold.com/rest-apis/webhooks.md) for setup instructions.

## Notify the user

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

> [!TIP]
>
> 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](#request-errors). An order that was created becomes `failed` when it cannot be completed. Read its `timeline` to tell which leg failed:

| Timeline event | Meaning | What to do |
| - | - | - |
| `deposit-failed` | The user's payment failed or was declined. The `reason` says why: see [Failure reasons](#failure-reasons). | Let the user try again with a new quote. |
| `withdrawal-failed` | The crypto could not be sent. | Check the [refund outcome](#refund-outcome). |
| `withdrawal-commit-failed` | The withdrawal could not be started. The `error` says why. | Check the [refund outcome](#refund-outcome). |

### Request errors

[Create quote](https://developer.uphold.com/rest-apis/on-off-ramp-api/orders/create-quote.md) and [Create order](https://developer.uphold.com/rest-apis/on-off-ramp-api/orders/create-order.md) 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.

| Error | Cause | Recommended action |
| - | - | - |
| `409 user_capability_failure` (`capability.code: "on-ramp"`) | The user can't place the order. `details.capability` lists the `requirements` to complete, such as verifying a higher [tier](https://developer.uphold.com/rest-apis/on-off-ramp-api/introduction.md#capabilities-and-verification-tiers) that this order's amount would put the user in, and the `restrictions` that apply. | Have the user complete the requirements, or explain the restriction. |
| `409 transaction_amount_invalid` (`minimum-limit-not-met`, `maximum-limit-exceeded`) | The amount is below the minimum or above the maximum of a single order. | Show the limit from `details.limit` and ask for another amount. |
| `409 transaction_amount_invalid` (`amount-exceeds-daily-limit`, `amount-exceeds-weekly-limit`, `amount-exceeds-monthly-limit`) | The amount exceeds the user's limit for the period. | Show the `details.limit.remainingAmount` and ask for a lower amount. |
| `409 crypto_address_invalid` | The `address` is invalid for the network, or the `reference` (such as a memo or destination tag) is missing or invalid for a network that requires one. Only for a crypto address destination. | Ask the user to check the address and reference, then create a new quote. Calling [Validate network address](https://developer.uphold.com/rest-apis/core-api/assets/validate-network-address.md) before creating the quote catches these errors earlier. |
| `409 operation_not_allowed` (`pending-requests-for-information`) | When creating the order, the `travel-rule` requirement of the quote isn't resolved yet. | Resolve it first, as described in [Travel rule](#travel-rule), then create the order. |
| `409 operation_not_allowed` (`user-tier-changed`) | When creating the order, the user's verification tier changed after the quote was created. | Create a new quote and ask the user to confirm again. |
| `409 operation_not_allowed` with a transaction status reason, such as `card-declined` or `card-unauthorized` | When creating the order, the card payment failed. | Handle it as the matching [failure reason](#failure-reasons). |
| `409 operation_not_allowed` (`duplicate-deposit`) | When creating the order, the same quote was already being used, for example after a double submit. | Don't retry. Track the order created by the first request instead. |
| `409 operation_not_allowed` (`country-restricted-transaction`) | The order isn't allowed for the user's country. | Tell the user the order isn't available to them. |
| `404 entity_not_found` (`entity: "quote"`) | When creating the order, the quote expired or was already used. | Create a new quote and ask the user to confirm again. |
| `409 operation_not_allowed` (`quote-rate-variance-not-allowed`) | When creating the order, the rate moved too far from the rate of the quote. | Create a new quote and ask the user to confirm again. |
| `409 operation_not_allowed` (`unspecified-error`) | The request failed for another reason. | Show a generic error, and ask the user to try again or contact support. |

### 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](https://developer.uphold.com/rest-apis/on-off-ramp-api/orders/get-order.md). The table only lists the reasons your integration should act on, such as by notifying the user.

| Reason | Cause | Recommended action |
| - | - | - |
| `card-declined`, `card-declined-by-bank` | The card issuer declined the payment, including when the 3DS authentication failed or wasn't completed in time. | Ask the user to try again and complete the 3DS challenge if one is shown, to use another card, or to contact their bank. |
| `card-permanently-declined-by-bank` | The card issuer declined the card for good. | Ask the user to use another card. |
| `card-unauthorized` | The payment was blocked, for example by risk checks or because the card doesn't support 3DS. | Ask the user to use another card, or to contact support. |
| `card-expired`, `card-unsupported` | The card has expired, or its type or brand isn't supported. | Ask the user to use another card. |
| `insufficient-funds` | The card doesn't have enough funds or credit. | Ask the user to try a lower amount or another card. |
| `provider-maximum-limit-exceeded` | The amount exceeds what the payment provider allows. | Ask the user to try a lower amount. |
| `apm-authorization-failed`, `apm-payment-method-declined` | The payment provider didn't authorize the payment, or declined the payment method. | Ask the user to try another payment method. |
| `apm-account-holder-data-mismatch`, `apm-missing-account-holder-data` | The payment provider couldn't match the account holder details. | Ask the user to check their account details and try again. |
| `velocity` | Too many transactions were made in a short time. | Ask the user to try again later. |
| `travel-rule-verification-failed`, `screening-verification-failed` | The order couldn't be verified. | Tell the user the order failed, and ask them to contact support. |
| `user-tier-changed` | The user's verification tier changed after the quote was created, for example because another order completed in between. | Create a new quote and ask the user to confirm again. |
| `unspecified-error` | The order failed for another reason. | Tell the user the order failed, and ask them to try again or contact support. |

### 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`:

| Timeline event | What to do |
| - | - |
| `refund-completed` | The payment was refunded. Tell the user, and let them try again with a new quote. |
| `refund-failed`, `refund-skipped`, `refund-commit-failed` | The payment was not refunded. Contact support. |

See [Refunds](https://developer.uphold.com/rest-apis/on-off-ramp-api/orders/overview.md#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](https://developer.uphold.com/rest-apis/on-off-ramp-api/orders/webhooks/order-status-changed.md) webhook.
