# Redirect Checkout — Web Implementation

## Opening the checkout

Use the `checkoutUrl` returned by `POST /v2/buy` or `POST /v2/sell` (API integration), or your constructed referral URL (Referral integration).

### New tab (recommended)

```javascript
function openBanxaCheckout(checkoutUrl) {
  window.open(checkoutUrl, '_blank', 'noopener,noreferrer');
}
```

Opening in a new tab keeps your application visible in the background, so the customer can return to it after checkout completes.

### Same window

```javascript
function openBanxaCheckout(checkoutUrl) {
  window.location.href = checkoutUrl;
}
```

Use this when you prefer a full-page transition. The customer will be redirected back to your `redirectUrl` on completion.

## Handling the return

When the customer finishes (or cancels) checkout, Banxa redirects them to the `redirectUrl` you specified when creating the order.

### Return URL parameters

Banxa can append order parameters to your return URL on completion, allowing you to read the outcome without an additional API call. Contact your Account Manager to enable this for your account.

When enabled, the following parameters are appended:

| Parameter | Description |
|  --- | --- |
| `orderId` | The Banxa order ID |
| `orderRef` | Banxa's internal order reference |
| `orderStatus` | Final order status |
| `fulfillmentStatus` | Fulfilment status of the order |
| `paymentStatus` | Payment processing status |
| `identityStatus` | KYC/identity status |
| `fiatAmount` | Fiat amount in the order |
| `fiat` | Fiat currency code |
| `coinAmount` | Crypto amount in the order |
| `coin` | Cryptocurrency code |


**Tip:** To link the customer to the Banxa order status page, append the `orderRef` value to your return URL — e.g. `https://{partnerRef}.banxa.com/status/{orderRef}`.

For the authoritative order status, use the [order lookup endpoint](/products/hosted-checkout/docs/transaction-lifecycle/order-lookup) or [webhooks](/products/hosted-checkout/docs/transaction-lifecycle/webhooks) — do not rely solely on return URL parameters.

## Security

Set `noopener,noreferrer` when opening in a new tab to prevent the checkout page from accessing your `window` object.

## Example flow

```javascript
async function startBanxaCheckout(orderParams) {
  // 1. Create order
  const response = await fetch('/api/create-banxa-order', {
    method: 'POST',
    body: JSON.stringify(orderParams)
  });
  const { checkoutUrl, orderId } = await response.json();

  // 2. Store orderId for later status lookup
  sessionStorage.setItem('pendingBanxaOrderId', orderId);

  // 3. Redirect customer to checkout
  window.open(checkoutUrl, '_blank', 'noopener,noreferrer');
}
```