> ## Documentation Index
> Fetch the complete documentation index at: https://docs.boomfi.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# Cookbook: Offer Crypto as a PSP

> You are a merchant. Your merchants are merchants too. Hold their API keys and run the paylink flow on their behalf.

You are a payment service provider (PSP) or acquirer. Merchants already collect payments through you. They also want to accept crypto.

BoomFi 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](/payments/paylinks) they would run themselves.

## How a merchant relates to BoomFi

BoomFi 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 BoomFi. See [Create an Account](/create-account).                        |
| Settlement   | Where their crypto proceeds land. See [Settlement Overview](/settlement/overview).         |
| API key      | Server credential scoped to **that** organisation. See [Authentication](/authentication).  |
| Webhooks     | Signed events for **that** organisation only. See [Webhooks Overview](/webhooks/overview). |
| Paylinks     | Checkout URLs created in **that** organisation. See [Payment Links](/payments/paylinks).   |

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 BoomFi merchant. You can have your own organisation, keys, and settlement if you take payments for yourself.

Each merchant you acquire for is **also** a BoomFi merchant, with their own organisation. BoomFi does not model your PSP-to-merchant contract. When you create a paylink for one of them, you are calling the [Merchants API](/api/overview) **as that merchant**.

```text theme={null}
Your PSP  (a BoomFi merchant - you hold the keys)
    │
    ├── Merchant A  (a BoomFi merchant)
    │     API key A → paylinks, settlement, webhooks for A
    │
    └── Merchant B  (a BoomFi merchant)
          API key B → paylinks, settlement, webhooks for B
```

<Note>
  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.
</Note>

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](/payments/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](/pricing/networks-and-currencies)                                                                          |
| What does acceptance cost?                      | [Pricing and Fees](/pricing/fees-and-pricing)                                                                                        |
| Which countries or activities are out of scope? | [Unsupported Countries](/pricing/unsupported-countries), [Unsupported Business Activities](/pricing/unsupported-business-activities) |
| When is KYC/KYB required?                       | [Account Verification and Limits](/pricing/account-verification-limits) (paylinks mainly need [settlement](/settlement/overview))    |
| Uptime and support targets?                     | [Service Level Agreement](/pricing/service-level-agreement)                                                                          |

Need commercial terms? Contact [BoomFi support](https://help.boomfi.xyz).

## What you integrate

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

<CardGroup cols={3}>
  <Card title="Merchants API" href="/api/overview">
    REST at `https://mapi.boomfi.xyz/v1`. Start with [Authentication](/api/authentication) and [Response Patterns](/api/response-patterns). In the API reference, use **Paylinks**, **Payments**, **Events**, and **Organisation**.
  </Card>

  <Card title="Webhooks" href="/webhooks/overview">
    Signed events per organisation. [Configure](/webhooks/setup), [verify signatures](/webhooks/verify-signatures), then handle [event types](/webhooks/event-types) (start with `Payment.Updated`).
  </Card>

  <Card title="Paylinks and checkout" href="/payments/paylinks">
    Create links, [variant URLs](/payments/paylink-features#change-amount-and-currency), and send the customer to [hosted checkout](/payments/checkout).
  </Card>
</CardGroup>

## 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:

1. [API Overview](/api/overview) and [Authentication](/authentication): how you call the API
2. [Networks and Currencies](/pricing/networks-and-currencies) and [Settlement Overview](/settlement/overview): what that merchant can accept
3. [Webhooks Overview](/webhooks/overview), [Configure Webhooks](/webhooks/setup), [Verify Webhook Signatures](/webhooks/verify-signatures), [Event Types](/webhooks/event-types)
4. [Payments Overview](/payments/overview) and [Payment Links](/payments/paylinks): create, list, update, disable
5. [Paylink Features](/payments/paylink-features): prefill, `customer_ident`, redirects, **variant URLs**
6. [Checkout](/payments/checkout): hosted customer experience
7. [Cookbook: Sell a Product](/payments/cookbook-sell-product): one-off sale from create through webhook
8. [Cookbook: Recurring Billing](/payments/cookbook-recurring): 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:

1. [Create an Account](/create-account) for that merchant, or have them create one and give you API access.
2. Configure [settlement](/settlement/overview) for the [chains and assets](/pricing/networks-and-currencies) they accept. Dashboard: [Payments Settings](/dashboard/payments-settings).
3. Create an API key at `https://app.boomfi.xyz/dashboard/settings/api-keys`. See [Authentication](/authentication) and [API Authentication](/api/authentication).
4. Point that organisation's webhook URL at **your** PSP endpoint. See [Configure Webhooks](/webhooks/setup).

```bash theme={null}
curl -X PUT "https://mapi.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](/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](/webhooks/verify-signatures) for that organisation |

<Warning>
  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.
</Warning>

## 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](/payments/paylinks) and [Cookbook: Sell a Product](/payments/cookbook-sell-product) describe. Request and response schemas are in the API reference **Paylinks** group.

```bash theme={null}
curl -X POST "https://mapi.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](/payments/paylinks).

## 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](/payments/paylink-features#change-amount-and-currency) call a merchant uses (API reference → **Paylinks** → Generate Paylink Variant URL):

```bash theme={null}
curl "https://mapi.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](/payments/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](/payments/paylink-features).

## 5. Present checkout

Redirect the customer to the variant `data.url`, or to hosted checkout for the paylink (`https://pay.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](/webhooks/overview) and [Webhook Best Practices](/webhooks/best-practices) first.

Each merchant organisation signs deliveries with its own key pair. On each POST:

1. Select the merchant (URL path, or `org_id` used only to look up the public key).
2. Read raw body bytes and headers `X-BoomFi-Signature`, `X-BoomFi-Timestamp`.
3. [Verify the signature](/webhooks/verify-signatures) with **that organisation's** public key.
4. Confirm `org_id` matches the merchant you resolved.
5. 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](/webhooks/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://app.boomfi.xyz/dashboard/settings/api-keys?tab=webhooks`\
then retry or bulk replay. See [Event History and Replay](/webhooks/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:

```bash theme={null}
curl "https://mapi.boomfi.xyz/v1/payments" \
  -H "X-API-KEY: ${MERCHANT_API_KEY}"
```

Merchants can still open the [merchant dashboard](https://app.boomfi.xyz/login) to review their own [paylinks](/payments/paylinks) and [transactions](/dashboard/transactions). Your platform remains the system that creates links and updates payment state.

## Related

**API**

* [API Overview](/api/overview)
* [API Authentication](/api/authentication)
* [Response Patterns](/api/response-patterns)
* [Authentication](/authentication)

**Webhooks**

* [Webhooks Overview](/webhooks/overview)
* [Configure Webhooks](/webhooks/setup)
* [Verify Webhook Signatures](/webhooks/verify-signatures)
* [Event Types](/webhooks/event-types)
* [Event History and Replay](/webhooks/event-history-and-replay)
* [Webhook Best Practices](/webhooks/best-practices)

**Paylinks**

* [Payment Links](/payments/paylinks)
* [Paylink Features](/payments/paylink-features)
* [Checkout](/payments/checkout)
* [Cookbook: Sell a Product](/payments/cookbook-sell-product)
* [Account-Specific Paylinks](/payments/account-specific-paylinks)

**Policy and settlement**

* [Networks and Currencies](/pricing/networks-and-currencies)
* [Pricing and Fees](/pricing/fees-and-pricing)
* [Settlement Overview](/settlement/overview)
* [Payments Settings](/dashboard/payments-settings)