Cookbook: Sell a Product

End-to-end fixed-price crypto sale with paylinks and webhooks.

This cookbook walks a fixed-price product sale from setup through fulfillment.

1. Prerequisites

• Create an Account and Authentication
• Settlement Overview for the chains/assets you accept
• HTTPS webhook endpoint with Verify Webhook Signatures

2. Create the product paylink

curl -X POST "https://mapi.zbx.boomfi.xyz/v1/paylinks" \
  -H "X-API-KEY: sk_test_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Widget",
    "amount": "49.00",
    "currency": "USD",
    "reference": "order_1001",
    "type": "OneTime",
    "available_quantity": 1
  }'

Store the returned id and checkout URL against your internal order.

3. Present checkout

Redirect the buyer to the paylink URL (email, cart page, or in-app webview). See Checkout.

4. Handle the webhook

On each POST to your endpoint:

1. Read raw body bytes and headers X-BoomFi-Signature, X-BoomFi-Timestamp
2. Verify Webhook Signatures
3. Confirm org_id matches your organisation
4. If event is Payment.Updated and status is Succeeded, mark the order paid and fulfill

Respond with 2xx quickly after persisting the event (idempotent on payment id).

5. Reconcile failures

If delivery fails, open
https://merchants.zbx.boomfi.xyz/dashboard/settings/api-keys?tab=webhooks
filter failed events, fix your endpoint, then Retry or bulk replay. See Event History and Replay.

6. Optional API reconciliation

curl "https://mapi.zbx.boomfi.xyz/v1/payments" \
  -H "X-API-KEY: sk_test_xxx"

Use list/get payment endpoints when you need to backfill state independently of webhooks.