Quickstart

Overview

The integration has three steps:

Your backend creates an invoice and gets a paymentUrl
You redirect the customer to the paymentUrl
You receive an invoice.settled webhook when the funds land in your wallet

That’s the entire integration. Settlx handles the checkout UI, chain selection, payment detection, confirmation, conversion, and settlement automatically.

Step 1 — Create an invoice

When a customer is ready to pay, call POST /api/v1/invoices from your backend.

curl -X POST https://api.settlx.io/api/v1/invoices \
  -H "Authorization: Bearer pgk_live_xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": "49.99",
    "currency": "USD",
    "description": "Pro Plan - Monthly",
    "webhookUrl": "https://your-backend.com/webhooks/settlx",
    "metadata": {
      "orderId": "order_123",
      "customerId": "cust_456"
    }
  }'

Response:

{
  "data": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "amount": "49.99",
    "currency": "USD",
    "status": "pending",
    "paymentUrl": "https://api.settlx.io/checkout/a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "expiresAt": null,
    "createdAt": "2026-04-12T10:00:00.000Z"
  }
}

Always pass metadata.orderId. It is included in every webhook payload so you can match the payment to your internal order without a database lookup.

Step 2 — Redirect the customer

Send the customer to the paymentUrl. This opens the Settlx hosted checkout where they:

See the invoice amount and your business name
Select their preferred chain and token
Get a unique deposit address and QR code
Send the payment from their wallet

You don’t build any of this — Settlx handles it entirely.

// After creating the invoice, redirect the customer
res.redirect(data.paymentUrl);

Step 3 — Receive the webhook

When the payment is confirmed and the funds have settled into your wallet, Settlx sends a POST request to the webhookUrl you provided. Always verify the signature before processing.

Verify the signature

Node.js

const crypto = require('crypto');

app.post('/webhooks/settlx', express.raw({ type: 'application/json' }), (req, res) => {
  const signature = req.headers['x-webhook-signature'];
  const expected = 'sha256=' + crypto
    .createHmac('sha256', process.env.SETTLX_WEBHOOK_SECRET)
    .update(req.body)
    .digest('hex');

  if (!crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected))) {
    return res.status(401).json({ error: 'Invalid signature' });
  }

  const event = JSON.parse(req.body);
  handleEvent(event);

  res.status(200).json({ received: true });
});

You must use express.raw() (not express.json()) for the webhook route. Signature verification requires the raw request body bytes — parsing it to JSON first will break the HMAC.

Handle the event

function handleEvent(event) {
  switch (event.event) {

    case 'invoice.settled': {
      const { orderId } = event.data.invoice.metadata;
      const netAmount = event.data.settlement.netAmount;
      const currency = event.data.settlement.currency;

      // ✅ Funds are in your wallet — fulfill the order
      fulfillOrder(orderId, netAmount, currency);
      break;
    }

    case 'invoice.expired': {
      // Customer did not pay in time — cancel the order
      break;
    }

    default:
      // Log any other events for visibility
      console.log('Settlx event:', event.event);
  }
}

Only fulfill the order on invoice.settled. This is the only event that guarantees the funds are in your wallet.

What happens in between

Once the customer sends their payment, everything is automatic:

Step	What happens	Time
Payment sent	Settlx detects it on-chain	~15–30 sec
Confirmations	Blockchain confirms the transaction	30 sec – 4 min depending on chain
Conversion	Funds swapped to your settlement currency if needed	~1–2 min
Bridge	Funds bridged to your settlement chain if needed	~3–5 min
Settlement	Funds transferred to your wallet	Instant
`invoice.settled`	Webhook fires	After transfer

Getting Started

API Reference

Webhooks

Overview

Step 1 — Create an invoice

Step 2 — Redirect the customer

Step 3 — Receive the webhook

Verify the signature

Handle the event

What happens in between

Next steps

Create Invoice

Webhook Events

Getting Started

API Reference

Webhooks

​Overview

​Step 1 — Create an invoice

​Step 2 — Redirect the customer

​Step 3 — Receive the webhook

​Verify the signature

​Handle the event

​What happens in between

​Next steps

Create Invoice

Webhook Events

Overview

Step 1 — Create an invoice

Step 2 — Redirect the customer

Step 3 — Receive the webhook

Verify the signature

Handle the event

What happens in between

Next steps