Skip to main content

​
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: 
// 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: 
// 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: 
// 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

1

Create invoice via API

Use the POST /api/v1/invoices endpoint with amount, currency, and webhook URL.
2

Redirect to paymentUrl

Send the customer to invoice.paymentUrl (can be a redirect or an iframe).
3

Receive webhooks

Handle invoice.settled to fulfill the order and invoice.expired for timeouts.
4

Verify webhook signatures

Set a webhook secret in the dashboard and verify the X-Webhook-Signature header on every delivery.

​
Customising the checkout page

Branding options — including your logo, primary colour, and post-payment return URL — can be configured via the Settlx Dashboard under Settings → Checkout.