Skip to main content

Custom Integration Path

If you are building your own backend integration, use this as the canonical path through the docs.

Read these pages in order:

  1. Quickstart Build the happy path once: create an invoice, redirect to checkout, and receive a webhook.

  2. Accept Bitcoin Payments Read the production-oriented integration guide with backend examples and implementation details.

  3. Checkout Flow Add the real order lifecycle: pending, processing, settled, expired, redirects, and retries.

  4. Webhook Status Reference Use this as the compact event-action table when wiring order updates and fulfillment logic.

  5. API Reference Use this for exact request and response fields once you know the flow you want to build.

Minimum viable production flow​

Start with the shortest safe path:

  1. Create an order in your system.
  2. Call POST /stores/{storeId}/invoices from your backend.
  3. Redirect the customer to checkoutLink.
  4. Verify the webhook signature.
  5. Mark the order as paid only when you receive Settled.

That is enough for many teams to ship a working integration.

What to add next​

After the happy path works, add these in order:

  1. Processing handling for Bitcoin confirmation delays.
  2. Expired handling for unpaid or partially paid invoices.
  3. Idempotency guards so duplicate webhook deliveries do not double-fulfill an order.
  4. Reconciliation using your orderId.
  5. Monitoring and retry visibility for webhook failures.

When to branch into other sections​

  • Use Examples if you want language-specific starter code.
  • Use Payment Links if your flow is async, email-based, or invoice-based.
  • Use Plugins if you do not want a custom backend integration.

One rule to keep in mind​

Do not treat the customer redirect as payment confirmation.

Always use the webhook as the source of truth for order state.