Cookbook: Offer Crypto as a PSP

You are a payment service provider (PSP) or acquirer. Merchants already collect payments through you. They also want to accept crypto. ZBX does not give you a separate PSP product. Every organisation is a merchant, including you, and including each merchant on your platform. You hold their API keys and run the same paylink flow they would run themselves.

How a merchant relates to ZBX

ZBX knows one unit: a merchant organisation. That organisation owns settlement, API keys, webhooks, and paylinks.

Piece	What it is for that merchant
Organisation	Their business on ZBX. See Create an Account.
Settlement	Where their crypto proceeds land. See Settlement Overview.
API key	Server credential scoped to that organisation. See Authentication.
Webhooks	Signed events for that organisation only. See Webhooks Overview.
Paylinks	Checkout URLs created in that organisation. See Payment Links.

A customer who pays a paylink pays that merchant. Settlement, dashboard transactions, and org_id on webhooks all belong to that merchant’s organisation.

You are a merchant too

Your PSP is itself a ZBX merchant. You can have your own organisation, keys, and settlement if you take payments for yourself. Each merchant you acquire for is also a ZBX merchant, with their own organisation. ZBX does not model your PSP-to-merchant contract. When you create a paylink for one of them, you are calling the Merchants API as that merchant.

Your PSP  (a ZBX merchant - you hold the keys)
    │
    ├── Merchant A  (a ZBX merchant)
    │     API key A → paylinks, settlement, webhooks for A
    │
    └── Merchant B  (a ZBX merchant)
          API key B → paylinks, settlement, webhooks for B

Do not create a sub-merchant’s paylink with your own PSP API key. Use their key so checkout, settlement, and webhooks belong to their organisation. You are only handling keys and driving the flow.

If you instead run one organisation and many settlement wallets, bind each paylink with account_ids or account_ref. That is a different model: Account-Specific Paylinks.

Before you proceed

Use these pages to decide whether this path works for your merchants. Wrong-chain or unsupported-token payments may not be credited.

Question	Where to look
Which chains and assets can a merchant accept?	Networks and Currencies
What does acceptance cost?	Pricing and Fees
Which countries or activities are out of scope?	Unsupported Countries, Unsupported Business Activities
When is KYC/KYB required?	Account Verification and Limits (paylinks mainly need settlement)
Uptime and support targets?	Service Level Agreement

Need commercial terms? Contact ZBX support.

What you integrate

A PSP integration is three documented surfaces. Open each before you write code.

Merchants API

REST at https://mapi.zbx.boomfi.xyz/v1. Start with Authentication and Response Patterns. In the API reference, use Paylinks, Payments, Events, and Organisation.

Webhooks

Signed events per organisation. Configure, verify signatures, then handle event types (start with Payment.Updated).

Paylinks and checkout

Create links, variant URLs, and send the customer to hosted checkout.

Use the merchant paylink flow

This cookbook does not replace those guides. Create, share, and confirm paylinks the same way a single merchant does, then swap in the right merchant’s key. Read these in order:

API Overview and Authentication: how you call the API
Networks and Currencies and Settlement Overview: what that merchant can accept
Webhooks Overview, Configure Webhooks, Verify Webhook Signatures, Event Types
Payments Overview and Payment Links: create, list, update, disable
Paylink Features: prefill, customer_ident, redirects, variant URLs
Checkout: hosted customer experience
Cookbook: Sell a Product: one-off sale from create through webhook
Cookbook: Recurring Billing: if that merchant bills on a schedule

The rest of this page is only what changes when you run that flow for many merchants.

1. Onboard each merchant as a merchant

For each merchant you enable for crypto:

Create an Account for that merchant, or have them create one and give you API access.
Configure settlement for the chains and assets they accept. Dashboard: Payments Settings.
Create an API key at https://merchants.zbx.boomfi.xyz/dashboard/settings/api-keys. See Authentication and API Authentication.
Point that organisation’s webhook URL at your PSP endpoint. See Configure Webhooks.

curl -X PUT "https://mapi.zbx.boomfi.xyz/v1/orgs" \
  -H "X-API-KEY: ${MERCHANT_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "webhook_url": "https://psp.example.com/webhooks/crypto/merchant_1042"
  }'

Organisation update fields are in the API reference Organisation group (API Overview). A path per merchant lets you select the correct webhook public key before you verify the signature. You can also use one URL and look up the key by org_id; still verify the raw body before you apply any business logic.

2. Hold their keys

Store credentials keyed by your internal merchant id:

You store	Why
API key	Call paylinks and payments as that merchant
`org_id`	Match inbound webhooks to the merchant
Webhook public key	Verify signatures for that organisation

An API key is scoped to the organisation that created it. Do not reuse one key across merchants. Keep keys in a secrets manager, never in a merchant-facing app or browser.

3. Create a paylink as that merchant

When your PSP opens a crypto payment, load that merchant’s API key and create a paylink the same way Payment Links and Cookbook: Sell a Product describe. Request and response schemas are in the API reference Paylinks group.

curl -X POST "https://mapi.zbx.boomfi.xyz/v1/paylinks" \
  -H "X-API-KEY: ${MERCHANT_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Invoice INV-8831",
    "amount": "150.00",
    "currency": "USD",
    "reference": "psp_pay_8831",
    "type": "OneTime",
    "available_quantity": 1,
    "metadata": {
      "merchant_id": "merchant_1042",
      "psp_payment_id": "psp_pay_8831"
    }
  }'

Required fields are name, amount, and currency. reference is at most 50 characters. metadata accepts at most 10 entries. Store the returned paylink id against your PSP payment. For field-by-field detail (quantity, expiry, settlement accounts, recurring interval), use Payment Links.

4. Variant paylinks (typical for a PSP)

Most PSPs do not create a new catalog paylink for every invoice. Create one (or a few) paylinks per merchant, then generate a variant URL when this checkout needs a different amount, currency, customer, or redirect. That is the same Generate variant URL call a merchant uses (API reference → Paylinks → Generate Paylink Variant URL):

curl "https://mapi.zbx.boomfi.xyz/v1/paylinks/generate-variant/${PAYLINK_ID}?amount=150.00&currency=USD&customer_ident=cust_88&redirect_to=https%3A%2F%2Fpsp.example.com%2Fthanks" \
  -H "X-API-KEY: ${MERCHANT_API_KEY}"

Query parameters (all optional): amount, currency, customer_ident, description, expires_at, redirect_to. The response wraps the checkout URL at data.url. Send the customer there. See Checkout.

Create a new paylink	Generate a variant
First time you enable crypto for that merchant	Same merchant link, this invoice’s amount or currency
One-time vs recurring (you cannot convert a link after create)	Prefill / bind a customer (`customer_ident`)
Different settlement accounts (`account_ids` / `account_ref`)	Return the payer to your PSP (`redirect_to`)

You can also append query parameters on the base paylink URL (prefill name/email, redirect_to, skip_redirect_delay). Full list: Paylink Features.

5. Present checkout

Redirect the customer to the variant data.url, or to hosted checkout for the paylink (https://pay.zbx.boomfi.xyz/<PAYLINK_ID>). After payment, redirect_to receives a pid query parameter (the payment id). You can fetch that payment with the same merchant API key (API reference → Payments). Do not fulfill from the browser landing on a success URL. Wait for a verified webhook.

6. Handle webhooks for many organisations

Webhooks are how you know a payment succeeded. Read Webhooks Overview and Webhook Best Practices first. Each merchant organisation signs deliveries with its own key pair. On each POST:

Select the merchant (URL path, or org_id used only to look up the public key).
Read raw body bytes and headers X-BoomFi-Signature, X-BoomFi-Timestamp.
Verify the signature with that organisation’s public key.
Confirm org_id matches the merchant you resolved.
Branch on event. For a one-off sale, if event is Payment.Updated and status is Succeeded, mark your PSP payment paid (idempotent on payment id) and notify the merchant through your existing PSP channels. Full catalog: Event Types.

Respond with 2xx after you persist the event.

7. Reconcile and operate

If delivery fails, open that merchant’s event history at
https://merchants.zbx.boomfi.xyz/dashboard/settings/api-keys?tab=webhooks
then retry or bulk replay. See Event History and Replay. The API reference Events group lists the same deliveries. List payments with the same merchant API key when you need to backfill independently of webhooks:

curl "https://mapi.zbx.boomfi.xyz/v1/payments" \
  -H "X-API-KEY: ${MERCHANT_API_KEY}"

Merchants can still open the merchant dashboard to review their own paylinks and transactions. Your platform remains the system that creates links and updates payment state. API

Webhooks

Paylinks

Policy and settlement

Get Started

Dashboard

Settlement

Payments

Deposit Accounts

Trading

Webhooks

Integrations

Pricing and Policies

Cookbook: Offer Crypto as a PSP

How a merchant relates to ZBX

You are a merchant too

Before you proceed

What you integrate

Merchants API

Webhooks

Paylinks and checkout

Use the merchant paylink flow

1. Onboard each merchant as a merchant

2. Hold their keys

3. Create a paylink as that merchant

4. Variant paylinks (typical for a PSP)

5. Present checkout

6. Handle webhooks for many organisations

7. Reconcile and operate

​How a merchant relates to ZBX

​You are a merchant too

​Before you proceed

​What you integrate

Merchants API

Webhooks

Paylinks and checkout

​Use the merchant paylink flow

​1. Onboard each merchant as a merchant

​2. Hold their keys

​3. Create a paylink as that merchant

​4. Variant paylinks (typical for a PSP)

​5. Present checkout

​6. Handle webhooks for many organisations

​7. Reconcile and operate

​Related

How a merchant relates to ZBX

You are a merchant too

Before you proceed

What you integrate

Use the merchant paylink flow

1. Onboard each merchant as a merchant

2. Hold their keys

3. Create a paylink as that merchant

4. Variant paylinks (typical for a PSP)

5. Present checkout

6. Handle webhooks for many organisations

7. Reconcile and operate

Related