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

# Hosted Checkout

> Accept crypto payments using the Settlx hosted checkout page

# Hosted Checkout

The simplest integration path. Create an invoice via the API and redirect your customer to the Settlx-hosted checkout page. No frontend work required.

## How it works

1. Your backend creates an invoice via API
2. You redirect the customer to `invoice.paymentUrl`
3. The customer selects token + chain on the Settlx checkout page
4. A unique payment address is shown with a QR code
5. The customer pays from their wallet
6. Settlx sends webhooks to your backend as the payment progresses

## Step 1 — Create the invoice

When your customer clicks "Pay with Crypto" in your checkout:

```javascript theme={null}
// server.js (Node.js example)
app.post('/checkout/initiate', async (req, res) => {
  const { orderId, amount } = req.body;
  
  const response = await fetch('https://api.settlx.io/api/v1/invoices', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.SETTLX_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      amount: amount.toString(),
      currency: 'USD',
      description: `Order #${orderId}`,
      expiresInMinutes: 30,
      webhookUrl: `${process.env.BASE_URL}/webhooks/settlx`,
      metadata: { orderId }
    })
  });
  
  const { data: invoice } = await response.json();
  
  // Save invoice ID for later lookup
  await db.orders.update({
    where: { id: orderId },
    data: { settlxInvoiceId: invoice.id }
  });
  
  // Redirect customer to hosted checkout
  res.redirect(invoice.paymentUrl);
});
```

## Step 2 — Handle webhooks

Set up your webhook endpoint to receive payment events:

```javascript theme={null}
// Webhook handler
app.post('/webhooks/settlx', express.raw({ type: 'application/json' }), async (req, res) => {
  // Verify signature (recommended)
  const signature = req.headers['x-webhook-signature'];
  if (!verifySignature(req.body, signature, process.env.SETTLX_WEBHOOK_SECRET)) {
    return res.status(401).send('Invalid signature');
  }
  
  const event = JSON.parse(req.body);
  
  switch (event.event) {
    case 'invoice.settled': {
      // Funds are in your wallet — safe to fulfill the order
      const orderId = event.data.invoice.metadata?.orderId;
      await fulfillOrder(orderId);
      break;
    }

    case 'invoice.expired': {
      // Payment was not received within the expiry window
      const orderId = event.data.invoice.metadata?.orderId;
      await markOrderExpired(orderId);
      break;
    }
  }
  
  res.status(200).send('OK');
});
```

## Step 3 — Handle the return (optional)

After payment, you can redirect customers back to your site. Add a success/cancel URL as metadata:

```javascript theme={null}
// Include return URLs in metadata
body: JSON.stringify({
  amount: '99.99',
  currency: 'USD',
  metadata: {
    orderId: '1234',
    successUrl: 'https://yoursite.com/order/1234/success',
    cancelUrl: 'https://yoursite.com/order/1234/cancel'
  }
})
```

Then in your webhook handler, redirect based on payment status.

## Complete integration checklist

<Steps>
  <Step title="Create invoice via API">
    Use the `POST /api/v1/invoices` endpoint with amount, currency, and webhook URL.
  </Step>

  <Step title="Redirect to paymentUrl">
    Send the customer to `invoice.paymentUrl` (can be a redirect or an iframe).
  </Step>

  <Step title="Receive webhooks">
    Handle `invoice.settled` to fulfill the order and `invoice.expired` for timeouts.
  </Step>

  <Step title="Verify webhook signatures">
    Set a webhook secret in the dashboard and verify the `X-Webhook-Signature` header on every delivery.
  </Step>
</Steps>

## Customising the checkout page

Branding options — including your logo, primary colour, and post-payment return URL — can be configured via the [Settlx Dashboard](https://app.settlx.io) under **Settings → Checkout**.