# Create Account Source: https://docs.boomfi.xyz/api-reference/accounts/create-account /openapi.yaml post /accounts Create a CryptoPayIn settlement account. Deprecated for payout destinations. # Delete Account Source: https://docs.boomfi.xyz/api-reference/accounts/delete-account /openapi.yaml delete /accounts/{accountId} Delete an account # Get Account Source: https://docs.boomfi.xyz/api-reference/accounts/get-account /openapi.yaml get /accounts/{accountId} Get a settlement account by ID # List Account Movements Source: https://docs.boomfi.xyz/api-reference/accounts/list-account-movements /openapi.yaml get /accounts/{accountId}/movement Paginated ledger history for one settlement account and its sub-accounts, newest first. The path accepts either the account id or the reference you gave it. Amounts are exact decimal strings. # List Accounts Source: https://docs.boomfi.xyz/api-reference/accounts/list-accounts /openapi.yaml get /accounts List settlement accounts for the organisation. Optional reference filter matches account.reference exactly. # Update Account Source: https://docs.boomfi.xyz/api-reference/accounts/update-account /openapi.yaml patch /accounts/{accountId} Update an account # Create Customer Source: https://docs.boomfi.xyz/api-reference/customers/create-customer /openapi.yaml post /customers Create a customer # Delete Customer Source: https://docs.boomfi.xyz/api-reference/customers/delete-customer /openapi.yaml delete /customers/{customerID} Delete customer # Get Customer Source: https://docs.boomfi.xyz/api-reference/customers/get-customer /openapi.yaml get /customers/{customerID} Get customer # List Customers Source: https://docs.boomfi.xyz/api-reference/customers/list-customers /openapi.yaml get /customers Retrieve a paginated list of customers for a given organisation, with optional sorting and filtering parameters # Update Customer Source: https://docs.boomfi.xyz/api-reference/customers/update-customer /openapi.yaml patch /customers/{customerID} Update customer fields. Only non-empty fields are applied. Returns the updated customer record (unwrapped). # List Events Source: https://docs.boomfi.xyz/api-reference/events/list-events /openapi.yaml get /events Retrieve a paginated list of events for a given organisation, with optional sorting and filtering parameters # Delete External Account Source: https://docs.boomfi.xyz/api-reference/external-accounts/delete-external-account /openapi.yaml delete /accounts/external-account/{accountId} Remove a payout destination. Payouts already in flight are unaffected; new payouts can no longer name it. # List External Accounts Source: https://docs.boomfi.xyz/api-reference/external-accounts/list-external-accounts /openapi.yaml get /accounts/external-account List the merchant's registered payout destinations. Bank details are returned as masked hints only. # Register External Account Source: https://docs.boomfi.xyz/api-reference/external-accounts/register-external-account /openapi.yaml post /accounts/external-account Register a payout destination the merchant controls: a wallet address (type Digital) or a bank account (type Fiat). Registering is the whitelisting step — /accounts/virtual/payout only sends to accounts created here — so this endpoint requires X-Step-Up-Token when authenticated with a Bearer session. # Get Invoice Source: https://docs.boomfi.xyz/api-reference/invoices/get-invoice /openapi.yaml get /invoices/{invoiceId} Get invoice by id or reference # List Invoices Source: https://docs.boomfi.xyz/api-reference/invoices/list-invoices /openapi.yaml get /invoices List invoices with optional customer, plan, and payment-type filters # Get Organisation Source: https://docs.boomfi.xyz/api-reference/organisation/get-organisation /openapi.yaml get /orgs Get the authenticated organisation's settings, including webhook public key when configured. # Update Display Currency Source: https://docs.boomfi.xyz/api-reference/organisation/update-display-currency /openapi.yaml post /orgs/currency/{currency_code} Set the organisation display/billing currency # Update Organisation Source: https://docs.boomfi.xyz/api-reference/organisation/update-organisation /openapi.yaml put /orgs Update organisation name, logo, webhook URL, fee payer, underpay tolerances, and email notification settings. # Create Balance Monitoring Source: https://docs.boomfi.xyz/api-reference/partner-balance-monitoring/create-balance-monitoring /openapi.yaml post /partners/accounts/id/{accountId}/automations/maintain-balance Create a maintain-balance automation for an account # Delete Balance Monitoring Source: https://docs.boomfi.xyz/api-reference/partner-balance-monitoring/delete-balance-monitoring /openapi.yaml delete /partners/accounts/id/{accountId}/automations/maintain-balance/{currency} Delete a maintain-balance automation for an account and currency # List Balance Monitoring Source: https://docs.boomfi.xyz/api-reference/partner-balance-monitoring/list-balance-monitoring /openapi.yaml get /partners/accounts/id/{accountId}/automations/maintain-balance List maintain-balance automations for an account # Update Balance Monitoring Source: https://docs.boomfi.xyz/api-reference/partner-balance-monitoring/update-balance-monitoring /openapi.yaml patch /partners/accounts/id/{accountId}/automations/maintain-balance Update a maintain-balance automation for an account # Create Pay-In Deposit Wallet Source: https://docs.boomfi.xyz/api-reference/partners/create-pay-in-deposit-wallet /openapi.yaml post /partners/accounts/{account_ref}/payin/address Create a permanent pay-in wallet for account. Deposit to this sub-account will be automatically swept to the parent account. Currency and deposit_splits are optional. # Create Payout Source: https://docs.boomfi.xyz/api-reference/partners/create-payout /openapi.yaml post /partners/accounts/{account_ref}/payout/address Create a payout to a crypto wallet address # Create Virtual Account Source: https://docs.boomfi.xyz/api-reference/partners/create-virtual-account /openapi.yaml post /partners/accounts/create-virtual-account Create virtual account with managed crypto wallets over supported networks # Get Account By ID Source: https://docs.boomfi.xyz/api-reference/partners/get-account-by-id /openapi.yaml get /partners/accounts/id/{accountId} Get account by ID # Get Account By Reference Source: https://docs.boomfi.xyz/api-reference/partners/get-account-by-reference /openapi.yaml get /partners/accounts/{account_ref} Get account by reference # Get Virtual Account Source: https://docs.boomfi.xyz/api-reference/partners/get-virtual-account /openapi.yaml get /partners/accounts/virtual-account Get a virtual account and its sub-accounts by reference # List Account Balances Source: https://docs.boomfi.xyz/api-reference/partners/list-account-balances /openapi.yaml get /partners/accounts/{account_ref}/balances List account balances by reference # List Deposit Account Balances Source: https://docs.boomfi.xyz/api-reference/partners/list-deposit-account-balances /openapi.yaml get /partners/accounts/{account_ref}/payin/{dep_account_ref}/balances List balances for a pay-in deposit wallet under a virtual account, aggregated per chain from succeeded Deposit/Payout payments. # Update Sub-Merchant Fees Source: https://docs.boomfi.xyz/api-reference/partners/update-sub-merchant-fees /openapi.yaml patch /partners/orgs/{orgId}/fees Change the fees on a merchant you onboarded. Send only the fees you want to move — anything omitted keeps its current value — and the response reports every fee on the merchant afterwards. partner_payment_rev_share_pct sets your own fee share for this one merchant, overriding your partner default; send it as null to remove the override. # Update Virtual Account Source: https://docs.boomfi.xyz/api-reference/partners/update-virtual-account /openapi.yaml patch /partners/accounts/update-virtual-account Update virtual account: add/enable chains with currencies, disable chains # Batch Delete Paylinks Source: https://docs.boomfi.xyz/api-reference/paylinks/batch-delete-paylinks /openapi.yaml delete /paylinks/batch Delete multiple paylinks in a single request # Batch Update Paylinks Source: https://docs.boomfi.xyz/api-reference/paylinks/batch-update-paylinks /openapi.yaml patch /paylinks/batch Update multiple paylinks in a single request # Create Paylink Source: https://docs.boomfi.xyz/api-reference/paylinks/create-paylink /openapi.yaml post /paylinks Create payment link. # Delete Paylink Source: https://docs.boomfi.xyz/api-reference/paylinks/delete-paylink /openapi.yaml delete /paylinks/{paylinkId} Soft-delete a payment link by ID # Generate Paylink Variant URL Source: https://docs.boomfi.xyz/api-reference/paylinks/generate-paylink-variant-url /openapi.yaml get /paylinks/generate-variant/{paylinkId} Generate a variant URL for a payment link # Get Paylink Source: https://docs.boomfi.xyz/api-reference/paylinks/get-paylink /openapi.yaml get /paylinks/{paylinkId} Retrieve a payment link by paylink ID or plan ID # List Paylinks Source: https://docs.boomfi.xyz/api-reference/paylinks/list-paylinks /openapi.yaml get /paylinks List paylinks with optional search and status filters # Update Paylink Source: https://docs.boomfi.xyz/api-reference/paylinks/update-paylink /openapi.yaml patch /paylinks/{paylinkId} Update a paylink's enabled status, metadata, or plan fields # Cancel Payment Source: https://docs.boomfi.xyz/api-reference/payments/cancel-payment /openapi.yaml delete /payments/{paymentId} Cancel a Processing ProxyWallet one-time payment with zero paid amount # Get Payment Source: https://docs.boomfi.xyz/api-reference/payments/get-payment /openapi.yaml get /payments/{paymentId} Get a payment by id. The payload matches the merchant webhook payment document, including nested customer, plan, invoice, and on-chain transactions when present. When status is RequiresAction, next_action contains a machine-readable code and content separated by the first colon. # List Payments Source: https://docs.boomfi.xyz/api-reference/payments/list-payments /openapi.yaml get /payments List payments with optional filters for invoice, customer, method, status, paylink, and plan. # Create Plan Source: https://docs.boomfi.xyz/api-reference/plans/create-plan /openapi.yaml post /plan Create plan. # Get Plan Source: https://docs.boomfi.xyz/api-reference/plans/get-plan /openapi.yaml get /plan/{planId} Get plan. # List Plans Source: https://docs.boomfi.xyz/api-reference/plans/list-plans /openapi.yaml get /plan List plans # Get Signing Secret Source: https://docs.boomfi.xyz/api-reference/secrets/get-signing-secret /openapi.yaml get /orgs/signing-secret Get the org request-signing secret (HMAC) # Rotate Signing Secret Source: https://docs.boomfi.xyz/api-reference/secrets/rotate-signing-secret /openapi.yaml patch /orgs/signing-secret Rotate the org request-signing secret and return the new value # Rotate Webhook Secret Source: https://docs.boomfi.xyz/api-reference/secrets/rotate-webhook-secret /openapi.yaml patch /orgs/webhook-secret Rotate the org webhook signing key pair and return the updated org # Cancel Subscription Source: https://docs.boomfi.xyz/api-reference/subscriptions/cancel-subscription /openapi.yaml delete /subscriptions/{subscriptionID} Cancel subscription # Create Subscription Invoice Source: https://docs.boomfi.xyz/api-reference/subscriptions/create-subscription-invoice /openapi.yaml post /subscriptions/{subscriptionID}/invoices Create an invoice for a subscription, or return the existing invoice with the same due date. # List Subscriptions Source: https://docs.boomfi.xyz/api-reference/subscriptions/list-subscriptions /openapi.yaml get /subscriptions List subscriptions with optional status and customer filters # List Subscriptions By Customer Source: https://docs.boomfi.xyz/api-reference/subscriptions/list-subscriptions-by-customer /openapi.yaml get /subscriptions/{customerID} List subscriptions for a customer belonging to the authenticated org # Create Pay-In Deposit Wallet Source: https://docs.boomfi.xyz/api-reference/virtual-accounts/create-pay-in-deposit-wallet /openapi.yaml post /accounts/virtual/payin/address Create a permanent pay-in wallet under the merchant's virtual account. Deposits to this sub-account are automatically swept to the parent account. # Create Payout Source: https://docs.boomfi.xyz/api-reference/virtual-accounts/create-payout /openapi.yaml post /accounts/virtual/payout/address Create a payout to a crypto wallet address. Requires request signature headers. When authenticated with a Bearer session, also requires X-Step-Up-Token. # Create Virtual Account Source: https://docs.boomfi.xyz/api-reference/virtual-accounts/create-virtual-account /openapi.yaml post /accounts/virtual Create the org's managed virtual account with crypto wallets on supported networks # Create Virtual Account Payout Source: https://docs.boomfi.xyz/api-reference/virtual-accounts/create-virtual-account-payout /openapi.yaml post /accounts/virtual/payout Create a payout from the managed virtual account to a registered destination account, identified by id or by the merchant's own reference. The destination must be enabled; enabling it is the step-up-protected operation, so this call needs no per-request step-up token. A fiat currency settles to the destination bank account, a digital one to its wallet address and requires chain_id. # Get Virtual Account Source: https://docs.boomfi.xyz/api-reference/virtual-accounts/get-virtual-account /openapi.yaml get /accounts/virtual Get the org's primary virtual account (empty reference) with crypto sub-accounts # List Virtual Account Balances Source: https://docs.boomfi.xyz/api-reference/virtual-accounts/list-virtual-account-balances /openapi.yaml get /accounts/virtual/balances List balances across the org's primary virtual account hierarchy # Update Virtual Account Source: https://docs.boomfi.xyz/api-reference/virtual-accounts/update-virtual-account /openapi.yaml patch /accounts/virtual Update virtual account: add/enable chains with currencies, disable chains # Authentication Source: https://docs.boomfi.xyz/api/authentication Authenticate Merchants API requests with an API key and optional request signatures. The Merchants API authenticates requests with an **API key**. Send the key on every request in the `X-API-KEY` header (OpenAPI security scheme `ApiKeyAuth`). Some write endpoints also require **HMAC request signing** (`X-API-Nonce` and `X-API-Signature`). Those requirements are declared per operation in the interactive API reference. ## Create an API key 1. Open the merchant dashboard and go to **Settings → API & Webhook → API Keys**: `https://app.boomfi.xyz/dashboard/settings/api-keys` 2. Create a new key. 3. Copy the secret immediately and store it in a secrets manager. BoomFi shows the full API key **once** at creation and cannot recover a lost key. Rotate (create a new key and revoke the old one) if it is leaked. ## Send the key ```bash theme={null} curl "https://mapi.boomfi.xyz/v1/orgs" \ -H "X-API-KEY: sk_test_xxx" \ -H "Accept: application/json" ``` Keep keys out of client-side code, public repos, logs, and screenshots. ## Request signing (when required) Permanent pay-in address creation and crypto payouts require HMAC request signing in addition to the API key. Other writes may only need `X-API-KEY`: check each operation in the API reference for `ApiNonce` / `ApiSignature`. | Header | Purpose | | ----------------- | -------------------------------------------- | | `X-API-KEY` | API key | | `X-API-Nonce` | Unique value per request (replay protection) | | `X-API-Signature` | Hex-encoded HMAC-SHA256 of the request | How the signature is built, how to fetch the signing secret, and a code sample are documented in the full guide: [Authentication](/authentication). ## Webhook verification is separate Inbound webhooks use an **asymmetric** public key for payload verification: not the API key and not the HMAC request-signing secret. See [Verify Webhook Signatures](/webhooks/verify-signatures). ## Next * [Response Patterns](/api/response-patterns) * [API Overview](/api/overview) # API Overview Source: https://docs.boomfi.xyz/api/overview How the Merchants REST API is structured and what you need before calling it. The Merchants API is a REST interface over HTTPS. Request and response bodies use JSON. Use standard HTTP methods (`GET`, `POST`, `PUT`, `PATCH`, `DELETE`). Base URL: ``` https://mapi.boomfi.xyz/v1 ``` ## Initial setup 1. Create or join an organisation in the [merchant dashboard](https://app.boomfi.xyz/login). 2. Configure [Settlement Overview](/settlement/overview) so collections can complete. 3. Create an API key. See [Authentication](/api/authentication). For a first end-to-end call, follow the [Quickstart](/quickstart). ## Guides API keys (`X-API-KEY`) and when HMAC request signing is required. Success envelopes, paginated lists, errors, and common HTTP status codes. ## Endpoint groups The API reference groups operations by product area: | Area | Use for | | -------------------------------- | --------------------------------------------------------------- | | Paylinks | Create and manage payment links and variants | | Plans / Subscriptions / Invoices | Recurring products and subscription billing | | Customers | Customer records linked to payments | | Payments | List and inspect payment transactions | | Events | Delivery history for organisation events | | Organisation / Secrets | Org profile, API and signing secrets | | Accounts | Settlement accounts | | Virtual Accounts | Deposit accounts, permanent pay-in addresses, balances, payouts | | Partners | Multi-merchant partner workflows | Interactive request samples and schemas are on each endpoint page in the groups that follow. ## Related * [Introduction](/introduction) * [Authentication](/authentication) * [Create an Account](/create-account) * [Webhooks Overview](/webhooks/overview) # Response Patterns Source: https://docs.boomfi.xyz/api/response-patterns Standard success, pagination, and error envelopes for the Merchants API. Successful Merchants API responses use a consistent JSON envelope. List endpoints add pagination fields under `data`. Errors use a dedicated error object. ## Single-item response When an endpoint returns one resource, the body looks like: ```json theme={null} { "data": { } } ``` Optional fields on some success responses: * `error`: boolean, set when the request failed (normally omitted on success) * `message`: human-readable status text when present ## Paginated response List endpoints wrap a page of results: ```json theme={null} { "data": { "items": [{ }, { }], "next": 2, "total": 10, "last_update": "2021-01-01T00:00:00Z" } } ``` | Field | Meaning | | ------------------ | ---------------------------------------------------------------------- | | `data.items` | Resources on the current page | | `data.next` | Next page number when more results exist | | `data.total` | Total matching items across all pages | | `data.last_update` | Timestamp of the most recently updated item in the set, when available | Common list query parameters (when supported by the endpoint): | Parameter | Meaning | | ----------------- | ---------------------------------------- | | `page` | 1-based page number (default 1) | | `limit` | Page size (default 100, maximum 100) | | `since` / `until` | Inclusive `created_at` bounds (RFC3339) | | `sort` | `asc` or `desc` for the primary sort key | Exact parameters differ per endpoint: see each operation in the interactive reference. ## Error response Failed requests return an error envelope: ```json theme={null} { "error": { "code": 400, "message": "Insufficient quantity", "errors": [ { "domain": "orders", "reason": "InsufficientQuantity" } ] } } ``` | Field | Meaning | | --------------- | ---------------------------------------------------------- | | `error.code` | Application / HTTP-style error code | | `error.message` | Primary human-readable message | | `error.errors` | Optional list of more specific `domain` / `reason` entries | ## HTTP status codes | Range | Meaning | | ------- | --------------------------------------------------- | | **2xx** | Success | | **4xx** | Client error (invalid input, auth, not found, etc.) | | **5xx** | Server or upstream failure | Treat non-2xx responses as failures even if a body is present. Prefer handling by status code and `error.code` / `error.message` rather than string matching alone. ## Next * [Authentication](/api/authentication) * [API Overview](/api/overview) # Authentication Source: https://docs.boomfi.xyz/authentication API keys, request signing secrets, and how secured Merchants API calls work. The Merchants API authenticates server requests with an API key. Sensitive write endpoints that manage virtual accounts, deposits, and payouts also require request-level HMAC signatures. ## API keys Create and revoke keys in **Settings → API & Webhook → API Keys**: `https://app.boomfi.xyz/dashboard/settings/api-keys` BoomFi API keys settings The full secret is shown **once** when the key is created. Store it in a secrets manager. BoomFi cannot recover a lost key: rotate (create a new key and revoke the old one) if it is compromised. Send the key on every request: ```bash theme={null} curl "https://mapi.boomfi.xyz/v1/orgs" \ -H "X-API-KEY: sk_test_xxx" \ -H "Accept: application/json" ``` ### Best practices * Never commit keys to source control or ship them in browser code * Prefer separate keys per environment and service * Rotate keys on a schedule and after personnel changes ## Request signing (HMAC) Some endpoints declare authentication as **API key + nonce + signature**. Those include permanent pay-in addresses and payouts. Creating or updating a virtual account itself is API-key only unless the operation schema says otherwise. Required headers when signature verification is enforced: | Header | Value | | ----------------- | --------------------------------------------- | | `X-API-KEY` | Your API key | | `X-API-Nonce` | Unique string per request (replay protection) | | `X-API-Signature` | Hex-encoded HMAC-SHA256 (see below) | Retrieve or rotate the org **request-signing secret** (HMAC secret for API calls, not the webhook key pair): ```bash theme={null} # Get signing secret curl "https://mapi.boomfi.xyz/v1/orgs/signing-secret" \ -H "X-API-KEY: sk_test_xxx" # Rotate signing secret curl -X PATCH "https://mapi.boomfi.xyz/v1/orgs/signing-secret" \ -H "X-API-KEY: sk_test_xxx" ``` ### How the signature is computed The message is the concatenation of: ``` HTTP_METHOD + URL_PATH + NONCE + QUERY_STRING + RAW_BODY ``` Examples: * `POST` + `/v1/accounts/virtual/payin/address` + `nonce-abc` + \`\` + `{"chain_id":8453,"reference":"customer-123"}` * Query string is the raw query without `?` (empty when none) Then: ```text theme={null} X-API-Signature = hex(HMAC_SHA256(signing_secret, message)) ``` Each nonce may be used once per organisation (recent nonces are rejected as reuse). ```javascript theme={null} import crypto from "crypto"; function signRequest({ method, path, // e.g. "/v1/accounts/virtual/payin/address" nonce, query = "", body = "", signingSecret, }) { const message = `${method}${path}${nonce}${query}${body}`; return crypto .createHmac("sha256", signingSecret) .update(message) .digest("hex"); } ``` `/v1/orgs/signing-secret` is exempt from request signature checks so you can obtain a secret on first run when signing is enforced. ## Webhook public key (different secret) Webhook verification uses an **asymmetric RSA key pair** (public key in the dashboard). Do not use the HMAC request-signing secret to verify webhooks. See [Verify Webhook Signatures](/webhooks/verify-signatures). ## Next steps * [Quickstart](/quickstart) * [Settlement Overview](/settlement/overview) * [Configure Webhooks](/webhooks/setup) # Choose Your Integration Source: https://docs.boomfi.xyz/choose-integration Decide between checkout paylinks, subscriptions, and permanent deposit accounts. Pick the money-in path that matches your product. You use the same organisation, API keys, settlement, and webhooks either way. ## Decision guide | If you… | Use | | ----------------------------------------------------------------- | ------------------------------------------------------------------ | | Sell a fixed-price product or invoice | [Payments Overview](/payments/overview) | | Bill on a schedule (membership, SaaS) | [Subscriptions](/payments/subscriptions) | | Maintain a **user balance** (deposits of any amount over time) | [Deposit Accounts Overview](/deposits/overview) | | Are a PSP or acquirer (you and your merchants are both merchants) | [Cookbook: Offer Crypto as a PSP](/payments/cookbook-psp-paylinks) | ## Payment links and checkout * Customer pays a **known amount** for goods or services * You share a link or redirect to hosted checkout * You fulfill when you receive a successful payment webhook Start with [Cookbook: Sell a Product](/payments/cookbook-sell-product). If you create those links for merchants on your PSP, use [Cookbook: Offer Crypto as a PSP](/payments/cookbook-psp-paylinks). ## Subscriptions * Create a **recurring** plan / paylink * Customer renews on interval; invoices may open and become overdue * Handle `Subscription.*` and `Invoice.*` events Start with [Subscriptions](/payments/subscriptions) and [Cookbook: Recurring Billing](/payments/cookbook-recurring). ## Deposit accounts * Issue a **permanent crypto address** per user (`reference` = your user id) * Deposits are swept to your parent virtual account * Credit your ledger only after verified payment events Start with [Cookbook: User Balance Deposits](/deposits/cookbook-user-balance) and [Create a Deposit Address](/deposits/create-address). ## Platform integrations If you already bill in Stripe, Chargebee, or WooCommerce, add crypto pay links via [Integrations Overview](/integrations/overview). ## PSP / acquirer * You are a BoomFi merchant; each merchant on your platform is also a merchant * You hold their API keys and run the [paylink flow](/payments/paylinks) on their behalf * Use [variant URLs](/payments/paylink-features#change-amount-and-currency) when the amount or currency changes per invoice Start with [Cookbook: Offer Crypto as a PSP](/payments/cookbook-psp-paylinks). One organisation with many settlement wallets is [Account-Specific Paylinks](/payments/account-specific-paylinks). Only accept assets and networks enabled for your settlement / virtual account. Funds sent on the wrong network or with an unsupported token may not be credited. See [Networks and Currencies](/pricing/networks-and-currencies) and [Pricing and Fees](/pricing/fees-and-pricing) (including recovery fees when recovery is possible). ## Shared setup checklist Before go-live on any path: * [ ] API key stored securely * [ ] Settlement / virtual account configured * [ ] Webhook URL set and [Verify Webhook Signatures](/webhooks/verify-signatures) implemented * [ ] Event history reviewed under API & Webhook → Webhooks * [ ] Dashboard [Payments Settings](/dashboard/payments-settings) matches production wallets * [ ] Third-party integrations configured if you use them ([Integrations Overview](/integrations/overview)) # Create an Account Source: https://docs.boomfi.xyz/create-account Sign up, create your organisation, and prepare the merchant dashboard. Before you call the API, create a merchant organisation in the dashboard and complete business settings. ## Sign in Open [https://app.boomfi.xyz/login](https://app.boomfi.xyz/login) and sign in with your work email (or passkey, when enabled). BoomFi sign-in page ## Sign up 1. Open [https://app.boomfi.xyz/login](https://app.boomfi.xyz/login). 2. Create a user account with a work email. 3. Complete organisation details (business name and related fields). BoomFi create-account page ## Business settings In **Settings → Business** (`https://app.boomfi.xyz/dashboard/settings/merchant`): * Confirm organisation profile and logo * Set your **webhook URL** (HTTPS endpoint) when you are ready to receive events * View or rotate the **webhook public key** used to verify signed deliveries See [Configure Webhooks](/webhooks/setup). BoomFi business webhook settings ## Team (optional) Invite colleagues under **Settings → Team** (`https://app.boomfi.xyz/dashboard/settings/members`). Owner and permission roles control access to API keys and event replay. ## Verification (when required) Some products (for example OTC) require KYC/KYB. Use **Settings → Verification** when prompted. See [Account Verification and Limits](/pricing/account-verification-limits). Payment-gateway acceptance of crypto paylinks primarily depends on settlement configuration. ## Next steps 1. [Authentication](/authentication) 2. [Settlement Overview](/settlement/overview) 3. [Configure Webhooks](/webhooks/setup) 4. [Choose Your Integration](/choose-integration) # Business Settings Source: https://docs.boomfi.xyz/dashboard/business Organisation profile, webhook endpoint, and public key for BoomFi. Use **Settings → Business** to manage organisation identity and the HTTPS endpoint that receives signed webhook deliveries. Open: `https://app.boomfi.xyz/dashboard/settings/merchant` BoomFi business settings ## Organisation profile Fields include: * Legal or display name * Logo used on hosted checkout where supported * Support or contact details as shown in the form Save after each change. Incomplete org details can block downstream products that require KYB. ## Webhook URL Enter the **HTTPS URL** of your application that will receive `POST` events. BoomFi signs each delivery so you can verify authenticity. * Configuration steps: [Configure Webhooks](/webhooks/setup) * Signature verification: [Verify Webhook Signatures](/webhooks/verify-signatures) * Event catalogue: [Event Types](/webhooks/event-types) BoomFi business webhook settings ## Webhook public key The business settings page shows the **webhook public key** used to verify signed deliveries. Header names and verification steps are documented in [Verify Webhook Signatures](/webhooks/verify-signatures). Rotate by regenerating keys only when your receiver is ready to accept the new public material. ## Next steps 1. [Team and Roles](/dashboard/team) 2. [Payments Settings](/dashboard/payments-settings) 3. [Authentication](/authentication) # Customer Portal Source: https://docs.boomfi.xyz/dashboard/customer-portal How end customers view transactions and manage subscriptions. The customer portal is where **your customers** (not merchants) view their transactions and manage subscriptions. ## Access Share the portal URL with your customers (your organisation receives it during onboarding). Attach customers to payments with `customer_ident` on pay links: see [Paylink Features](/payments/paylink-features). Contact [support](https://help.boomfi.xyz) if you need the portal URL for your organisation. ## Transactions Customers can: * Switch between **recurring** and **one-time** history * Review dates, descriptions, and amounts * **Download receipts** ## Subscriptions Where subscriptions are active, customers can: * View type, billing cycle, and next payment date * Cancel a subscription Merchant-side control stays in the dashboard under subscriptions and pay links. See [Subscriptions](/payments/subscriptions). # Customers Source: https://docs.boomfi.xyz/dashboard/customers Manage payers linked to wallets and paylinks, including manual registration. The **Customers** section is the hub for everyone who has paid or been registered against your organisation: whether or not a payment succeeded. Open: `https://app.boomfi.xyz/dashboard/customers` BoomFi customers list ## Automatic registration When a new customer completes a pay link payment, BoomFi creates or updates a customer record. Required fields are filled automatically; optional identity fields depend on what you collect at checkout. ## Tracking by wallet Customer interaction history is often correlated with **wallet addresses**. Paying from a known address attaches activity to that customer profile. ## Manual registration Use **Add customer** and provide at least a **name** and unique **wallet address**. Optional fields include: * Email * Personal address * Phone number * Unique customer identifier (your external id) * Social handles where the form supports them BoomFi add customer ## Permissions Creating, editing, and deleting customers requires Member or higher; Accountants can view and export only. See [Team and Roles](/dashboard/team). ## Related * [Customer Portal](/dashboard/customer-portal) * [Transactions](/dashboard/transactions) * [Paylink Features](/payments/paylink-features) (`customer_ident`) # Merchant Dashboard Overview Source: https://docs.boomfi.xyz/dashboard/overview Navigate Settings, payments, customers, and integrations in the BoomFi merchant dashboard. The merchant dashboard is where you configure settlement and business settings, create payment links, review transactions and customers, manage API keys and webhooks, and connect billing integrations. ## Main areas | Area | Path | Purpose | | ------------------- | -------------------------------------------------------- | ---------------------------------------------- | | Home / account | `https://app.boomfi.xyz/dashboard` | Overview and balance-oriented actions | | Pay links | `https://app.boomfi.xyz/dashboard/pay-links` | Create and manage payment links | | Transactions | `https://app.boomfi.xyz/dashboard/transactions` | Payment history, filters, receipts | | Customers | `https://app.boomfi.xyz/dashboard/customers` | Customers attached to payments | | Settlement (crypto) | `https://app.boomfi.xyz/dashboard/settings/settlement` | Chains, settlement addresses, underpayment | | Business | `https://app.boomfi.xyz/dashboard/settings/merchant` | Org profile, webhook URL and public key | | Team | `https://app.boomfi.xyz/dashboard/settings/members` | Invites and roles | | API keys | `https://app.boomfi.xyz/dashboard/settings/api-keys` | Keys and webhook / signing secrets | | Verification | `https://app.boomfi.xyz/dashboard/settings/verification` | KYC/KYB when required for higher-risk products | BoomFi dashboard home ## Guides * [Business Settings](/dashboard/business) * [Team and Roles](/dashboard/team) * [Payments Settings](/dashboard/payments-settings) * [Transactions](/dashboard/transactions) * [Customers](/dashboard/customers) * [Customer Portal](/dashboard/customer-portal) ## Related setup * [Create an Account](/create-account) * [Settlement Overview](/settlement/overview) * [Authentication](/authentication) * [Webhooks Overview](/webhooks/overview) # Payments Settings Source: https://docs.boomfi.xyz/dashboard/payments-settings Configure crypto settlement chains and underpayment tolerance. Open **Settings → Payments / Settlement** to configure how crypto payments settle and how far underpaid invoices can still complete. `https://app.boomfi.xyz/dashboard/settings/settlement` BoomFi settlement settings ## Crypto settlements For each supported blockchain you enable: 1. Toggle the network on 2. Set the **settlement address** for that chain 3. Select the **currencies** you accept on that chain 4. Save See also [Settlement Accounts](/settlement/settlement-accounts) and [Networks and Currencies](/pricing/networks-and-currencies). BoomFi crypto settlement settings ## Underpayments Underpayment settings define how much shortfall you accept at checkout when a customer pays less than the invoice amount. | Setting | Meaning | | ------------------------------------- | ------------------------------------------------------------------- | | Acceptable underpayment percentage | Relative tolerance (for example 1% of a $100 invoice → accept $99+) | | Maximum allowable underpayment amount | Hard USD (or stable-unit) cap on the shortfall | ### Combining percentage and amount If both are set, the **percentage** tolerance applies, and the **fixed amount** acts as a **hard cap**. Example with **1%** and **\$5**: * $100 invoice → accept about $99 and above * $1,000 invoice → $995 and above (1% = $10, but the $5 cap wins) BoomFi underpayment settings ### Field names (API / config) ```typescript theme={null} interface UnderpayThresholds { underpay_tolerance_percent?: number; // acceptable underpayment percentage underpay_tolerance_usd?: number; // maximum allowable underpayment amount } ``` ## Related * [Settlement Overview](/settlement/overview) * [Payment Links](/payments/paylinks) # Team and Roles Source: https://docs.boomfi.xyz/dashboard/team Invite teammates and understand Owner, Admin, Member, and Accountant permissions. In **Settings → Team**, invite colleagues by email and assign a role. Open: `https://app.boomfi.xyz/dashboard/settings/members` BoomFi team settings ## Role summary * **Owner**: full organisation control, including delete and organisation-level settings * **Admin**: full management of team, funds transfer, API keys, settlement, and webhooks (except organisation delete) * **Member**: create and manage pay links, view/export customers and transactions, refunds and cancellations * **Accountant**: view and export customers and transaction data only ## Invite a teammate 1. Open the Team page 2. Click **Add user** (or equivalent) 3. Enter work email and choose a role 4. Send the invite BoomFi team invite ## Permission matrix | Permission | Owner | Admin | Member | Accountant | | ---------------------------- | :---: | :---: | :----: | :--------: | | View dashboard | Yes | Yes | Yes | Yes | | View transactions | Yes | Yes | Yes | Yes | | Export transactions | Yes | Yes | Yes | Yes | | View customers | Yes | Yes | Yes | Yes | | Export customers | Yes | Yes | Yes | Yes | | Create customers | Yes | Yes | Yes | No | | Edit customers | Yes | Yes | Yes | No | | Delete customers | Yes | Yes | Yes | No | | View paylinks | Yes | Yes | Yes | No | | Create paylinks | Yes | Yes | Yes | No | | Edit paylinks | Yes | Yes | Yes | No | | Initiate refunds | Yes | Yes | Yes | No | | Cancel payments | Yes | Yes | Yes | No | | Manage team members | Yes | Yes | No | No | | Manage integrations | Yes | Yes | No | No | | Manage API keys | Yes | Yes | No | No | | Manage settlement accounts | Yes | Yes | No | No | | Edit business settings | Yes | Yes | No | No | | View webhook configuration | Yes | Yes | No | No | | Manage webhook configuration | Yes | Yes | No | No | | Transfer funds | Yes | Yes | No | No | | Manage organisation settings | Yes | No | No | No | | Delete organisation | Yes | No | No | No | # Transactions Source: https://docs.boomfi.xyz/dashboard/transactions View, filter, and export payments; open explorer details and download receipts. The **Transactions** list is a filterable ledger of payments in the merchant dashboard. Open: `https://app.boomfi.xyz/dashboard/transactions` BoomFi transactions list ## Status and filters Filter by status, date, customer, pay link, or network. Use export when you need a CSV for finance or reconciliation. ## Row actions For each transaction you can: | Action | What it does | | -------------------------- | --------------------------------------------------- | | Customer details | Open the customer profile (name, wallet, history) | | Transaction details / hash | Follow the chain hash to a block explorer | | Download receipt | PDF (or equivalent) receipt for bookkeeping and tax | BoomFi transaction detail ### Customer details Select the customer name or wallet address on the row to open their [customer](/dashboard/customers) profile, including history and subscriptions where present. ### On-chain details Use the **transaction hash** link to open the chain explorer for confirmation and fee data outside BoomFi. ### Receipt Download receipt for: * Bookkeeping and audits * Proof of payment between parties * Tax records ## API List and retrieve payments via the Payments API using [https://mapi.boomfi.xyz/v1](https://mapi.boomfi.xyz/v1) and your merchant API key. After a successful checkout, redirect flows can include a `pid` payment id: see [Paylink Features](/payments/paylink-features). ## Related * [Customers](/dashboard/customers) * [Webhooks Overview](/webhooks/overview) * [Checkout](/payments/checkout) # Cookbook: User Balance Deposits Source: https://docs.boomfi.xyz/deposits/cookbook-user-balance Map users to permanent deposit addresses and credit balances from verified events. ## Goal Each end user has a durable deposit address. When they send crypto, you credit their in-app balance after BoomFi confirms the payment via signed webhooks. ## 1. Foundation 1. [Create virtual account](/settlement/virtual-accounts) with chains/currencies you support 2. Store API key + request signing secret 3. Implement [webhook signature verification](/webhooks/verify-signatures) ## 2. On user signup Generate a deposit address for each chain you show in the UI: ```bash theme={null} curl -X POST "https://mapi.boomfi.xyz/v1/accounts/virtual/payin/address" \ -H "X-API-KEY: sk_test_xxx" \ -H "Content-Type: application/json" \ -H "X-API-Nonce: ${NONCE}" \ -H "X-API-Signature: ${SIG}" \ -d "{\"chain_id\": 8453, \"reference\": \"user_${INTERNAL_USER_ID}\"}" ``` Save `address` → `user_id` → `chain_id` in your database. ## 3. Wallet UI * Show address (and QR) only for the selected network * Copy labels from [Networks and Currencies](/pricing/networks-and-currencies) * Warn that wrong-chain or wrong-token transfers may be unrecoverable ## 4. Webhook credit rule On verified `Payment.Updated` (or related payment event) with a successful status: 1. Map payment customer / reference back to your user 2. Idempotently apply ledger credit by payment id 3. Optionally notify the user Never credit solely because funds appear on-chain without a platform payment event. ## 5. Balances and ops * Merchant balances: `GET https://mapi.boomfi.xyz/v1/accounts/virtual/balances` * Dashboard: `https://app.boomfi.xyz/dashboard/account` and transactions * Failed webhooks: [Event History and Replay](/webhooks/event-history-and-replay) ## 6. Withdrawals / payouts (optional) If users can cash out, use the virtual-account payout API (`POST /accounts/virtual/payout/address` with request signing) and apply your own risk controls. # Create a Deposit Address Source: https://docs.boomfi.xyz/deposits/create-address Create a permanent pay-in crypto wallet for a customer reference. `POST /accounts/virtual/payin/address` creates a permanent pay-in wallet under the merchant’s virtual account. Deposits are swept to the parent account. ## Request Requires API key and request signature when signature verification is enforced. ```bash theme={null} curl -X POST "https://mapi.boomfi.xyz/v1/accounts/virtual/payin/address" \ -H "X-API-KEY: sk_test_xxx" \ -H "Content-Type: application/json" \ -H "X-API-Nonce: nonce-unique-1" \ -H "X-API-Signature: " \ -d '{ "chain_id": 8453, "reference": "customer-123" }' ``` ### Fields | Field | Required | Description | | ----------- | -------- | ----------------------------------------------------------------------------------------------------------------- | | `reference` | Yes | Your stable user/customer id for this sub-account | | `chain_id` | Yes | Chain id (for example `8453` Base, `1` Ethereum). See [Networks and Currencies](/pricing/networks-and-currencies) | The parent virtual account must exist, be enabled, and in **Ready** state. The chain must be enabled on the platform. ## Response (shape) | Field | Description | | ------------ | --------------------------------- | | `account_id` | Sub-account id | | `reference` | Echo of your reference | | `chain_id` | Chain | | `address` | On-chain address to show the user | | `status` | Account state | | `enabled` | Whether deposits are enabled | Persist `address` and `account_id` next to your user record. Creating again for the same reference/chain returns the existing wallet when already provisioned (idempotent behaviour from the account store). ## Request signing Build `X-API-Signature` as described in [Authentication](/authentication): `HMAC_SHA256(secret, METHOD + PATH + NONCE + QUERY + BODY)`. ## Show address to users Display the address only for the **chosen chain**. Educate users not to send assets from incompatible networks. ## Credit your ledger Watch for payment webhooks involving deposit payment methods / successful payments tied to that customer, and verify signatures. Prefer a conservative rule: **credit only on successful, verified payment events** that match your `reference` / customer mapping. ## Next step [Cookbook: User Balance Deposits](/deposits/cookbook-user-balance) # Deposit Accounts Overview Source: https://docs.boomfi.xyz/deposits/overview Permanent crypto deposit addresses for user balances with automatic sweep to your virtual account. Deposit accounts are permanent pay-in wallets under your organisation’s [Virtual Accounts](/settlement/virtual-accounts). Use them when each user holds a **balance** and can top up any amount over time (iGaming, prepaid wallets, account funding). ## How it works 1. You create or ensure a **Ready** primary virtual account 2. For each user, call create pay-in address with `reference` = your user id and a `chain_id` 3. Show the address (and memo/tag when the chain requires one) 4. Deposits to that sub-account are **automatically swept** to the parent virtual account 5. You credit the user’s balance only after verified webhooks / payment events ## When not to use deposits For a single fixed charge for a product, use [Payments Overview](/payments/overview) instead. ## Prerequisites * Virtual account created and ready ([Virtual Accounts](/settlement/virtual-accounts)) * [Authentication](/authentication) for pay-in address creation * [Verify Webhook Signatures](/webhooks/verify-signatures) ## Asset and network safety Only instruct users to send assets that are **enabled on the chain you requested** for that deposit wallet. Transfers of wrong tokens, wrong networks, or assets outside your virtual-account configuration may not be detected or credited. Review [Networks and Currencies](/pricing/networks-and-currencies). When recovery is possible, [pricing](/pricing/fees-and-pricing) describes payment recovery fees. Supported deposit-wallet namespaces (merchant pay-in API) are EVM, Solana, Tron, and Bitcoin. TON and Celo deposit wallets are rejected by the API. ## Partner APIs Platform partners can create virtual accounts and deposit wallets under `/partners/accounts/...`. Merchant guides focus on `/accounts/virtual/...`. See the API reference Partners tags if you integrate as a partner. ## Next steps * [Create a Deposit Address](/deposits/create-address) * [Cookbook: User Balance Deposits](/deposits/cookbook-user-balance) # Chargebee Source: https://docs.boomfi.xyz/integrations/chargebee Add BoomFi crypto paylinks to Chargebee invoices and subscriptions. Connect [Chargebee](https://www.chargebee.com/) so invoices can include a BoomFi cryptocurrency pay link. ## Auto charge BoomFi does **not** auto-charge crypto. Use wallet / pay link flows for collection. For automatic crypto charging, create an appropriate pay link in the [dashboard](https://app.boomfi.xyz/login) and complete the customer wallet consent path where required. ## Enable the integration ### Chargebee API key 1. In Chargebee: **Settings → Configure Chargebee → API keys → Add API key**. 2. Choose a **full-access** key covering the resources you need. 3. Name it (for example “BoomFi integration”) and create the key. Store it securely. ### Connect in BoomFi 1. Open the merchant dashboard. 2. Go to **Settings → Integration**, find **Chargebee**, **Connect**. 3. Enter your **Chargebee site / domain** and the API key. 4. Confirm **Connect**. Copy the **webhook URL** shown after connect for the next step. ## Webhooks Chargebee can poll/sync on an interval. For near real-time updates, add a webhook: 1. Chargebee **Settings → Configure Chargebee → Webhooks → Add webhook**. 2. Name it and set the URL in this form: ```text theme={null} https://mapi.boomfi.xyz/v1/integrations/webhook/Chargebee/ ``` Use the exact URL provided in the BoomFi integration UI if it differs slightly from the pattern above. 3. Turn **off** basic-auth protection, primary-flag-only behaviour, and card data exclusion as directed in the product UI for this integration. 4. Send **all events** (or the set required by support). 5. Create the webhook. ## Custom fields (recommended) Provision Chargebee custom fields so crypto metadata is searchable and mergeable. Field keys below use the published integration names: ### Customer | Field name | Type | Label | | -------------------------- | ---------------- | -------------- | | `cf_boomfi_wallet_address` | Single line text | Wallet address | ### Charge / plan price | Field name | Type | Label | | --------------------------- | ---------------- | -------- | | `cf_boomfi_payment_network` | Single line text | Network | | `cf_boomfi_amount` | Single line text | Amount | | `cf_boomfi_currency` | Single line text | Currency | | `cf_boomfi_paylink` | URL | Paylink | Fields are not all strictly required, but provisioning the full set gives the best reporting experience. See Chargebee’s custom field docs for setup. ## Test a payment 1. Complete a test payment on a pay link in the correct environment. 2. Open **Invoices** in Chargebee and confirm payment details landed. ## Subscriptions When creating Chargebee subscriptions that use BoomFi: 1. Ensure the integration is connected. 2. Create products/plans and customers in Chargebee as usual. 3. Avoid auto-charge modes that only apply to card. 4. Confirm invoices show the crypto pay link metadata after sync. Contact [support](https://help.boomfi.xyz) if invoice pay links do not appear after connection. ## Related * [Integrations Overview](/integrations/overview) * [Payment Links](/payments/paylinks) # Integrations Overview Source: https://docs.boomfi.xyz/integrations/overview Connect BoomFi crypto checkout to billing platforms and storefronts. BoomFi can attach cryptocurrency payment links to invoices and checkouts from common platforms. Configure an API key and Integration settings in the merchant dashboard, then finish setup in the third-party product. BoomFi integrations settings ## Available guides | Integration | Use case | | ---------------------------------------------- | -------------------------------------------------- | | [Stripe Billing](/integrations/stripe-billing) | Crypto paylinks on Stripe invoices / subscriptions | | [Chargebee](/integrations/chargebee) | Crypto paylinks on Chargebee invoices | | [WooCommerce](/integrations/woocommerce) | WordPress store crypto payment method | ## Shared constraints * **No auto-charge for crypto**: invoice / subscription products that rely on automatic card capture are out of scope. Customers pay through a pay link (and, for recurring wallet permissions, Connect Wallet / signature flows where used). * Prefer **webhooks** over polling where the partner platform supports it: see [Webhooks Overview](/webhooks/overview). * Generate API keys under `https://app.boomfi.xyz/dashboard/settings/api-keys`. * Configure settlement under [Payments Settings](/dashboard/payments-settings). ## Related * [Choose Your Integration](/choose-integration) * [Payment Links](/payments/paylinks) * [Subscriptions](/payments/subscriptions) * [Merchant Dashboard Overview](/dashboard/overview) # Stripe Billing Source: https://docs.boomfi.xyz/integrations/stripe-billing Add BoomFi crypto paylinks to Stripe Billing invoices and subscriptions. Connect [Stripe Billing](https://stripe.com/) so invoices can include a cryptocurrency pay link generated by BoomFi. ## Auto charge BoomFi does **not** implement Stripe auto-charge for crypto. To charge a customer automatically in crypto, create a recurring pay link in the [dashboard](https://app.boomfi.xyz/login) and have the customer complete wallet connection / signature where required. ## Enable the integration 1. Sign in to **Stripe**. 2. Open **Developers → API keys** and copy a secret key for the environment you want to connect. 3. Sign in to BoomFi and open **Settings → Integration**. 4. Find **Stripe** and choose **Connect**. 5. Paste the Stripe API key and confirm integration. The integration should register a Stripe webhook endpoint automatically. Confirm it under Stripe **Developers → Webhooks**. If missing, add an endpoint using the webhook URL shown in the BoomFi integration UI. Using Stripe webhooks is strongly recommended because relying only on API polling can hit rate limits. ## Subscriptions with Stripe ### Prerequisites Confirm Stripe appears as connected under Integrations. ### Create a product (optional) 1. In Stripe, open **Product catalog → Add product**. 2. Set name and price, then save. BoomFi can generate a pay link and attach it as metadata on the price / related invoices. ### Create a subscription 1. Open **Customers**, select the customer, then **Create subscription**. 2. Attach the product. 3. Under **Subscription settings**, turn **off** auto charge and invoice payment-page auto behaviour that BoomFi cannot process. Invoices left on auto-charge for card will be ignored for crypto processing. After setup, open an invoice and confirm the pay link metadata. When the customer pays successfully on the BoomFi checkout, the Stripe invoice is marked **Paid** and crypto payment details are attached. ## Related * [Integrations Overview](/integrations/overview) * [Payment Links](/payments/paylinks) * [Webhooks Overview](/webhooks/overview) # WHMCS Source: https://docs.boomfi.xyz/integrations/whmcs Offer crypto checkout in WHMCS with one-time and recurring pay links. Integrate BoomFi with [WHMCS](https://www.whmcs.com/) so clients can pay invoices with cryptocurrency at checkout. **Single-item checkout only.** Multi-item carts are not supported for the crypto payment method. Customers see an error on multi-line invoices if the crypto method is selected. ## Setup ### 1. Merchant account Create and KYB-ready your organisation at [https://app.boomfi.xyz/login](https://app.boomfi.xyz/login). ### 2. API key 1. Open `https://app.boomfi.xyz/dashboard/settings/api-keys` 2. **Create API key**, name it, store the secret ### 3. Pay links Create: * One **one-time** pay link (enable **allow repeat payments without confirmation** so multiple checkouts can reuse it) * One **recurring** pay link for subscription-style billing See [Payment Links](/payments/paylinks). ### 4. Install and configure the WHMCS module 1. In WHMCS, open **Apps & Integrations**. 2. Search for the crypto payment module and activate it. 3. Configure: | Field | Purpose | | ---------------------- | ---------------------------------------------------------------------------- | | Show on order form | Whether crypto appears at checkout | | Display name | Label clients see (for example “Crypto payment”) | | Test mode | Use pay links / keys from a separate test merchant account when you have one | | One-time payment link | From step 3 | | Recurring payment link | From step 3 | | API key | From step 2 | ## Test mode Enable **Test mode** in WHMCS only if you have a separate test merchant account. Use that account's pay links and API keys. ## Live mode Disable test mode and use production pay links and API keys from [https://app.boomfi.xyz/login](https://app.boomfi.xyz/login). ## Related * [Integrations Overview](/integrations/overview) * [Payment Links](/payments/paylinks) * [Subscriptions](/payments/subscriptions) # WooCommerce Source: https://docs.boomfi.xyz/integrations/woocommerce Accept crypto on WooCommerce invoices with the BoomFi plugin. Use BoomFi with [WooCommerce](https://woocommerce.com/) so store invoices can offer cryptocurrency checkout via a payment link. ## Auto charge BoomFi does not auto-charge crypto wallets. For recurring crypto without re-entering details each time, create a pay link that supports Connect Wallet / signature flows and complete customer setup separately. ## Prerequisites 1. A blockchain wallet ready to receive settlements (network + tokens such as USDC/USDT as you configure). 2. A merchant account on [https://app.boomfi.xyz/login](https://app.boomfi.xyz/login). 3. Settlement configured for the networks you accept: see [Payments Settings](/dashboard/payments-settings). 4. A pay link created for WooCommerce (name it clearly, set a default amount that can be overridden, allow one-time / repeat as needed). Copy the link. 5. An API key from `https://app.boomfi.xyz/dashboard/settings/api-keys`. ## Install the plugin 1. Install and activate the official WooCommerce crypto payments plugin from WordPress.org: [boomfi-crypto-payments](https://wordpress.org/plugins/boomfi-crypto-payments/). 2. In WordPress, open the plugin settings. 3. Enable the plugin, choose **Test** or **Live**, paste the **API key** and **payment link**, and save. ## Product settings For each digital product you sell through crypto, mark the product **Virtual** and **Downloadable** so WooCommerce can move paid orders to **Completed** without shipping. Configure products individually. ## Test the integration 1. Place a test order selecting the crypto payment method. 2. On checkout, complete the BoomFi payment flow (use test mode where applicable). 3. Confirm the order status in WooCommerce and the payment in the merchant [Transactions](/dashboard/transactions) list. ## Go live Switch the plugin to **Live** and replace test keys/links with production credentials. ## Related * [Integrations Overview](/integrations/overview) * [Payment Links](/payments/paylinks) * [Settlement Overview](/settlement/overview) # Introduction Source: https://docs.boomfi.xyz/introduction Overview of the BoomFi documentation portal and what you can build. Welcome to the BoomFi documentation portal. Here, you'll find comprehensive information about our three core products designed to streamline and enhance your financial operations: Payment Gateway, Crypto Exchange, and Crypto On/Off Ramp. Each product is crafted to provide seamless integration, robust features, and compliance with financial standards, ensuring your business can operate smoothly and efficiently. ## Payment Gateway BoomFi Payment Gateway offers businesses a versatile solution for accepting both cryptocurrency and traditional payments. Our gateway simplifies the complexities of multiple blockchains, cryptocurrencies, and compliance requirements, ensuring a seamless transaction process. * **Dual payment options:** Accept both fiat and cryptocurrency payments, providing flexibility and convenience to your customers. * **Seamless transaction reconciliation:** Effortlessly integrate crypto payments with settlement reports that sync with your existing accounting and banking systems. Enjoy single-point-of-truth reporting and scheduled settlements into your bank account. * **Trusted and compliant transactions:** Our gateway meets the highest financial standards, offering reliable and compliant payment processing to help you liquidate assets confidently. Start with [Payments Overview](/payments/overview), [Settlement Overview](/settlement/overview), and [Choose Your Integration](/choose-integration). ## Crypto On/Off Ramp The Crypto On/Off Ramp enables websites to integrate a seamless crypto purchasing feature, enhancing user engagement and driving revenue for merchants. * **Native crypto purchases:** Allow customers to buy and sell crypto directly within your platform, making it easy for them to fund their wallets and use digital products without leaving your site. * **Easy onboarding:** Provide a smooth onboarding experience by enabling customers to purchase crypto using fiat, reducing technical barriers. * **Crypto to fiat off-ramp:** Let customers convert their crypto earnings or sales from digital goods back into fiat and withdraw to their bank accounts, completing the transaction cycle. ## Crypto Exchange Our Crypto Exchange provides a robust solution for converting crypto assets to fiat and vice versa, catering to the diverse needs of businesses and high-net-worth individuals. * **Automatic liquidation:** Set thresholds to automatically convert crypto assets into fiat and transfer funds to your bank account, mirroring traditional payment processes. * **Flexible settlement options:** Choose to settle transactions in your preferred cryptocurrencies or fiat currencies, providing flexibility for your business operations. * **OTC trading:** Facilitate large volume crypto trades with low fees, tight spreads, and fast liquidity, similar to a foreign exchange counter for digital assets. Commercial terms and verification for exchange products are in [Pricing and Fees](/pricing/fees-and-pricing) and [Account Verification and Limits](/pricing/account-verification-limits). ## What you can build | Path | Use when | | -------------------------------------------------------- | ---------------------------------------------------------------------------------------------- | | [Payments Overview](/payments/overview) | Fixed-price products, invoices, one-off sales | | [Subscriptions](/payments/subscriptions) | Recurring access or membership billing | | [Deposit Accounts Overview](/deposits/overview) | User balances (for example iGaming, wallets, prepaid credit) | | [Offer crypto as a PSP](/payments/cookbook-psp-paylinks) | You are a merchant; your merchants are merchants too. Hold their keys and run the paylink flow | These paths share the same foundation: an organisation, API credentials, settlement configuration, and webhooks. ## Base URL API requests use: ``` https://mapi.boomfi.xyz/v1 ``` Authenticate with an API key (`X-API-KEY`). Some write endpoints also require request signatures (`X-API-Nonce`, `X-API-Signature`). See [Authentication](/authentication). Open the [merchant dashboard](https://app.boomfi.xyz/login) to manage organisation settings, settlement, pay links, transactions, API keys, and webhook event history. Need help? Contact [BoomFi support](https://help.boomfi.xyz). # Account-Specific Paylinks Source: https://docs.boomfi.xyz/payments/account-specific-paylinks Bind paylinks to settlement accounts with account_ids or account_ref. Account-specific paylinks let platforms that run **many settlement accounts** (multi-merchant, multi-chain, multi-currency) attach which accounts may receive settlement for a given pay link. ## Who this is for * Platforms routing payments to the correct merchant account * Operators who need explicit control over settlement targets * Businesses accepting payments across many chains and currencies with separate settlement wallets ## Attach accounts when creating a paylink See settlement account creation in [Settlement Accounts](/settlement/settlement-accounts) before binding them on a paylink. ### `account_ids` Pass an array of internal account ids: ```bash theme={null} curl --request POST \ --url "https://mapi.boomfi.xyz/v1/paylinks" \ --header "accept: application/json" \ --header "content-type: application/json" \ --header "X-API-KEY: sk_test_xxx" \ --data '{ "name": "Multi-account link", "amount": "100", "currency": "USD", "account_ids": [1, 2, 3] }' ``` ### `account_ref` Pass a shared merchant-defined **account reference** that groups accounts: ```bash theme={null} curl --request POST \ --url "https://mapi.boomfi.xyz/v1/paylinks" \ --header "accept: application/json" \ --header "content-type: application/json" \ --header "X-API-KEY: sk_test_xxx" \ --data '{ "name": "Ref-scoped link", "amount": "100", "currency": "USD", "account_ref": "my_acc_reference" }' ``` Some internal payloads may store the reference as `account_reference`. Prefer the create-paylink field names in the OpenAPI reference. ## Operational notes * You own routing correctness: wrong ids/refs send settlement to the wrong wallets. * More flexibility means more careful account lifecycle management. ## Related * [Payment Links](/payments/paylinks) * [Paylink Features](/payments/paylink-features) * [Settlement Overview](/settlement/overview) # Checkout Source: https://docs.boomfi.xyz/payments/checkout Hosted customer checkout for payment links. When a customer opens a payment link, BoomFi hosts checkout at `https://pay.boomfi.xyz`: they connect a wallet or follow the configured payment methods and complete the transfer on a supported network. ## How it fits together 1. You create a [Payment Links](/payments/paylinks) in the dashboard or API 2. You send the checkout URL (email, your website, in-app browser) 3. Customer completes payment 4. Your backend receives webhooks and updates order state ## After completion In the dashboard paylink builder, or via the Paylinks API `after_completion` field, you can: * Show a confirmation screen (default or custom message) * Redirect to your own success URL after a successful payment (`type: redirect` + `redirect_url`) * Redirect to a failure URL when the link expires or payment.status is Failed (`failure_redirect_url`) * Optionally allow repeat payments without a duplicate-payment acknowledgement Create, get, and list paylink responses include `after_completion` when it is set. You can also send it nested under `metadata.after_completion`; the first-class field wins if both are present. BoomFi checkout success settings ## Redirect from your app ```javascript theme={null} // Prefer the checkout URL from the dashboard or generate-variant response (`data.url`). // Create-paylink responses expose the link `id`: open the hosted URL returned by your // integration path, or call POST /paylinks/generate-variant/{paylinkId} when you need // amount/currency overrides and a temporary checkout URL. const checkoutUrl = variantResponse.data.url; window.location.href = checkoutUrl; ``` ## Trust server-side confirmation only Do not ship digital goods based solely on the browser landing on a success URL. Always verify [Verify Webhook Signatures](/webhooks/verify-signatures) and treat `Payment.Updated` with a successful status as authoritative. ## Transactions Inspect payments under `https://app.boomfi.xyz/dashboard/transactions`. BoomFi transactions list ## Next steps * [Webhooks Overview](/webhooks/overview) * [Cookbook: Sell a Product](/payments/cookbook-sell-product) * [Cookbook: Offer Crypto as a PSP](/payments/cookbook-psp-paylinks) # Cookbook: Offer Crypto as a PSP Source: https://docs.boomfi.xyz/payments/cookbook-psp-paylinks 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 ``` 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](/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. 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**. Signed events per organisation. [Configure](/webhooks/setup), [verify signatures](/webhooks/verify-signatures), then handle [event types](/webhooks/event-types) (start with `Payment.Updated`). Create links, [variant URLs](/payments/paylink-features#change-amount-and-currency), and send the customer to [hosted checkout](/payments/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: 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 | 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](/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¤cy=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/`). 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) # Cookbook: Recurring Billing Source: https://docs.boomfi.xyz/payments/cookbook-recurring End-to-end subscription setup with invoices and lifecycle webhooks. Bill customers on a interval using recurring paylinks and subscription webhooks. ## 1. Prerequisites Same as [Cookbook: Sell a Product](/payments/cookbook-sell-product): settlement, API key, verified webhooks. ## 2. Create a recurring offer ```bash theme={null} curl -X POST "https://mapi.boomfi.xyz/v1/paylinks" \ -H "X-API-KEY: sk_test_xxx" \ -H "Content-Type: application/json" \ -d '{ "name": "Pro plan", "amount": "29.00", "currency": "USD", "type": "Recurring", "interval": "Month", "intervalCount": 1, "reference": "pro_monthly" }' ``` Share the checkout URL. See [Subscriptions](/payments/subscriptions). ## 3. Provision access from webhooks | Event | Merchant action | | ------------------------------- | ------------------------------------------------- | | `Subscription.Created` | Record pending subscription | | `Subscription.Updated` (Active) | Grant product access | | `Payment.Updated` (Succeeded) | Confirm paid period | | `Invoice.Created` | Record open invoice | | `Invoice.Overdue` | Notify customer / restrict access per your policy | | `Subscription.Canceled` | Revoke access | Always [Verify Webhook Signatures](/webhooks/verify-signatures) and enforce idempotency on subscription and invoice ids. ## 4. Cancel Use the Merchants API cancel-subscription endpoints (see API reference) or customer-facing cancel flows if enabled. Expect a cancellation webhook when status settles. ## 5. Ops Use [Event History and Replay](/webhooks/event-history-and-replay) if renewal notifications failed to reach your servers. # Cookbook: Sell a Product Source: https://docs.boomfi.xyz/payments/cookbook-sell-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](/create-account) and [Authentication](/authentication) * [Settlement Overview](/settlement/overview) for the chains/assets you accept * HTTPS webhook endpoint with [Verify Webhook Signatures](/webhooks/verify-signatures) ## 2. Create the product paylink ```bash theme={null} curl -X POST "https://mapi.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](/payments/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](/webhooks/verify-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://app.boomfi.xyz/dashboard/settings/api-keys?tab=webhooks`\ filter failed events, fix your endpoint, then **Retry** or bulk replay. See [Event History and Replay](/webhooks/event-history-and-replay). ## 6. Optional API reconciliation ```bash theme={null} curl "https://mapi.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. # Payments Overview Source: https://docs.boomfi.xyz/payments/overview Accept fixed-price crypto payments with payment links and hosted checkout. Use payment links when your customer pays a **set amount** for a product, invoice, or service. BoomFi hosts checkout; you share a URL or redirect from your app. ## When to use this path * E-commerce checkout * Invoices with a known total * One-time donations or event tickets at a fixed price **Not this path:** continuous user balances → use [Deposit Accounts Overview](/deposits/overview). ## Building blocks | Building block | Role | | --------------------------------------- | ----------------------------------------------------------- | | [Payment Links](/payments/paylinks) | Merchant object + public checkout URL | | Plan | Pricing definition (one-time or recurring) backing the link | | Checkout | Hosted customer payment experience | | [Webhooks Overview](/webhooks/overview) | Server-side confirmation (`Payment.Updated`, etc.) | ## Prerequisites 1. [Settlement Overview](/settlement/overview) configured 2. API key ([Authentication](/authentication)) 3. Webhook endpoint with [Verify Webhook Signatures](/webhooks/verify-signatures) for production ## Cookbooks * [Cookbook: Sell a Product](/payments/cookbook-sell-product) * [Cookbook: Recurring Billing](/payments/cookbook-recurring) * [Cookbook: Offer Crypto as a PSP](/payments/cookbook-psp-paylinks) ## Related dashboard * Pay links: `https://app.boomfi.xyz/dashboard/pay-links` * Transactions: `https://app.boomfi.xyz/dashboard/transactions` * Customers: `https://app.boomfi.xyz/dashboard/customers` # Paylink Features Source: https://docs.boomfi.xyz/payments/paylink-features Prefill, customer_ident, redirects, variants, and managing payment links. Payment links support query parameters and variant URLs so you can tailor checkout without creating a new link for every customer. Topics: * [Prefill customer data](#prefill-customer-data) * [Connect a customer (`customer_ident`)](#connect-a-customer) * [Redirect after payment](#redirect-after-a-successful-payment) * [Change amount and currency (variants)](#change-amount-and-currency) * [Manage pay links in the dashboard](#manage-pay-links) Your base pay link URL is returned when you create a pay link (hosted checkout host + link id). Hosted checkout for this environment is rooted at `https://pay.boomfi.xyz`. Below, `` means that full URL (for example `https://pay.boomfi.xyz/`). ## Prefill customer data Append identity query parameters so the customer does not re-type data you already hold: ```text theme={null} ?name=Tamara&email=tamara@example.com ``` | Field | Description | Required | | -------------- | ----------------------------- | ------------------- | | `name` | Full name | Yes when prefilling | | `email` | Email address | Yes when prefilling | | `dateOfBirth` | ISO 8601 `YYYY-MM-DD` | Conditional\* | | `placeOfBirth` | Country / place of birth | Conditional\* | | `address1` | Address line 1 | Conditional\* | | `address2` | Address line 2 | Conditional\* | | `city` | City | Conditional\* | | `state` | State / province | Conditional\* | | `postalCode` | Postal / ZIP code | Conditional\* | | `country` | Country | Conditional\* | | `phoneNumber` | Phone in international format | Conditional\* | \*Required only when the merchant enabled that field at paylink / checkout configuration. ## Connect a customer Bind the session to a customer id you already store with `customer_ident`: ```text theme={null} ?customer_ident= ``` Webhook and dashboard activity can then use this identifier consistently. ## Redirect after a successful payment Configure redirects on the paylink with first-class `after_completion` when you create or update it (`type: redirect`, `redirect_url` for success, optional `failure_redirect_url` for expiry or Failed). Get and list paylink responses return the same object. You can also pass `redirect_to` with a URL-encoded destination. If the pay link itself has no redirect configured, the query value is used. ```text theme={null} ?redirect_to= ``` ### Skip redirect delay By default a short countdown (about 10 seconds) runs before redirect. Skip it with: ```text theme={null} ?redirect_to=&skip_redirect_delay=1 ``` ### Payment id on redirect The redirect destination receives a `pid` query parameter with the payment id so you can fetch payment details from the API: ```text theme={null} https://your.example.com/thanks?pid= ``` Use the payment-by-id endpoint on `https://mapi.boomfi.xyz/v1` with your API credentials. See the Payments operations in the API reference. ## Change amount and currency Generate a **variant** URL when the quoted amount or currency must change at send time (top-ups, tips in addition to a base amount, alternate quote currency): * Call the **Generate variant URL** paylink endpoint (see API reference) * Pass `amount` and/or `currency` * Optionally pass `customer_ident` and `redirect_to` ## Manage pay links Open: `https://app.boomfi.xyz/dashboard/pay-links` BoomFi payment link detail From a pay link detail page you can: * Inspect main, link, and checkout settings * Review transactions on that link * Edit most fields via the overflow menu, or deactivate the link You cannot change a one-time link into recurring (or vice versa) after creation: create a new link instead. ## Related * [Payment Links](/payments/paylinks) * [Account-Specific Paylinks](/payments/account-specific-paylinks) * [Checkout](/payments/checkout) # Payment Links Source: https://docs.boomfi.xyz/payments/paylinks Create, share, and manage crypto payment links (one-time or recurring). Payment links (paylinks) collect crypto payment without building your own checkout UI. Create them in the dashboard or via the API, then share the URL. ## Dashboard 1. Open `https://app.boomfi.xyz/dashboard/pay-links` 2. Create a pay link and enter name, amount, currency, payment type (one-time or recurring), and after-completion behaviour 3. Share the generated URL with your customer BoomFi payment links list BoomFi create payment link ## Create via API ```bash theme={null} curl -X POST "https://mapi.boomfi.xyz/v1/paylinks" \ -H "X-API-KEY: sk_test_xxx" \ -H "Content-Type: application/json" \ -d '{ "name": "ZenBlend Aromatherapy Diffuser", "description": "One-time purchase", "amount": "29.99", "currency": "USD", "reference": "sku_diffuser_001", "type": "OneTime", "after_completion": { "type": "redirect", "redirect_url": "https://merchant.example/checkout/success", "failure_redirect_url": "https://merchant.example/checkout/failed" } }' ``` ### Notable fields | Field | Description | | --------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `name`, `amount`, `currency` | Required | | `type` | `OneTime` or `Recurring` (defaults from interval if omitted) | | `interval`, `intervalCount` | Recurring cadence (`Day`, `Week`, `Month`, `Year`, …) | | `account_ids` / `account_ref` | Settlement targets: see [Account-Specific Paylinks](/payments/account-specific-paylinks) | | `available_quantity` | Remaining purchases; `1` for single-use | | `expires_at` | Future expiry timestamp | | `image_url`, `description`, `reference`, `metadata` | Presentation and bookkeeping | | `after_completion` | Checkout outcome: `type` (`hosted` or `redirect`), `redirect_url` (success), `failure_redirect_url` (expired link or Failed payment). Extra keys are stored and returned. Also present on get and list paylink responses. | ## List and manage ```bash theme={null} # List curl "https://mapi.boomfi.xyz/v1/paylinks" \ -H "X-API-KEY: sk_test_xxx" # Get one — response includes after_completion when configured curl "https://mapi.boomfi.xyz/v1/paylinks/{paylinkId}" \ -H "X-API-KEY: sk_test_xxx" # Update curl -X PATCH "https://mapi.boomfi.xyz/v1/paylinks/{paylinkId}" \ -H "X-API-KEY: sk_test_xxx" \ -H "Content-Type: application/json" \ -d '{"enabled": false}' ``` Batch update/delete endpoints are also available under `/paylinks/batch`. Variant URLs can be generated for specialised checkout flows (`/paylinks/generate-variant/{paylinkId}`): see [Paylink Features](/payments/paylink-features). ## Events Successful customer payment arrives as `Payment.Updated` with status `Succeeded`. Creating or updating plans/paylinks can emit `Plan.Created` / `Plan.Updated`. See [Event Types](/webhooks/event-types). ## Next steps * [Paylink Features](/payments/paylink-features) (prefill, redirects, variants) * [Account-Specific Paylinks](/payments/account-specific-paylinks) * [Checkout](/payments/checkout) * [Cookbook: Sell a Product](/payments/cookbook-sell-product) * [Cookbook: Offer Crypto as a PSP](/payments/cookbook-psp-paylinks) # Subscriptions Source: https://docs.boomfi.xyz/payments/subscriptions Bill customers on a recurring schedule with crypto and handle renewals. Subscriptions charge customers on a fixed interval. In BoomFi, recurring paylinks create plans; customers subscribe; invoices are issued; webhooks notify you of lifecycle changes. ## Flow 1. Create a **recurring** plan/paylink (`type: Recurring`, `interval`, `intervalCount`) 2. Customer completes the first checkout 3. Platform issues invoices on schedule 4. You handle `Subscription.*` and `Invoice.*` webhooks ## Create a recurring paylink ```bash theme={null} curl -X POST "https://mapi.boomfi.xyz/v1/paylinks" \ -H "X-API-KEY: sk_test_xxx" \ -H "Content-Type: application/json" \ -d '{ "name": "Premium membership", "amount": "69.99", "currency": "USD", "type": "Recurring", "interval": "Month", "intervalCount": 1, "reference": "plan_premium_monthly" }' ``` ## Plans API List, create, and retrieve plans: * `GET https://mapi.boomfi.xyz/v1/plan` * `POST https://mapi.boomfi.xyz/v1/plan` * `GET https://mapi.boomfi.xyz/v1/plan/{id}` ## Subscriptions API * `GET https://mapi.boomfi.xyz/v1/subscriptions`: list * `GET https://mapi.boomfi.xyz/v1/subscriptions/{customerID}`: list by customer * `POST https://mapi.boomfi.xyz/v1/subscriptions/{subscriptionID}/invoices`: create invoice * Cancel / delete flows as documented in the API reference under **Subscriptions** ## Events to handle | Event | Why it matters | | ----------------------- | --------------------------------- | | `Subscription.Created` | New subscription pending/starting | | `Subscription.Updated` | Active, status changes | | `Subscription.Canceled` | Churn / access revocation | | `Invoice.Created` | New invoice open | | `Invoice.Overdue` | Failed renewal / dunning | Full detail: [Event Types](/webhooks/event-types). ## Cookbook See [Cookbook: Recurring Billing](/payments/cookbook-recurring). # Payouts Overview Source: https://docs.boomfi.xyz/payouts/overview Send crypto or fiat from your virtual account to a whitelisted external account. Payouts move funds from your BoomFi virtual account balance to an **external account** you've registered — a crypto wallet or a bank account. See [Whitelist External Account](/whitelist-external-account/overview) to register a destination first. ## Prerequisites * Funded [Virtual Accounts](/settlement/virtual-accounts) * A registered, enabled [external account](/whitelist-external-account/overview) to pay out to * [Authentication](/authentication) (`X-API-KEY`, `X-API-Nonce`, `X-API-Signature`) Because whitelisting the destination is the step-up-protected step, creating the payout itself needs no per-request OTP — it can be called by an API key alone. ## Create a payout (API) Address the destination by the `id` or `reference` you registered it with. The currency decides the rail: a fiat symbol settles to the destination's bank account, a digital one to its wallet (and requires `chain_id`). ```bash theme={null} curl -X POST "https://mapi.boomfi.xyz/v1/accounts/virtual/payout" \ -H "X-API-KEY: sk_test_xxx" \ -H "Content-Type: application/json" \ -H "X-API-Nonce: nonce-unique-1" \ -H "X-API-Signature: " \ -d '{ "destination_account_reference": "treasury-base", "currency": "USDC", "chain_id": 8453, "amount": "10.00" }' ``` | Field | Type | Required | Description | | ---------------------------------------------------------- | ------ | -------------------- | ------------------------------------------------------------------------------------------ | | `destination_account_id` / `destination_account_reference` | | exactly one | The registered external account to pay | | `account_id` / `account_reference` | | no | Which virtual (sub-)account to pay out from; defaults to the org's primary virtual account | | `amount` | string | yes | Amount in major units | | `currency` | string | yes | Fiat symbol takes the bank rail, digital takes the chain rail | | `chain_id` | number | required for digital | Must be omitted for fiat | | `token_address` | string | no | Only needed when the symbol maps to several tokens on the chain | | `reference` | string | no | Your own reference for this payout; must be unique | | `metadata` | object | no | Caller metadata returned on the payment record (max 2 KiB) | Use the request schema from the API reference (`CreateVirtualPayoutRequest`) for exact fields. ## Direct wallet payout (no whitelisting) For a one-off crypto send where you don't want to register a destination first, `POST /accounts/virtual/payout/address` still pays out directly to a wallet address: ```bash theme={null} curl -X POST "https://mapi.boomfi.xyz/v1/accounts/virtual/payout/address" \ -H "X-API-KEY: sk_test_xxx" \ -H "Content-Type: application/json" \ -H "X-API-Nonce: nonce-unique-1" \ -H "X-API-Signature: " \ -d '{ "wallet_address": "0xRecipientWallet…", "chain_id": 8453, "ccy": "USDC", "amount": "10.00" }' ``` This path is digital-only and has no equivalent for fiat: use the whitelisted flow above for a bank payout, or for any destination you'll pay repeatedly. ## Dashboard Use the Account experience (`https://app.boomfi.xyz/dashboard/account`) for payout controls in the merchant UI. BoomFi account payouts ## Events and monitoring Track resulting payments/transactions in the dashboard and via webhooks. Failed webhook delivery does not reverse an on-chain payout: reconcile carefully. # Withdraw to Bank Source: https://docs.boomfi.xyz/payouts/withdraw-to-bank Withdraw crypto proceeds to a bank account after KYB. BoomFi lets you withdraw funds **directly to a bank account**. Complete **Know Your Business (KYB)** before bank withdrawal is available. Contact [support](https://help.boomfi.xyz) to start KYB if you have not already. ## Prerequisites * Approved KYB * Beneficiary bank details configured during onboarding * Sufficient balance and a supported source coin for the withdrawal ## Make a withdrawal 1. Open the dashboard: [https://app.boomfi.xyz/login](https://app.boomfi.xyz/login) 2. Choose **Withdraw to bank** (often top-right of the main dashboard). 3. Select **amount** and **coin**. Review exchange rate, service fee, beneficiary details, and net fiat amount. 4) Continue and fund the withdrawal in one of two ways: ### Manual transfer Scan the shown **QR code** or copy the destination details, send funds from your wallet, then confirm **I've made the transfer**. ### Wallet connection Connect a wallet in the prompt and sign/send the required transfer. The withdrawal stays **pending** until BoomFi confirms receipt of the crypto leg (or marks the attempt failed). Status also appears under [Transactions](/dashboard/transactions). ### Success After confirmation, fiat is sent to the registered bank beneficiary according to the quoted schedule and fee. ### Failure If the crypto leg is not received, the attempt is cancelled. Retry from the dashboard when ready. ## Related * [Payouts Overview](/payouts/overview) * [Account Verification and Limits](/pricing/account-verification-limits) * [Pricing and Fees](/pricing/fees-and-pricing) # Account Verification and Limits Source: https://docs.boomfi.xyz/pricing/account-verification-limits KYC and KYB verification levels and transaction limits for OTC and card products. BoomFi is required to complete Know Your Customer (KYC) or Know Your Business (KYB) checks before you can use OTC Exchange services and similar regulated products. This supports anti-money laundering (AML) obligations as a licensed Virtual Asset Service Provider. Verification differs for individuals and businesses, with two tiers: Level 1 provides access with restricted limits, and Level 2 offers higher limits. ## Limits summary | Limit | Level 1 OTC | Level 1 Card | Level 2 OTC | Level 2 Card | | ----------------------------- | --------------------------------------------------------------------- | -------------------------------------------------------------- | -------------------------------------------------------------------------------------- | --------------------------------------------------------------- | | Fiat to crypto | 50,000 EUR / day | 3,000 EUR / transaction · 5,000 EUR / day · 20,000 EUR / month | 100,000 EUR / day | 3,000 EUR / transaction · 10,000 EUR / day · 50,000 EUR / month | | Crypto to fiat withdrawal | 50,000 EUR / day | n/a | 1 million EUR / day | n/a | | Verification attributes (KYC) | Name, email, phone number, ID doc, liveness selfie, wallet screen | n/a | Level 1 + proof of address, proof of source of funds / source of wealth, wallet screen | n/a | | Verification attributes (KYB) | Company docs, source of funds, business questionnaire + wallet screen | n/a | Custom KYB onboarding | n/a | ## How to start verification In the merchant dashboard open **Settings → Verification**: `https://app.boomfi.xyz/dashboard/settings/verification` BoomFi verification settings Complete the steps shown for your account type. Contact [support](https://help.boomfi.xyz) if you need higher limits. ## Related * [Unsupported Countries](/pricing/unsupported-countries) * [Unsupported Business Activities](/pricing/unsupported-business-activities) * [Pricing and Fees](/pricing/fees-and-pricing) # Pricing and Fees Source: https://docs.boomfi.xyz/pricing/fees-and-pricing Processing fees for payment gateway, exchange, and related products. BoomFi fees depend on product path: crypto payment acceptance, optional fiat settlement, and exchange. ## Payment gateway | Payment gateway\* | Fee | | :----------------------------------------------------- | :------------------------ | | Crypto Acceptance fee (Crypto to Crypto) | 1% + \$0.25 / transaction | | Crypto Acceptance fee (Crypto to Fiat Bank Settlement) | 2% + \$0.25 / transaction | | Payment Recovery Fee (when recoverable) | 1% (min \$15) / recovery | *\*Payment gateway fees can be passed onto the payer at the merchant's discretion.* ## Crypto exchange (businesses and HNWI) | Crypto exchange service | Fee | | :----------------------------------- | :-- | | Buy crypto (min \$50K USD buy/sell) | 1% | | Sell crypto (min \$50K USD buy/sell) | 1% | Volume-based discounts may apply depending on monthly transaction value. Contact [support](https://help.boomfi.xyz) for commercial terms. ## Recovery of unsupported or incorrect payments Payment Recovery Fee applies **when recovery is possible**. Always instruct customers to pay only the chains and assets enabled for your settlement and deposit wallets. Incorrect network or token transfers may be unrecoverable: see [Networks and Currencies](/pricing/networks-and-currencies) and deposit [safety notes](/deposits/overview). # Networks and Currencies Source: https://docs.boomfi.xyz/pricing/networks-and-currencies Supported blockchain networks, cryptocurrencies, payment rails, and fiat currencies. Supported blockchain networks, cryptocurrencies, payment rails, and fiat currencies for BoomFi. ## Supported blockchain networks | Network | Payment Gateway | Smart Wallets | OTC | `chain_id` | | :------------------------------------------- | :-------------- | :------------ | :-- | :--------- | | [Ethereum Mainnet](https://ethereum.org/en/) | ✅ | ✅ | ✅ | 1 | | [Solana](https://solana.com/) | ✅ | ✅ | ✅ | 1399811149 | | [Tron](https://tron.network/) | ✅ | ✅ | ✅ | -200 | | [Polygon](https://polygon.technology/) | ✅ | ✅ | ✅ | 137 | | [Arbitrum](https://arbitrum.io/) | ✅ | ✅ | ✅ | 42161 | | [BNB Chain](https://www.bnbchain.org/) | ✅ | ✅ | ✅ | 56 | | [Base Chain](https://www.base.org/) | ✅ | ✅ | ✅ | 8453 | | [Ton](https://ton.org/) | - | ✅ | ✅ | 201514 | | [Bitcoin](https://bitcoin.org/en/) | ✅ | ✅ | ✅ | 20090103 | ## Supported cryptocurrencies | Cryptocurrency | Payment Gateway | OTC | Invoice CCY | | :------------- | :-------------- | :-- | :---------- | | ETH | ✅ | ✅ | ✅ | | USDC | ✅ | ✅ | ✅ | | USDT | ✅ | - | ✅ | | WETH | ✅ | - | - | | DAI | ✅ | - | ✅ | | SOL | ✅ | ✅ | ✅ | | BTC | ✅ | ✅ | - | | BNB | - | - | ✅ | | MATIC / POL | - | - | ✅ | | TRX | - | - | ✅ | | TON | - | - | ✅ | | ARB | - | - | ✅ | | AXM | - | - | ✅ | | SGD | - | - | ✅ | | EURO | - | ✅ | ✅ | | AED | - | ✅ | ✅ | | USD | - | ✅ | ✅ | | GBP | - | ✅ | ✅ | | AUD | - | ✅ | - | | MXN | - | ✅ | - | | HKD | - | - | ✅ | | PLN | - | - | ✅ | | JPY | - | - | ✅ | | IDR | - | - | ✅ | ## Supported payment networks | Network | OTC | | :--------------------------------------------------- | :-- | | SEPA / SEPA Instant *(same day)* | ✅ | | UK FPS *(same day)* | ✅ | | SWIFT *(2-3 business days)* | ✅ | | ACH *(1-2 business days - 13:00 ET cut off)* | ✅ | | Fedwire *(same day - 16:45 ET cut off)* | ✅ | | US Wire *(same day - 16:45 ET cut off)* | ✅ | | Visa / Mastercard *(excl. Premium & Business cards)* | - | ## Supported fiat currencies | Fiat currency (38 supported) | OTC | | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :-- | | EUR | ✅ | | USD | ✅ | | GBP | ✅ | | Other: AED, AUD, BBD, BGN, BHD, CAD, CHF, CZK, DKK, GHS, HKD, HUF, ILS, JPY, KES, MWK, MXN, NOK, NZD, OMR, PHP, PKR, PLN, QAR, RON, SAR, SEK, SGD, THB, TND, TRY, TTD, UGX, ZAR, ZMW. | ✅ | ## Merchant deposit wallets API creation of permanent deposit wallets supports **EVM, Solana, Tron, and Bitcoin** chains. TON and Celo are rejected for proxy-wallet v3 deposit address creation. Always pass a platform-validated `chain_id` from this table and ensure the currency is enabled on your virtual account. # Risk Summary Regarding Cryptoassets Source: https://docs.boomfi.xyz/pricing/risk-summary Key risks associated with cryptoassets and related investments. The Financial Conduct Authority (FCA) deems this investment high-risk due to the potential for significant financial losses. Before making any investment decisions, carefully consider the associated risks. ## What are the key risks? ### 1. You could lose all the money you invest The performance of most crypto assets can be highly volatile, with their value dropping as quickly as it can rise. You should be prepared to lose all the money you invest in crypto assets. The crypto asset market is largely unregulated. You may lose money or any crypto assets you purchase due to risks such as cyber-attacks, financial crime, and firm failure. ### 2. You should not expect to be protected if something goes wrong The Financial Services Compensation Scheme (FSCS) doesn’t protect this type of investment because it’s not a ‘specified investment’ under the UK regulatory regime: in other words, this type of investment isn’t recognized as the sort of investment the FSCS can protect. Learn more using the [FSCS investment protection checker](https://www.fscs.org.uk/check/investment-protection-checker/). ### 3. You may not be able to sell your investment when you want There is no guarantee that investments in crypto assets can be quickly sold at any given time. The ability to sell a crypto asset depends on various factors, including the supply and demand in the market at that time. Operational failings, such as technology outages, cyber-attacks, and the comingling of funds, could cause unwanted delays, and you may be unable to sell your crypto assets when you want. ### 4. Cryptoasset investments can be complex Investments in crypto assets can be complex, making it difficult to understand the risks associated with the investment. Do your own research before investing. If something sounds too good to be true, it probably is. ### 5. Don’t put all your eggs in one basket Investing all your money in a single type of investment is risky. Spreading your money across different investments makes you less dependent on any one for success. A good rule of thumb is not to invest more than 10% of your money in high-risk investments. Learn more about investing [here](https://www.fca.org.uk/investsmart/5-questions-ask-you-invest). ### Learn more To learn more about protecting yourself, visit the [FCA’s website](https://www.fca.org.uk/investsmart). See the [FCA’s Crypto: The basics](https://www.fca.org.uk/investsmart/crypto-basics) article for further information about crypto assets. # Service Level Agreement Source: https://docs.boomfi.xyz/pricing/service-level-agreement Uptime targets, support response times, and customer responsibilities for BoomFi. ### 1. Overview This Service Level Agreement ("SLA") defines uptime targets, support response times, and responsibilities between BoomFi ("Provider") and its customers ("Client"). ### 2. Service availability and uptime BoomFi commits to maintaining a **99.8% uptime** for its core payment processing services, excluding scheduled maintenance and force majeure events. * **Planned maintenance:** Scheduled with at least **48 hours' notice** via email or platform notifications. * **Unplanned outages:** BoomFi provides real-time status updates on its status page. ### 3. Support and response times BoomFi provides customer support based on the following severity levels: | Severity level | Definition | Initial response time | Resolution target time | | -------------- | --------------------------------------------------------------------- | ----------------------------- | --------------------------------- | | **Critical** | Service is completely down, causing financial impact. | **30 minutes** (24/7) | Best effort, immediate escalation | | **High** | Major issue affecting transactions but partial functionality remains. | **2 hours** (24/7) | Within **8 hours** | | **Medium** | Minor issue, system functioning with some limitations. | **4 hours** (business hours) | Within **24 hours** | | **Low** | General inquiries, non-urgent issues. | **24 hours** (business hours) | Within **5 business days** | ### 4. Customer service SLA BoomFi support commitments include: * **Multi-channel support:** Clients can reach BoomFi via email, live chat, and ticketing system. * **First contact resolution:** Resolve simple queries in the first interaction whenever possible. * **Escalation process:** Unresolved issues escalated to senior support within **24 hours** of the initial report. * **Customer satisfaction (CSAT) tracking:** Regular feedback to measure and improve service quality. * **Priority handling:** VIP and enterprise users may receive dedicated support channels with faster resolution times. Contact [BoomFi support](https://help.boomfi.xyz). ### 5. Customer responsibilities To ensure effective support, clients must: * Provide accurate incident details when reporting issues. * Use designated communication channels for support requests. * Maintain compliance with BoomFi Terms of Service. ### 6. Exclusions This SLA does not cover: * Issues caused by third-party providers, blockchain network congestion, or external factors. * Force majeure events, including natural disasters or regulatory changes. * Client-side connectivity, hardware failures, or non-compliance with security best practices. ### 7. Modification and termination BoomFi reserves the right to update this SLA at any time. # Unsupported Business Activities Source: https://docs.boomfi.xyz/pricing/unsupported-business-activities Goods and services that cannot use BoomFi products. BoomFi products are available to businesses **except** those offering the following goods and services: * Services that automatically activate periodic subscriptions, particularly in industries like nutraceuticals or pseudo-pharmaceuticals * Devices designed to circumvent encrypted content (e.g., TV, cable, pay-per-view programs) * Anti-virus and cleaning software (except recognized brands) * Claims recovery agencies or firms * Credit card or identity protection services * Services to restore bank credit scores * Refinancing, credit recovery, or settlement services * Facsimile currency * Counterfeit design products or replicas (except furniture) * Substances simulating the effects of illegal drugs * Payment of fines * Guarantees or protection against forced execution * Pretenders, riddles, or clairvoyants * Illegal gambling online, by phone, or mail * Lifetime subscriptions for any product or service * Any product or service related to illegal activities * Medical benefits packages, including discount medical cards * Marijuana pharmacies and related services * Activities prohibited by card schemes * Cross-selling techniques that share confidential cardholder data * Selling value-stored cards for card-not-present transactions * Deceptive marketing practices * Technology products infringing on intellectual property rights * Shell banks * Issuers of bearer shares * Payable-through accounts * Quick investment schemes, including online search/ad optimization * Money gifts * Changes in mortgages or credits, and mortgage redemption services * Multi-level marketing or pyramid schemes focusing on recruiting new distributors * Advance credit offers * Chain messages intended for widespread forwarding * Cash collection institutions * Pharmacies, prescription drug retailers, or prescription discounts * PC support services, registry cleaning software, and bug fixes * Adult products or services involving bestiality, infant pornography, necrophilia, incest, violence, or BDSM * Drugs of any kind * Warranty extension companies * Commerce startups accepting orders by mail or telephone * Sites promoting hate, racism, or religious persecution * Time-sharing and promotional services * "Win a house" schemes If you are unsure whether your business qualifies, contact [BoomFi support](https://help.boomfi.xyz) before onboarding. # Unsupported Countries Source: https://docs.boomfi.xyz/pricing/unsupported-countries Jurisdictions where BoomFi regulated or software services are unavailable. The following jurisdictions are classified as high-risk third countries effective **30 June 2025**: **Algeria, Angola, Côte d’Ivoire, Kenya, Laos, Lebanon, Monaco, Namibia, Nepal and Venezuela.** Clients from these jurisdictions are subject to enhanced due diligence or onboarding restrictions. (The full European Commission regulation is available [here](https://ec.europa.eu/transparency/documents-register/detail?ref=C\(2025\)3815\&lang=en).) *** Businesses worldwide can use BoomFi payment software and infrastructure **except** businesses and residents of the countries and regions listed below. ## Regulated services only Countries and U.S. states where **regulated services** are currently unavailable: | Country | | :---------------------------------- | | USA: New York, Alaska and Louisiana | | Afghanistan | | Albania | | Bahamas | | Bangladesh | | Barbados | | Belarus | | Bolivia | | Botswana | | Burkina Faso | | Cambodia | | Canada: Quebec | | Cayman Islands | | China | | Congo | | Côte d'Ivoire | | Cuba | | Ecuador | | Ghana | | Haiti | | Iran | | Iraq | | Jamaica | | Kosovo | | North Korea | | Liberia | | Macau | | Malaysia | | Mongolia | | Morocco | | Myanmar | | Netherlands | | Nicaragua | | Pakistan | | Palestine | | Panama | | Russian Federation | | Senegal | | South Africa | | South Sudan | | Sudan | | Syrian Arab Republic | | Trinidad And Tobago | | Uganda | | Ukraine | | United Kingdom | | Virgin Islands | | Vanuatu | | Venezuela | | Yemen | | Zimbabwe | ## Software services only Countries and territories where **software services** are currently unavailable: | Country / territory | | :-------------------------------- | | Afghanistan | | American Samoa | | Bahamas | | Belarus | | Bosnia-Herzegovina | | Botswana | | Burkina Faso | | Burundi | | Cambodia | | Central African Republic | | Chad | | Congo (Brazzaville) | | Congo, the Democratic Republic | | Crimea (Ukraine) | | Cuba | | Donetsk (Ukraine) | | Equatorial Guinea | | Eritrea | | Fiji | | Gaza Strip | | Guam | | Guatemala | | Guinea | | Guinea Bissau | | Guyana | | Haiti | | Honduras | | Iran, Islamic Republic of | | Iraq | | Kherson (Ukraine) | | Kosovo | | Lao People's Democratic Republic | | Lebanon | | Libya | | Luhansk | | Mali | | Mauritania | | Mongolia | | Myanmar | | Nicaragua | | Niger | | Niue | | North Korea | | Oman | | Pakistan | | Panama | | Russian Federation | | Samoa | | Sevastopol (Ukraine) | | Somalia | | South Sudan | | Sudan | | Suriname | | Syria | | Timor-Leste | | Trinidad & Tobago | | Turkmenistan | | Uganda | | United States Virgin Islands | | Vanuatu | | Venezuela | | West Bank (Palestinian Territory) | | Western Sahara | | Yemen | | Zaporizhia (Ukraine) | | Zimbabwe | Lists can change as regulations evolve. Contact [BoomFi support](https://help.boomfi.xyz) if you are unsure about eligibility for your jurisdiction. # Quickstart Source: https://docs.boomfi.xyz/quickstart Create your first paylink with the Merchants API and prepare for webhooks. This quickstart creates a one-time payment link and points you at settlement and webhooks for a complete first payment. ## Prerequisites 1. [Create an Account](/create-account) 2. [Authentication](/authentication) from `https://app.boomfi.xyz/dashboard/settings/api-keys` 3. Prefer configuring [Settlement Overview](/settlement/overview) so customers can complete crypto payment ## Create a paylink ```bash theme={null} curl -X POST "https://mapi.boomfi.xyz/v1/paylinks" \ -H "X-API-KEY: sk_test_xxx" \ -H "Content-Type: application/json" \ -H "Accept: application/json" \ -d '{ "name": "Sample product", "amount": "25.00", "currency": "USD", "description": "Quickstart charge", "reference": "quickstart_order_1" }' ``` Required fields: `name`, `amount`, `currency`. Optional fields include `type` (`OneTime` or `Recurring`), `interval` / `intervalCount` for subscriptions, `account_ids` or `account_ref` for settlement accounts, `available_quantity`, and `expires_at`. The response includes a payment-link identifier and a URL customers can open for checkout. See [Payment Links](/payments/paylinks). ## Listen for payment success When the customer pays, BoomFi delivers webhook events such as `Payment.Updated` with status `Succeeded`. Configure your endpoint and verify signatures before trusting payloads: 1. [Configure Webhooks](/webhooks/setup) 2. [Verify Webhook Signatures](/webhooks/verify-signatures) ## Deposit path instead For permanent user deposit addresses (balances / iGaming), use the [Deposit Accounts Overview](/deposits/overview) cookbook after your [Virtual Accounts](/settlement/virtual-accounts) is ready. That path requires request signing headers. ## Next steps * [Choose Your Integration](/choose-integration) * [Merchant Dashboard Overview](/dashboard/overview) * [Cookbook: Sell a Product](/payments/cookbook-sell-product) * [Cookbook: User Balance Deposits](/deposits/cookbook-user-balance) * [Cookbook: Offer Crypto as a PSP](/payments/cookbook-psp-paylinks) # Settlement Overview Source: https://docs.boomfi.xyz/settlement/overview Configure where crypto payment proceeds land before you accept payments. BoomFi is a crypto-to-crypto payment gateway. You choose which blockchains and currencies to accept through settlement settings. Configure settlement before customers pay, or checkout may not expose the networks you expect. ## Concepts | Concept | Role | | ------------------------- | -------------------------------------------------------------------------------------- | | **Settlement account** | An account record for receiving proceeds (`CryptoPayIn` and related types) | | **Virtual account** | Org-managed hierarchy of wallets (empty `reference` parent) with per-chain balances | | **Pay-in deposit wallet** | Permanent sub-address for a customer `reference`; sweeps to the parent virtual account | Dashboard path for payment / settlement settings: `https://app.boomfi.xyz/dashboard/settings/settlement` Balances and virtual-account tools also appear under **Account** when your org has the virtual-account feature: `https://app.boomfi.xyz/dashboard/account` BoomFi settlement settings ## Recommended order 1. [Settlement Accounts](/settlement/settlement-accounts) 2. [Create or extend the virtual account](/settlement/virtual-accounts) with the chains and currencies you accept 3. Attach those accounts when [Payment Links](/payments/paylinks) (`account_ids` or `account_ref`) 4. For balance products, [Create a Deposit Address](/deposits/create-address) ## Supported networks Supported chains and assets evolve; see [Networks and Currencies](/pricing/networks-and-currencies). Always use identifiers returned by the platform (dashboard selectors or API responses). ## Next steps * [Settlement Accounts](/settlement/settlement-accounts) * [Virtual Accounts](/settlement/virtual-accounts) * [Choose Your Integration](/choose-integration) # Settlement Accounts Source: https://docs.boomfi.xyz/settlement/settlement-accounts List, create, and manage merchant settlement accounts via dashboard or API. Settlement accounts define where payment proceeds can settle. You can manage them in the dashboard under **Settings → Payments / settlement**, or with the Accounts API. Base path: `https://mapi.boomfi.xyz/v1/accounts` ## List settlement accounts ```bash theme={null} curl "https://mapi.boomfi.xyz/v1/accounts" \ -H "X-API-KEY: sk_test_xxx" \ -H "Accept: application/json" ``` Filter by exact `reference`: ```bash theme={null} curl "https://mapi.boomfi.xyz/v1/accounts?reference=my_personal_accounts" \ -H "X-API-KEY: sk_test_xxx" \ -H "Accept: application/json" ``` ## Create a settlement account ```bash theme={null} curl -X POST "https://mapi.boomfi.xyz/v1/accounts" \ -H "X-API-KEY: sk_test_xxx" \ -H "Content-Type: application/json" \ -d '{ "type": "CryptoPayIn", "name": "primary_settlement", "reference": "my_personal_accounts", "chain_id": 8453, "address": "0x4649f19a2c42C8C88b668a9198fBad51103D8E33", "currencies": ["ETH", "USDC"] }' ``` Use a controlled address you own. `chain_id` values are documented under [Networks and Currencies](/pricing/networks-and-currencies). ## Get, update, delete * `GET https://mapi.boomfi.xyz/v1/accounts/{id}` * `PATCH https://mapi.boomfi.xyz/v1/accounts/{id}` * `DELETE https://mapi.boomfi.xyz/v1/accounts/{id}` Replace `{id}` with the numeric account id from create/list responses. ## Paylinks attachment When you create a [Payment Links](/payments/paylinks), pass `account_ids` or `account_ref` so checkout uses the correct settlement targets. ## Next steps * [Virtual Accounts](/settlement/virtual-accounts) * [Payments Overview](/payments/overview) # Virtual Accounts Source: https://docs.boomfi.xyz/settlement/virtual-accounts Create and manage the org virtual account hierarchy, balances, and chains. A virtual account is the org’s managed wallet hierarchy: a primary account (empty `reference`) with crypto wallets on enabled chains, plus optional pay-in sub-accounts for permanent deposit addresses. ## Create the virtual account ```bash theme={null} curl -X POST "https://mapi.boomfi.xyz/v1/accounts/virtual" \ -H "X-API-KEY: sk_test_xxx" \ -H "Content-Type: application/json" \ -H "X-API-Nonce: nonce-$(date +%s)" \ -H "X-API-Signature: " \ -d '{ "chains": [ { "chain_id": 8453, "currencies": ["USDC", "ETH"] } ] }' ``` Virtual-account write endpoints require request signing when signature verification is enforced. See [Authentication](/authentication). ## Get virtual account ```bash theme={null} curl "https://mapi.boomfi.xyz/v1/accounts/virtual" \ -H "X-API-KEY: sk_test_xxx" ``` Returns the primary virtual account and nested structure (chains, addresses, state). The parent must be **enabled** and in a **Ready** state before you create pay-in deposit wallets. ## Update virtual account Enable additional chains/currencies or disable existing ones via `PATCH https://mapi.boomfi.xyz/v1/accounts/virtual`. ## Balances ```bash theme={null} curl "https://mapi.boomfi.xyz/v1/accounts/virtual/balances" \ -H "X-API-KEY: sk_test_xxx" ``` Lists balances across the primary virtual-account hierarchy. ## Permanent pay-in wallets Create customer deposit addresses with `POST https://mapi.boomfi.xyz/v1/accounts/virtual/payin/address`. Deposits on those addresses are swept to the parent account. Full guide: [Create a Deposit Address](/deposits/create-address). ## Dashboard * Settlement: `https://app.boomfi.xyz/dashboard/settings/settlement` * Account balances UI: `https://app.boomfi.xyz/dashboard/account` BoomFi virtual account balances ## Payouts from the virtual account `POST https://mapi.boomfi.xyz/v1/accounts/virtual/payout/address` creates a payout to an external wallet (signed; session auth may require step-up). See the API reference for the full request schema. ## Next steps * [Deposit Accounts Overview](/deposits/overview) * [Payment Links](/payments/paylinks) # Webhook Best Practices Source: https://docs.boomfi.xyz/webhooks/best-practices Idempotency, security, and operational patterns for reliable webhook handlers. ## Security * Always [Verify Webhook Signatures](/webhooks/verify-signatures) before business logic * Reject stale timestamps * Check `org_id` so partner/metadata edge cases cannot cross orgs * Serve only over HTTPS; do not log full headers if they include secrets from your own reverse proxies ## Correctness * **Idempotency**: process by payment / subscription / invoice id; retries and replays will re-send the same business event * Prefer updating state machines (`paid`, `active`) rather than incrementing counters without keys * Persist the raw event id when available for audit ## Performance * Return `2xx` after durable write (database commit or queue enqueue) * Do slow work asynchronously *after* acknowledging, but ensure crash recovery from persisted events * Keep response under a few seconds to avoid timeouts marking deliveries failed ## Configuration * Keep webhook URL and public key in sync across environments * Rotate keys deliberately; dual-run verification during rotations if possible * Distinguish [request signing secrets](/authentication) from webhook RSA keys ## Observability * Monitor non-2xx rates at your edge * Review [event history](/webhooks/event-history-and-replay) weekly during early integration * Alert when failed\_count grows ## Testing 1. Point webhook URL at a tunnel to local 2. Create a small paylink payment or use test tools 3. Confirm signature verification passes with dashboard public key 4. Force a handler error, confirm failed status, **Retry**, confirm success ## Related * [Configure Webhooks](/webhooks/setup) * [Event Types](/webhooks/event-types) # Event History and Replay Source: https://docs.boomfi.xyz/webhooks/event-history-and-replay Inspect webhook deliveries in the dashboard, retry failed events, and use the Events API. When your endpoint is down or returns non-2xx, deliveries fail. The merchant dashboard records attempts so you can fix the receiver and resend without losing business events. ## Dashboard event log Open **Settings → API & Webhook → Webhooks**: `https://app.boomfi.xyz/dashboard/settings/api-keys?tab=webhooks` BoomFi webhook event history ### What you can do | Capability | Behaviour | | ----------------- | --------------------------------------------------------------------------------------- | | List events | Paginated history for your organisation | | Filters | Event type, action, delivery status (`succeeded` / `failed`), document id, time range | | Detail panel | Payload, delivery status, attempt list (original vs retry), HTTP metadata when captured | | **Retry** | Resend one failed event (button disabled unless latest delivery failed) | | **Replay failed** | Queue resend for failed events currently matched on the page | ### Retry cooldown Manual retries enforce a **60 second** cooldown per event. Replaying during cooldown returns rate-limit style errors (HTTP 429) and skips ineligible ids. Queued deliveries poll until attempts complete. ### Permissions Viewing the log requires the same permission family as managing API keys (`CREATE_VIEW_API_KEY` in the merchant app). Ensure ops engineers hold that permission. ## What a retry does Manual redispatch POSTs the **stored event document** (exact body already processed for delivery) to your **current** organisation webhook URL, re-signing with your webhook private key and new `X-BoomFi-Timestamp` / `X-BoomFi-Signature` headers. A new delivery attempt row is recorded. ## List events API ```bash theme={null} curl "https://mapi.boomfi.xyz/v1/events?event_status=failed&limit=20&page=1" \ -H "X-API-KEY: sk_test_xxx" ``` Useful query parameters: | Param | Purpose | | ------------------ | ------------------------------- | | `event_status` | `succeeded` or `failed` | | `event_type` | e.g. Payment | | `event_action` | e.g. Updated | | `document_id` | Payment/plan/invoice display id | | `since` / `until` | RFC3339 time bounds | | `limit` / `page` | Pagination | | `sort` / `sort_by` | Ordering | List items include delivery snapshot fields such as `delivery_status`, `webhook_url`, `webhook_response_status`, and request header dumps when captured (including signature headers). ## Retry / replay API paths OpenAPI exposes event detail, single retry, and replay-failed routes under `/events`. Use the dashboard for day-to-day ops, or call those routes programmatically with the same eligibility rules (failed latest delivery, not queued, outside cooldown). ## Operational runbook 1. Alert on failed deliveries or customer reports 2. Open the Webhooks tab filtered to `failed` 3. Inspect response status/body 4. Fix endpoint (downtime, signature bug, 5xx) 5. Retry one event as a smoke test 6. Bulk replay remaining failures 7. Confirm orders updated idempotently ## Related * [Verify Webhook Signatures](/webhooks/verify-signatures) * [Webhook Best Practices](/webhooks/best-practices) # Event Types Source: https://docs.boomfi.xyz/webhooks/event-types Catalog of webhook event Type.Action values and payload conventions. Each delivery is a JSON object. The platform injects: ```json theme={null} "event": "Payment.Updated" ``` where the value is `Type.Action` from the internal event enum. ## Event types (`Type`) | Type | Meaning | | ---------------------------------------------------------- | ------------------------------------------------------------------------ | | `Payment` | Customer payment lifecycle | | `Plan` | Plan / catalog definition | | `Subscription` | Subscription lifecycle | | `Invoice` | Invoice lifecycle | | `Customer` | Customer records | | `Account` | Account alerts (for example low balance / virtual account alert actions) | | `Transaction` / `CryptoTransaction` / `OfframpTransaction` | On-chain or offramp transaction notifications when raised | | `Org` / `MerchantContract` | Organisation or contract-level events | ## Event actions (`Action`) Common actions: | Action | Typical use | | ----------------------------------------------- | ------------------------------------------------- | | `Created` | Resource created | | `Updated` | Status or field change | | `Canceled` | Subscription or similar cancellation | | `Overdue` | Invoice overdue | | `Refunded` | Refund applied | | `Settled` | Settlement-related payment stage | | `Processed` / `Queued` / `Enabled` / `Disabled` | Operational transitions | | `Delayed` | Delayed processing (may also notify internal ops) | | `LowBalanceDetected` / `VirtualAccountAlert` | Account monitoring | Exact action availability depends on the resource. ## Common merchant events ### Plan | `event` value | When | | -------------- | ------------------------------------ | | `Plan.Created` | Plan created (one-time or recurring) | | `Plan.Updated` | Plan field or enabled flag changed | ### Subscription | `event` value | When | | ----------------------- | ----------------------------------- | | `Subscription.Created` | Subscription created | | `Subscription.Updated` | Status changes (for example Active) | | `Subscription.Canceled` | Subscription canceled | ### Payment | `event` value | When | | ----------------- | -------------------------------------------- | | `Payment.Created` | Payment created | | `Payment.Updated` | Status transition: treat `Succeeded` as paid | Payments may include nested customer, plan, currency, and `crypto_transaction` (`hash`, `chain_id`) when relevant. ### Invoice | `event` value | When | | ----------------- | -------------------------- | | `Invoice.Created` | Invoice opened | | `Invoice.Overdue` | Invoice past due / dunning | ## Payload conventions Typical fields (vary by type): | Field | Description | | -------------------------- | ------------------------------------ | | `id` | Resource id | | `org_id` / `org` | Owning organisation: always validate | | `status` | Resource status string | | `amount`, `currency` | Monetary fields as strings/codes | | `customer` / `customer_id` | Payer details | | `reference` | Merchant reference when set | | `metadata` | Arbitrary metadata | | `event` | `Type.Action` string | | `payment_method` | e.g. Crypto, Deposit, ProxyWallet | | `crypto_transaction` | On-chain hash / chain when present | ## Filtering noise Some organisations configure notification properties so certain zero-amount proxy-wallet updates are not delivered until paid. Treat the event log as the source of truth for what was attempted. ## Full field reference For exhaustive schemas, use the event document models in the API reference and test against sandbox deliveries. ## Next steps * [Event History and Replay](/webhooks/event-history-and-replay) * [Webhook Best Practices](/webhooks/best-practices) # Webhooks Overview Source: https://docs.boomfi.xyz/webhooks/overview Receive real-time Plan, Subscription, Payment, Invoice, and related events from BoomFi. Webhooks push event payloads to your HTTPS endpoint when objects change in your organisation: for example when a customer completes a payment or a subscription becomes active. They are the primary way to keep your system in sync without polling. ## Why verify every request Payloads include payment amounts and status fields. Anyone who can discover your URL could otherwise POST forged “Succeeded” events. BoomFi signs each delivery with your organisation’s webhook private key. You verify with the **public key** from the dashboard. See [Verify Webhook Signatures](/webhooks/verify-signatures). ## Delivery model 1. An internal event is processed (`Type` + `Action`, for example Payment + Updated) 2. The payload’s `event` field is set to `Type.Action` (for example `Payment.Updated`) 3. Platform POSTs JSON to your org `webhook_url` with signature headers 4. Delivery status is stored (and listed under API & Webhook → Webhooks) If your endpoint does not return a **2xx** status, the delivery is marked failed. Use the dashboard (or events API) to [retry or replay](/webhooks/event-history-and-replay). Manual retries enforce a **60 second** cooldown per event. ## Handler checklist 1. Accept `POST` with JSON body 2. Verify signature + timestamp freshness 3. Confirm `org_id` 4. Branch on `event` 5. Apply business logic **idempotently** 6. Return `2xx` after durable persistence ## Related configuration * Set URL and public key: [Configure Webhooks](/webhooks/setup) * Catalog of events: [Event Types](/webhooks/event-types) * Ops: [Event History and Replay](/webhooks/event-history-and-replay) * Patterns: [Webhook Best Practices](/webhooks/best-practices) # Configure Webhooks Source: https://docs.boomfi.xyz/webhooks/setup Set your webhook URL and manage the webhook signing public key in the dashboard or API. ## Dashboard (recommended) ### Webhook URL and public key Open **Settings → Business**: `https://app.boomfi.xyz/dashboard/settings/merchant` BoomFi business webhook settings * **Webhook URL**: HTTPS endpoint that accepts JSON POSTs * **Webhook public key**: PEM public key used to [Verify Webhook Signatures](/webhooks/verify-signatures) * Use the rotate control to regenerate the key pair if the private key may be compromised Public key text is also shown for copy; PEM newlines may appear escaped (`\n`) in some API responses: normalise to real newlines before verification. ### Event history Open **Settings → API & Webhook → Webhooks** tab: `https://app.boomfi.xyz/dashboard/settings/api-keys?tab=webhooks` BoomFi webhook event history Filter, inspect payloads, retry failed deliveries, and bulk-replay failures. See [Event History and Replay](/webhooks/event-history-and-replay). ## API ### Update organisation webhook URL ```bash theme={null} curl -X PUT "https://mapi.boomfi.xyz/v1/orgs" \ -H "X-API-KEY: sk_test_xxx" \ -H "Content-Type: application/json" \ -d '{ "webhook_url": "https://api.example.com/webhooks/payments" }' ``` Use fields supported by the update organisation schema (name, logo, webhook URL, fee payer, underpay tolerances, email notification settings). See API reference → Organisation. ### Rotate webhook secret / key pair ```bash theme={null} curl -X PATCH "https://mapi.boomfi.xyz/v1/orgs/webhook-secret" \ -H "X-API-KEY: sk_test_xxx" ``` Returns updated organisation material including the new public key material as implemented by the Merchants API. ### Get organisation ```bash theme={null} curl "https://mapi.boomfi.xyz/v1/orgs" \ -H "X-API-KEY: sk_test_xxx" ``` Includes webhook public key when configured. ## Local development Tunnel your local server (for example with a reverse proxy or tunnel tool) so the platform can reach an HTTPS (or tunnelled) URL. Always verify signatures even in development. ## Next steps * [Verify Webhook Signatures](/webhooks/verify-signatures) * [Event Types](/webhooks/event-types) # Verify Webhook Signatures Source: https://docs.boomfi.xyz/webhooks/verify-signatures Verify RSA signatures on outbound webhook deliveries using your org public key. BoomFi signs outbound webhook POST bodies with your organisation’s RSA private key. The corresponding public key is available in the merchant dashboard. Verifying the signature proves authenticity and integrity; checking the timestamp reduces replay risk. ## Headers Every signed delivery includes: | Header | Meaning | | -------------------- | -------------------------------------------------------------------- | | `X-BoomFi-Timestamp` | Unix time (seconds) when the request was signed | | `X-BoomFi-Signature` | Base64-encoded RSA PKCS#1 v1.5 signature over SHA-256 of the message | These header names are platform-level (the same string across white-label deployments). ## Message format ```text theme={null} message = timestamp + "." + raw_request_body ``` * Use the **raw body bytes** as received (the exact JSON posted). Do not re-serialise the parsed object. * The body already includes the `event` field (for example `Payment.Updated`) at send time. ## Algorithms 1. SHA-256 hash the message 2. Verify with RSA PKCS#1 v1.5 against your org **PEM public key** 3. Decode signature as standard Base64 Reference implementation matches Merchants API event signing (`VerifySignature` / `SignMessage` using PKCS#1 private/public keys). ## Steps 1. Read `X-BoomFi-Timestamp` and `X-BoomFi-Signature` 2. Reject if the timestamp is outside your freshness window (for example ±5 minutes) 3. Build `message = timestamp + "." + rawBody` 4. Verify RSA signature with the public key from [Configure Webhooks](/webhooks/setup) 5. Parse JSON only after verification succeeds 6. Confirm `org_id` (or `org.id`) matches your organisation ## Code examples ### TypeScript (Node.js) ```typescript theme={null} import { createVerify, createPublicKey } from "crypto"; function verifyWebhookSignature(opts: { rawBody: string | Buffer; signatureBase64: string; timestamp: string; publicKeyPem: string; }): boolean { const message = `${opts.timestamp}.${opts.rawBody.toString()}`; const verifier = createVerify("RSA-SHA256"); verifier.update(message); verifier.end(); return verifier.verify( createPublicKey(opts.publicKeyPem), opts.signatureBase64, "base64", ); } // Express-style: use express.raw() or capture raw body before JSON middleware export function webhookHandler(req: { body: Buffer; headers: Record; }, res: { status: (n: number) => { send: (s: string) => void } }) { const signature = String(req.headers["x-boomfi-signature"] ?? ""); const timestamp = String(req.headers["x-boomfi-timestamp"] ?? ""); const publicKeyPem = process.env.WEBHOOK_PUBLIC_KEY!.replace(/\\n/g, "\n"); const ts = Number(timestamp); if (!Number.isFinite(ts) || Math.abs(Date.now() / 1000 - ts) > 300) { return res.status(401).send("stale timestamp"); } const ok = verifyWebhookSignature({ rawBody: req.body, signatureBase64: signature, timestamp, publicKeyPem, }); if (!ok) return res.status(401).send("invalid signature"); const payload = JSON.parse(req.body.toString("utf8")); // Assert org_id matches your organisation; handle payload.event idempotently return res.status(200).send("ok"); } ``` ### Python ```python theme={null} import base64 import hashlib from cryptography.hazmat.primitives import hashes, serialization from cryptography.hazmat.primitives.asymmetric import padding from cryptography.exceptions import InvalidSignature def verify_signature(public_key_pem: str, message: bytes, signature_base64: str) -> None: public_key = serialization.load_pem_public_key(public_key_pem.encode("utf-8")) signature = base64.b64decode(signature_base64) public_key.verify( signature, message, padding.PKCS1v15(), hashes.SHA256(), ) def verify_webhook(raw_body: bytes, timestamp: str, signature_b64: str, public_key_pem: str) -> None: message = f"{timestamp}.".encode("utf-8") + raw_body try: verify_signature(public_key_pem, message, signature_b64) except InvalidSignature as exc: raise ValueError("invalid signature") from exc ``` ### Go ```go theme={null} package webhooks import ( "crypto" "crypto/rsa" "crypto/sha256" "crypto/x509" "encoding/base64" "encoding/pem" "errors" "fmt" ) func VerifySignature(publicKeyPEM string, message []byte, signatureBase64 string) error { block, _ := pem.Decode([]byte(publicKeyPEM)) if block == nil || block.Type != "PUBLIC KEY" { return errors.New("failed to decode PEM block containing public key") } publicKey, err := x509.ParsePKIXPublicKey(block.Bytes) if err != nil { return fmt.Errorf("failed to parse public key: %w", err) } rsaPublicKey, ok := publicKey.(*rsa.PublicKey) if !ok { return errors.New("not an RSA public key") } signature, err := base64.StdEncoding.DecodeString(signatureBase64) if err != nil { return fmt.Errorf("failed to decode signature: %w", err) } h := sha256.New() h.Write(message) return rsa.VerifyPKCS1v15(rsaPublicKey, crypto.SHA256, h.Sum(nil), signature) } func VerifyWebhook(rawBody []byte, timestamp, signatureB64, publicKeyPEM string) error { message := append([]byte(timestamp+"."), rawBody...) return VerifySignature(publicKeyPEM, message, signatureB64) } ``` ## Rotate keys Rotate from Business settings or `PATCH https://mapi.boomfi.xyz/v1/orgs/webhook-secret`. Deploy the new public key to all verifiers before or during rotation, depending on your dual-key window. ## Related * [Event Types](/webhooks/event-types) * [Webhook Best Practices](/webhooks/best-practices) # External Account Overview Source: https://docs.boomfi.xyz/whitelist-external-account/overview Register the crypto wallets and bank accounts your payouts are allowed to reach. An **external account** is a payout destination you control, outside BoomFi's custody: a crypto wallet address, or a bank account. Registering one whitelists it: payouts can only send funds to an external account created here. ## Why whitelist first Registering an external account is the sensitive step, not paying out to it afterward: * When you authenticate with a Bearer session, registering requires **step-up verification** (`X-Step-Up-Token`). * Once an account is registered and enabled, payouts to it need no per-request OTP — the whitelisting step already proved you control the destination. * Disabling or deleting an external account immediately stops any future payout (including scheduled automations) from reaching it. Payouts already in flight are unaffected. ## Register a destination Both kinds are registered through the same endpoint, `POST /accounts/external-account`, distinguished by `type`: * [Whitelist a crypto account](/whitelist-external-account/whitelist-crypto-account) — a wallet address on a specific chain. * [Whitelist a fiat bank account](/whitelist-external-account/whitelist-fiat-bank-account) — a bank beneficiary for fiat settlement. ## Addressing a destination Every external account has a `reference` — your own identifier for it — alongside its numeric `id`. A payout can name the destination by either: `destination_account_id` or `destination_account_reference`. An org can register at most one destination per (`reference`, chain) pair: registering the same reference again on the same chain returns **409**. ## Prerequisites * [Authentication](/authentication) (`X-API-KEY`, or a Bearer session with step-up) * A supported currency and, for a crypto account, a supported chain (see [Networks and Currencies](/pricing/networks-and-currencies)) ## Next steps * [Whitelist a Crypto Account](/whitelist-external-account/whitelist-crypto-account) * [Whitelist a Fiat Bank Account](/whitelist-external-account/whitelist-fiat-bank-account) * Once registered and enabled, use the account as a payout destination. # Whitelist a Crypto Account Source: https://docs.boomfi.xyz/whitelist-external-account/whitelist-crypto-account Register a wallet address as a crypto payout destination. Register a wallet you control as a payout destination. See [Overview](/whitelist-external-account/overview) for why registration is the security-sensitive step. ## Register ```bash theme={null} curl -X POST "https://mapi.boomfi.xyz/v1/accounts/external-account" \ -H "X-API-KEY: sk_test_xxx" \ -H "X-Step-Up-Token: " \ -H "Content-Type: application/json" \ -d '{ "type": "Digital", "reference": "treasury-base", "name": "Treasury (Base)", "currencies": ["USDC"], "chain_id": 8453, "address": "0xRecipientWallet…" }' ``` `X-Step-Up-Token` is required when you authenticate with a Bearer session; it is ignored for API-key auth. The account is **enabled** immediately — registering it is the approval. | Field | Type | Required | Description | | ------------ | ------ | -------- | -------------------------------------------------------------------- | | `type` | string | yes | `Digital` | | `reference` | string | yes | Your own reference for this account. Used to address it on a payout | | `name` | string | yes | Display name | | `currencies` | array | yes | One or more currency symbols this address can receive on `chain_id` | | `chain_id` | number | yes | Destination chain id | | `address` | string | yes | Destination wallet address, validated for the chain's address format | A second registration with the same `reference` on the same `chain_id` returns **409**. ## List ```bash theme={null} curl "https://mapi.boomfi.xyz/v1/accounts/external-account?type=Digital" \ -H "X-API-KEY: sk_test_xxx" ``` Returns every registered external account; filter with `?type=Digital` to see only crypto destinations. Response fields for a digital account: `id`, `reference`, `name`, `currencies`, `chain_id`, `address`, `enabled`, `created_at`. ## Remove ```bash theme={null} curl -X DELETE "https://mapi.boomfi.xyz/v1/accounts/external-account/123" \ -H "X-API-KEY: sk_test_xxx" \ -H "X-Step-Up-Token: " ``` Payouts already in flight are unaffected; new payouts can no longer name this account. ## Next steps Once registered and enabled, pay out to this account by its `id` or `reference`. # Whitelist a Fiat Bank Account Source: https://docs.boomfi.xyz/whitelist-external-account/whitelist-fiat-bank-account Register a bank account as a fiat payout destination. Register a bank account you control as a fiat payout destination. See [Overview](/whitelist-external-account/overview) for why registration is the security-sensitive step. ## Register ```bash Business beneficiary theme={null} curl -X POST "https://mapi.boomfi.xyz/v1/accounts/external-account" \ -H "X-API-KEY: sk_test_xxx" \ -H "X-Step-Up-Token: " \ -H "Content-Type: application/json" \ -d '{ "type": "Fiat", "reference": "treasury-eur", "name": "Treasury (EUR)", "currencies": ["EUR"], "account_number": "DE89370400440532013000", "bank_name": "Example Bank", "account_holder_name": "Example Trading Ltd", "country": "DE", "beneficiary_type": "business", "payment_rail": "SEPA" }' ``` ```bash Individual beneficiary theme={null} curl -X POST "https://mapi.boomfi.xyz/v1/accounts/external-account" \ -H "X-API-KEY: sk_test_xxx" \ -H "X-Step-Up-Token: " \ -H "Content-Type: application/json" \ -d '{ "type": "Fiat", "reference": "founder-payout-eur", "name": "Founder payout (EUR)", "currencies": ["EUR"], "account_number": "DE89370400440532013000", "bank_name": "Example Bank", "account_holder_name": "Jane Doe", "country": "DE", "beneficiary_type": "individual", "first_name": "Jane", "last_name": "Doe", "payment_rail": "SEPA" }' ``` `X-Step-Up-Token` is required when you authenticate with a Bearer session; it is ignored for API-key auth. The account is **enabled** immediately — registering it is the approval. | Field | Type | Required | Description | | ------------------------- | ------ | ------------------------ | ------------------------------------------------------------------------------ | | `type` | string | yes | `Fiat` | | `reference` | string | yes | Your own reference for this account. Used to address it on a payout | | `name` | string | yes | Display name | | `currencies` | array | yes | Exactly one settlement currency | | `account_number` | string | yes | Bank account number or IBAN. Encrypted at rest; responses return a masked hint | | `account_holder_name` | string | yes | Legal account holder. Encrypted at rest; responses return a masked hint | | `country` | string | yes | Bank country, ISO 3166-1 alpha-2 | | `bank_name` | string | no | Name of the beneficiary bank | | `beneficiary_type` | string | no | `individual` or `business` (defaults to `business`) | | `first_name`, `last_name` | string | required if `individual` | Beneficiary name | | `business_name` | string | no | Defaults to `account_holder_name` for a business beneficiary | | `payment_rail` | string | no | `SEPA` or `SEPA_INSTANT` (defaults to `SEPA`) | A second registration with the same `reference` returns **409**. ## List ```bash theme={null} curl "https://mapi.boomfi.xyz/v1/accounts/external-account?type=Fiat" \ -H "X-API-KEY: sk_test_xxx" ``` Response fields for a fiat account: `id`, `reference`, `name`, `currencies`, `account_number_hint`, `account_holder_name_hint`, `bank_name`, `country`, `beneficiary_type`, `payment_rail`, `enabled`, `created_at`. The account number and holder name are never returned in full. ## Remove ```bash theme={null} curl -X DELETE "https://mapi.boomfi.xyz/v1/accounts/external-account/123" \ -H "X-API-KEY: sk_test_xxx" \ -H "X-Step-Up-Token: " ``` Payouts already in flight are unaffected; new payouts can no longer name this account. ## Next steps Once registered and enabled, pay out to this account by its `id` or `reference`.