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.

Reading payment details server-side​

A webhook tells you the invoice changed state. To reconcile the amounts, read the invoice with your API key:

  • GET /api/v1/stores/{storeId}/invoices/{invoiceId} returns status, additionalStatus, amount (expected, satoshis), totalPaid (received, satoshis), currency and exchangeRate. These fields are stable and safe to build against.
  • GET /api/v1/stores/{storeId}/invoices/{invoiceId}/payments returns the individual customer payments, each with its own amount, networkFee, transactionId, status and receivedDate.

The Coinsnap service fee is not returned by either endpoint. It is billed against your prepaid balance rather than recorded on the invoice, so read it from your transactions instead. See Wallets and settlement.

Do not use the public checkout endpoint (/api/v1/checkout/invoices/{invoiceId}) from your backend. It is the payer-facing read model, authenticated by the invoice ID alone, and it deliberately omits rate and fee data.

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.