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

# Offramp Widget

> Redirect users to Partna's offramp widget

The offramp widget lets you redirect users to a Partna-managed flow where they can send crypto and receive local currency. Use this flow when you want Partna to handle the payout collection interface and transaction instructions.

## Base URLs

| Environment  | URL                                                |
| ------------ | -------------------------------------------------- |
| `staging`    | `https://staging-pay.getpartna.com/v4/pay/offramp` |
| `production` | `https://pay.getpartna.com/v4/pay/offramp`         |

## Query parameters

| Parameter       | Required | Description                                                             |
| --------------- | -------- | ----------------------------------------------------------------------- |
| `amount`        | Yes      | Amount the user wants to convert                                        |
| `from_currency` | Yes      | Crypto the user is sending, such as `USDT`, `USDC`, `BTC`, or `ETH`     |
| `from_network`  | Yes      | Network the user is sending from, such as `tron`, `celo`, or `ethereum` |
| `to_currency`   | Yes      | Local payout currency, such as `NGN`, `KES`, or `GHS`                   |
| `merchant`      | Yes      | Your Partna merchant username                                           |
| `address`       | No       | Wallet address the crypto will be sent from                             |
| `reference`     | No       | A hex string transaction reference                                      |

## Registration modes

The widget supports two merchant-controlled registration modes:

| Mode     | Behavior                                                                           |
| -------- | ---------------------------------------------------------------------------------- |
| `open`   | Users can begin registration through the widget flow and complete onboarding later |
| `closed` | Only users you have already created can continue in the widget flow                |

You can manage this setting through [Update Settings](/api-reference/endpoint/v3/user/registration-deposit-and-fee-settings) and inspect the current value with [Get Settings](/api-reference/endpoint/v3/user/get-registration-deposit-and-fee-settings).

If your registration mode is `open`, you can use [Register Account](/api-reference/endpoint/v3/account/register-account) to create a pending registration. If your registration mode is `closed`, create the user up front with [Create Account](/api-reference/endpoint/v3/account/create-account).

The hosted flow collects the user's payout details before finalizing the transaction.

## How it works

<Steps>
  <Step title="Generate the redirect URL">
    Build a URL using the correct environment URL and the required query parameters.
  </Step>

  <Step title="Redirect the user">
    Send the user to the hosted Partna offramp flow from your app or website.
  </Step>

  <Step title="User submits payout details and sends crypto">
    The user enters the required payout details in the hosted flow and transfers the specified crypto amount.
  </Step>

  <Step title="Receive webhook updates">
    Partna sends `Offramp` webhook events as the transaction progresses. See [Webhooks](/v4/documentation/core-concepts/webhooks) for verification details.
  </Step>

  <Step title="Handle completion">
    Once the transaction reaches `completed`, the local currency payout has been sent.
  </Step>
</Steps>

## Build the redirect URL

<CodeGroup>
  ```typescript TypeScript theme={null}
  const redirectURL =
    environment === "staging"
      ? "https://staging-pay.getpartna.com/v4/pay/offramp"
      : "https://pay.getpartna.com/v4/pay/offramp";

  const params = new URLSearchParams();
  params.append("from_currency", fromCurrency);
  params.append("to_currency", toCurrency);
  params.append("from_network", fromNetwork);
  params.append("amount", amount);
  if (address) {
    params.append("address", address);
  }
  params.append("merchant", merchant);

  if (reference) {
    params.append("reference", reference);
  }

  const url = `${redirectURL}?${params.toString()}`;
  window.location.href = url;
  ```

  ```javascript JavaScript theme={null}
  const redirectURL =
    environment === "staging"
      ? "https://staging-pay.getpartna.com/v4/pay/offramp"
      : "https://pay.getpartna.com/v4/pay/offramp";

  const params = new URLSearchParams({
    from_currency: fromCurrency,
    to_currency: toCurrency,
    from_network: fromNetwork,
    amount,
    merchant,
  });

  if (address) {
    params.append("address", address);
  }

  if (reference) {
    params.append("reference", reference);
  }

  window.location.href = `${redirectURL}?${params.toString()}`;
  ```
</CodeGroup>

## Example redirect URL

```text theme={null}
https://pay.getpartna.com/v4/pay/offramp?amount=0.11&from_currency=CUSD&from_network=celo&to_currency=KES&address=0x00B6845c6F47C770cE630B96df9BD4A6dA91C65d&merchant=your-merchant-username&reference=a13953b727b9f20ab1ab76dfd9abe4ca
```

For staging, use `https://staging-pay.getpartna.com/v4/pay/offramp` instead.

## Transaction lifecycle

Partna emits `Offramp` webhooks with these statuses:

| Status       | Meaning                                                             |
| ------------ | ------------------------------------------------------------------- |
| `pending`    | The offramp request has been created and is awaiting crypto payment |
| `received`   | Partna has received the user's crypto transfer                      |
| `processing` | Conversion or payout is currently being processed                   |
| `completed`  | The local currency payout is complete                               |

## Sample webhook payloads

### `pending`

```json theme={null}
{
  "event": "Offramp",
  "data": {
    "transactionReference": "a13953b727b9f20ab1ab76dfd9abe4ca",
    "status": "pending",
    "timestamp": 1773706850,
    "fromAmount": 0.11,
    "toAmount": 12.93,
    "fromCurrency": "CUSD",
    "toCurrency": "KES",
    "fromNetwork": "celo",
    "toNetwork": "kenyanshilling",
    "totalFeesInFromCurrency": 0.0089,
    "totalFeesInToCurrency": 1.14,
    "sendingAddress": "0x00B6845c6F47C770cE630B96df9BD4A6dA91C65d",
    "paymentAddress": "0xc89f5afe4d5c13daeef96164abc8001c1e320718",
    "expireAt": 1773710450,
    "toExternalAccount": "Safaricom::0726140198::::MOBILE"
  },
  "signature": "BASE64_SIGNATURE"
}
```

### `received`

```json theme={null}
{
  "event": "Offramp",
  "data": {
    "transactionReference": "a13953b727b9f20ab1ab76dfd9abe4ca",
    "status": "received",
    "timestamp": 1773706902,
    "transactionHash": "0xeefee6c33e572458e6aef553b1572c58084ad59d7f3bcec9654d60810def6d2b",
    "fromAmount": 0.11,
    "fromCurrency": "CUSD",
    "toCurrency": "KES",
    "sendingAddress": "0x00B6845c6F47C770cE630B96df9BD4A6dA91C65d"
  },
  "signature": "BASE64_SIGNATURE"
}
```

### `processing`

```json theme={null}
{
  "event": "Offramp",
  "data": {
    "transactionReference": "a13953b727b9f20ab1ab76dfd9abe4ca",
    "status": "processing",
    "timestamp": 1773706921,
    "fromAmount": 0.11,
    "toAmount": 12.9392,
    "fromCurrency": "CUSD",
    "toCurrency": "KES",
    "fromNetwork": "celo",
    "toNetwork": "kenyanshilling",
    "sendingAddress": "0x00B6845c6F47C770cE630B96df9BD4A6dA91C65d",
    "expireAt": 1773710450,
    "toExternalAccount": "Safaricom::0726140198::::MOBILE"
  },
  "signature": "BASE64_SIGNATURE"
}
```

### `completed`

```json theme={null}
{
  "event": "Offramp",
  "data": {
    "transactionReference": "a13953b727b9f20ab1ab76dfd9abe4ca",
    "status": "completed",
    "timestamp": 1773706921,
    "sessionId": "DFE48F597F",
    "fromAmount": 0.11,
    "toAmount": 12.9392,
    "fromCurrency": "CUSD",
    "toCurrency": "KES",
    "fromNetwork": "celo",
    "toNetwork": "kenyanshilling",
    "sendingAddress": "0x00B6845c6F47C770cE630B96df9BD4A6dA91C65d",
    "toExternalAccount": "Safaricom::0726140198::::MOBILE"
  },
  "signature": "BASE64_SIGNATURE"
}
```

## When to use the hosted widget

Use the hosted widget when you want:

* A redirect-based offramp experience with less frontend work
* Partna to collect payout details inside the hosted flow
* A fast way to launch crypto-to-fiat payouts

Use the API-based [Offramp Guide](/v4/documentation/guides/offramp) when you need to manage account resolution, payout details, and user experience yourself.