Leepa Developer Docs

Leepa gives your platform crypto payment acceptance and digital wallet capabilities — from a hosted checkout page you can link to in minutes, all the way to a fully headless API where you control every pixel. Pick the integration depth that fits your timeline and your users.

Every product above is available at whichever depth suits your team. You can start shallow and move deeper without re-integrating.

• No-code — share a hosted checkout link, or point users at a wallet. Nothing to build or deploy.
• Low-code — drop a single <script> tag into your site for checkout or a wallet modal.
• API — build fully custom flows against the REST API. You own the entire experience.

Leepa is one platform with two integrable products.

Next step: Which Integration Is Right for Me? → — match your situation to the exact guide.

Start with what you are trying to do. Pick a card for the fast path, or read the tables below to match your exact situation to a guide.

Or match your exact situation to a guide below. Each row names the exact guide and the API reference it maps to.

Accepting payments? → Checkout

Embedding a wallet? → Wallet

Something else?

Next step: Quickstart → — pick a product and run your first call against test mode.

One opinionated path per product, each ending in a working call against test mode. Pick yours:

• Quickstart: Hosted Checkout — create a purchase session and take a test payment.
• Quickstart: Wallet — create a user, provision a wallet, run a transfer in sandbox.

Both assume you have credentials. See Environments & Test Mode to get set up.

Test environment behavior

• Test credentials never work against production, and vice versa.
• The test environment runs on testnet blockchain networks — no real funds are used.
• Recurring payments: production enforces a minimum scheduling frequency of once per day; test allows once per minute.
• Test merchant credentials are provided during onboarding alongside production credentials.

Getting test tokens

To make test payments you need testnet USDC. Use the Circle faucet to mint free USDC on supported testnets:

• faucet.circle.com — supports Ethereum Sepolia, Avalanche Fuji, Polygon Amoy, Base Sepolia, Solana Devnet, and more. Connect your wallet and request tokens — they arrive within seconds. Polygon Amoy is the fastest and cheapest default.

Chain IDs

When it fails

Next step: Making a Test Payment → — run the full payment flow end to end before writing any code.

A concrete, no-code walkthrough for seeing the full payment flow end to end before writing any code.

1. Create or log into your test account at https://test.leepa.africa. This is the account you use to accept and make test purchases.
2. Find your wallet address in your test account settings.
3. Fund your wallet with test USDC before starting checkout: go to faucet.circle.com, select Polygon PoS Amoy, paste your wallet address, and request test USDC. Tokens arrive within seconds.
4. Make a test purchase. Create a product in the dashboard (Products → + Add Product), copy the checkout link it generates, open it, and sign in using the same email as your merchant account to pay.

Verify it worked

When it fails

Next step: Quickstart: Hosted Checkout → — take the same payment programmatically with a purchase session.

Checkout is a hosted payment experience. You create a purchase session (via dashboard or API), your customer completes payment on the checkout page, and you receive a webhook when it settles. You never handle wallet logic, conversion, or settlement yourself.

The customer sees three steps

1. Info

The customer enters their name and email. A returning customer is detected by email and verified with a one-time code (valid for 20 minutes). If they hold a balance covering the purchase, they pay in a single step and skip payment selection entirely — this shortcut is called Fast Track and can be toggled per merchant.

2. Options

The customer picks an enabled payment option: Connect Wallet, Direct Transfer, or Buy Crypto. See Payment Options. If only one option is enabled, this step is skipped.

3. Pay

The order summary shows your platform fee and applicable fees before the customer commits.

What you get: payment confirmation by webhook, settlement in stablecoins, full reporting in the dashboard.

Three independent payment paths. Which ones customers see, and in what order, is configured per merchant. See Per-Merchant Configuration.

Connect Wallet

• The customer pays from a wallet they control — either the Leepa platform wallet or a third-party wallet (MetaMask, Coinbase Wallet, WalletConnect; configurable per merchant)
• Available for one-time and subscription products

Direct Transfer

• The customer sends crypto to a platform deposit address from any source — a personal wallet, an exchange, or anywhere else
• Unique one-time deposit address per purchase, retired after use
• Deposit window 30 minutes by default, configurable
• One-time products only — not available for subscriptions

Networks: Bitcoin, Ethereum, Base, Polygon, Solana, Tron, Ink

The exact assets and networks available depend on your environment and per-merchant configuration — some tokens (e.g. USDG, PYUSD) are enabled in production but not in test.

Buy Crypto

• The customer pays with fiat — credit/debit card, bank transfer, Apple Pay, or Google Pay — which is converted to crypto
• Multiple liquidity providers; identity verification happens inside the onramp flow
• The purchased crypto lands in a wallet created in-flow; whitelabel partners run it branded on their own subdomain (see Hosted Wallet)
• Available for one-time and subscription products

• A recurring session creates an agreement; renewals process automatically, or a unique payment URL is generated if a renewal cannot be processed automatically.
• Minimum billing frequency: once per day in production, once per minute in test.
• Cancel via the dashboard or the Cancel an Agreement endpoint.

Every behavior below is configured per merchant — no deploy or SDK change required on your end. Request changes through your Leepa contact.

Fast Track is the returning-customer shortcut. Once a customer is recognised by email and verified with a one-time code, if they already hold enough balance to cover the purchase they pay in a single step — skipping payment-option selection. Turn it off to always show the full options flow.

From zero to a test payment in four steps.

Prerequisites

• A test Leepa merchant account.
• Your test API-Key and Merchant-ID from Settings → API Keys in the test dashboard.
• An endpoint to receive the Payment Webhook (optional — needed only to confirm payments server-side).

1. Get your test API-Key and Merchant-ID from Settings → API Keys in the test dashboard. See Environments & Test Mode.
2. Create a purchase session from your backend:

curl -X POST https://test-api.leepa.africa/v1/purchase/session/start \
  -H "API-Key: $API_KEY" \
  -H "Merchant-ID: $MERCHANT_ID" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Test product", "details": "A test product", "amount": 9.99, "currency": "USDC" }'

3. Open the url from the response (new tab, modal, or embed) and complete a test payment.
4. Receive the Payment Webhook at your endpoint. Done.

Full field reference: Commerce / Checkout API Reference.

Verify it worked

• The POST returns a session url — open it and complete a test payment.
• After paying, a Payment Webhook fires at your endpoint and the payment appears in the dashboard.

When it fails

Next step: Embedded Checkout → — keep the customer on your own site instead of redirecting out.

The simplest way to accept a payment: create a product in the dashboard and share the generated checkout link. No code required.

Prerequisites

• A test or production Leepa merchant account.
• A product created in the dashboard under Products.

How it works

1. Go to Products → + Add Product in the dashboard.
2. Set the product name, price, and whether it is one-time or recurring.
3. Copy the generated checkout link (e.g. buy.leepa.africa/abc123).
4. Share the link via email, social media, or embed it in a button on your site.

When a customer visits the link, they go directly to the hosted checkout page. Payments are confirmed via webhook and tracked in the dashboard.

Verify it worked

• Opening the link loads the hosted checkout page for the product.
• A test payment appears in the dashboard shortly after it completes.

When it fails

Next step: Purchase Sessions API → — for more control over the checkout flow with dynamic amounts.

Create checkout sessions programmatically; the hosted page does the rest. One backend call, one redirect, one webhook.

Prerequisites

• An API-Key and Merchant-ID from Settings → API Keys. See Generating API keys.
• A webhook endpoint to receive the Payment Webhook.

1. Create a purchase session

Full body fields: Create a Purchase Session.

2. Send the customer to checkout

The response includes a url field. Open it in a tab, modal, or embed.

3. Listen for webhooks

Payment Webhook on success, Failed Payment Webhook on failure. See Webhooks & Events for signing and retries.

4. Recurring payments

A recurring session creates an agreement that renews automatically. Cancel via the dashboard or Cancel an Agreement.

Verify it worked

• The create call returns a url field — open it to reach the hosted checkout.
• A successful payment delivers a Payment Webhook to your endpoint.

When it fails

Next step: Embedded Checkout → — embed the returned url so customers stay on your site.

Keep the customer on your site. Two embed shapes: a button that opens a hosted checkout in a new context, and a full iframe that never leaves your page. Both start from a product created in the dashboard, or a purchase session for dynamic amounts.

Prerequisites

• A product created in the dashboard (its ID becomes data-id or the checkout link), or a purchase session for dynamic amounts.
• A page on your site where you can add the script tag or iframe.
• An endpoint to receive the Payment Webhook that confirms completion.

Button Embed

Best for low-code teams: a single script tag renders a payment button.

<script
  class="crypto-button-script"
  data-id="YOUR_PRODUCT_ID"
  data-color="#0484fc"
  src="https://buy.leepa.africa/djs/button.js"
></script>

data-id is the product ID from the dashboard; data-color sets the button background — its label colour is computed automatically for contrast, so light and dark brand colours both stay readable.

Two optional attributes tailor the button:

• data-mode — light (default) or dark, controlling the button's branding row.
• data-customer — a JSON object of customer details, passed through to checkout to prefill the form (submitted as a hidden customerData field). Supplying email, firstName and lastName skips the personal-information step for known customers.

<script
  class="crypto-button-script"
  data-id="YOUR_PRODUCT_ID"
  data-color="#0484fc"
  data-mode="dark"
  data-customer='{"email":"jane@example.com","firstName":"Jane","lastName":"Doe"}'
  src="https://buy.leepa.africa/djs/button.js"
></script>

iFrame Embed

Best for keeping the customer fully inside your UI. Point the iframe at your checkout link.

<iframe
  src="https://buy.leepa.africa/YOUR_PRODUCT_ID"
  allow="clipboard-read *; publickey-credentials-create *; publickey-credentials-get *"
></iframe>

The allow attributes are required for wallet-connect and passkey flows inside the frame. No sensitive payment data touches your page, and no postMessage bridge is needed on your side.

Completion: both shapes confirm via the same Payment Webhook, not a postMessage event. For dynamic amounts, embed the url returned from a Purchase Session the same way.

Verify it worked

• The button or iframe renders on your page and opens the hosted checkout.
• Completing a test payment delivers a Payment Webhook to your endpoint.

When it fails

Next step: Test customer demand → — gauge interest in crypto payments before you go live.

Leepa provides a WooCommerce plugin that adds crypto payment acceptance to any WooCommerce store. No custom code required.

Prerequisites

• A WordPress site with WooCommerce installed and active.
• A Leepa merchant account and an API key from Settings → API Keys.

Installation

1. Download the Leepa WooCommerce plugin from the dashboard under Settings → Integrations.
2. Install the plugin in your WordPress admin under Plugins → Add New → Upload Plugin.
3. Activate the plugin and go to WooCommerce → Settings → Payments.
4. Enable Leepa and enter your API key.

Once configured, customers see Leepa as a payment option at checkout. Payments are confirmed via webhook and tracked in the Leepa dashboard.

Verify it worked

• Leepa appears as a payment method on the WooCommerce checkout page.
• A test order confirms via webhook and appears in the Leepa dashboard.

When it fails

Next step: Test customer demand → — measure interest in crypto payments before enabling it store-wide.

The Crypto Interest & Engagement Button allows you to measure customer interest in paying with cryptocurrency before launch. By integrating this button, you can collect customer interactions, emails, and waitlist sign-ups — all without processing any payments immediately.

• Log in to your Leepa Dashboard.
• Go to Settings → API Keys.
• Copy your Merchant ID.

Place the following script anywhere in your HTML:

The button can be fully customized using the data-* attributes. You can customize the look of your buttons to match your website's style.

Use the APIs below to collect data about user engagement and interest. This feature is currently restricted to the test environment.

Gets the total interest button click count.

Gets the total interest button click count with interval (in days).

Gets the total interest button click count with details about collected emails, consent, and user location breakdown.

Get all emails collected from the interest button.

Get all user collected data (regionality, cart size, products metadata, etc.).

Leepa Wallet gives your users a complete branded wallet — deposits, transfers, and withdrawals — with no wallet infrastructure to build. Same rails across modes; you choose how much frontend you own.

flowchart TB
  subgraph HOSTED["Hosted Wallet"]
    direction LR
    H1["Frontend UI"]:::ours
    H2["Wallet infrastructure"]:::ours
    H3["Chain and gas"]:::ours
    H1 ~~~ H2 ~~~ H3
  end
  subgraph EMBED["Embedded Button"]
    direction LR
    E1["Frontend UI (your page, our modal)"]:::shared
    E2["Wallet infrastructure"]:::ours
    E3["Chain and gas"]:::ours
    E1 ~~~ E2 ~~~ E3
  end
  subgraph HEADLESS["Headless (Wallet API)"]
    direction LR
    F1["Frontend UI"]:::yours
    F2["Wallet infrastructure"]:::ours
    F3["Chain and gas"]:::ours
    F1 ~~~ F2 ~~~ F3
  end

  classDef ours fill:#0484fc,stroke:#0366c9,color:#ffffff;
  classDef yours fill:#e9eef6,stroke:#9aa7bd,color:#1f2a3a;
  classDef shared fill:#bfe0ff,stroke:#0484fc,color:#0b3b66;
      

Start hosted or embedded. Headless is for strict-UX teams with dedicated engineering. See Headless Wallet: When to Use the API.

Next step: Embedded Wallet Button → — add a wallet to your own site with one script tag and a single call.

Run the full wallet on your own subdomain, themed to your brand. Deepest whitelabel. Zero frontend build.

1. Choose a subdomain (e.g. wallet.yourdomain.com).
2. Point a CNAME at the Leepa-hosted wallet (target provided during onboarding; SSL handled by us).
3. Send branding assets: your onboarding contact provides the required asset list.
4. We configure infrastructure and apply branding.
5. The wallet goes live on your subdomain.

Verify it worked

When it fails

Next step: Embedded Wallet Button → — add a wallet modal inside your own site with one script tag.

Hosted Wallet, above, runs the whole wallet on your subdomain. These are the other three ways to integrate — same rails, you choose how much frontend you own.

The Embedded Wallet is a Leepa-hosted wallet that opens in a modal on your own site. You add one <script> tag; a wallet button appears; when a visitor clicks it, a secure modal opens in-place — no redirect, no new tab, no app to download. Inside that modal the visitor authenticates with a passkey and moves stablecoins.

You build no wallet UI and hold no keys. Leepa hosts the wallet, runs the signing infrastructure, and secures the passkey. Your job is two calls: render the script tag, and (optionally) create a prefill session from your server first.

The modal runs in one of two modes:

• Anonymous — no prefill. The visitor enters everything themselves: who to pay and how much. Use this when you just want to drop a working wallet onto a page.
• Prefilled — your server set the destination (and optionally the amount) in advance. The modal opens straight to the send screen with those values locked in; the visitor only authenticates and confirms.

This page covers money coming in: a visitor authenticates in the modal and sends funds to a destination your server chose. Paying money out from your merchant wallet to a user is a different integration — a server-side call with no modal and no user interaction. See Disbursements: Paying Your Users.

• A Leepa merchant account with an API key that has the wallet_embed permission — write to create prefill sessions, read to fetch balance tokens.
• Server-side code to call the prefill endpoint. Never call it from the browser.

Anonymous mode is enough for a general-purpose wallet, but most integrations know exactly where the money should go — a specific invoice, a specific payout. Prefill solves that: it turns a multi-step payment into a single click and guarantees the destination is the one you chose, not something the visitor typed. The visitor never picks the recipient or the amount; they only authenticate and confirm.

The full sequence is six steps:

1. Your server calls POST Create Prefill Session with the recipient email (plus optional memo and amount), authenticated with your wallet_embed key.
2. Leepa creates a short-lived prefill session and returns an embed_code UUID.
3. Your server renders the page, injecting that embed_code as the data-embed-key on the embed script tag.
4. The visitor clicks the wallet button; the modal opens on the send screen, pre-loaded with the recipient (and amount, if you set one).
5. The visitor authenticates with a passkey — becoming the sender — and confirms the transfer.
6. Leepa settles the transfer and delivers an embed_transfer webhook to your endpoint, which you reconcile against your own record.

Session lifecycle. An embed_code points at a single short-lived prefill session. Treat it as single-use: mint a fresh embed_code per authenticated page load rather than caching one and reusing it across visitors or page views. Don't embed a long-lived code in a static page.

A disbursement sends funds from your wallet to one of your users. It is a single server-to-server call — no modal, no wallet UI, and nothing for the recipient to do. You name the recipient by email (or by your own user id) and the USD amount; Leepa signs and settles it on your behalf using the signing key you granted.

This is the opposite direction from the Embedded Wallet, and a different integration entirely — that one is an in-browser modal where a visitor authenticates to send you money. Do not use a prefill session to pay a user.

Typical uses (name them however fits your product):

• Marketplace seller payouts
• Contractor and freelancer payments
• Refunds
• Rewards and loyalty credits
• Affiliate commissions
• Prizes and winnings

• A Leepa merchant account with an API key holding the merchant_wallet_transfers permission — write to create disbursements, read to query them. See Generating API keys.
• A granted Leepa signing key whose allowance covers the amounts you intend to send. Without it every call fails with no_signing_key.
• A funded wallet.
• The recipient must have completed wallet signup.

Nothing is required of them for the money to arrive — the funds land in a Leepa wallet tied to their email. When they next open the wallet, they can hold the balance, send it onward, or cash out. Telling them it arrived is your job: send your own notification.

They must have completed wallet signup first. Unlike a prefill — where a first-time visitor provisions a wallet by authenticating in the modal — a disbursement has no interactive step in which that can happen, so an unregistered recipient is rejected up front with recipient_not_registered (or recipient_not_found if no account exists at all). Onboard the user before paying them.

These are returned inline on the POST, because they are yours to fix. Anything that fails after acceptance does not appear here — it surfaces as failed on the status endpoint plus a failed_wallet_transfer webhook.

This page assumes you used Which Integration Is Right for Me? and chose wallet + headless. You build your own frontend against the Wallet API. Maximum control, more engineering effort.

Headless is the right call if you are:

• A consumer wallet with a mature design system
• Extending an existing card-on-file UX you own
• Required to place custom compliance disclosures inside the flow
• A brand that demands a fully native experience
• Able to dedicate engineering for weeks, not days

If none apply, use a hosted or embedded mode. Before you start, read Signing & Recovery — the hardest integration step. Contact us before committing.

Next step: Wallet Quickstart → — provision a wallet and run your first transfer against the API.

https://wallet.leepa.africa is a fully featured, self-custodial digital wallet your users can access from any device — no app download, no seed phrase, no integration work on your side. A user visits the URL, registers with their email and a passkey, and gets a wallet with full money-movement capabilities in under a minute.

This is the fastest path to giving users a production-ready wallet. Share the link in an onboarding email, embed it as a button in your app, or print it as a QR code — there is nothing to build or deploy.

Provision a user wallet and run a peer-to-peer transfer in sandbox.

Prerequisites

• An API key and Merchant-ID with Wallet API access — see Generating API keys.
• The DFNS WebAuthn client SDK wired into your frontend for the passkey signing steps — see Signing & Recovery.

1. Create your operator — set default chain, default token, and whitelisted addresses.
2. Create a user: call POST /v1/wallet/users/init → sign the passkey challenge on the client → POST /v1/wallet/users/complete. Store the returned recoveryCode.
3. Provision a wallet: POST /v1/wallet/ with { "user_id": "…", "type": "user" }.
4. Run a transfer: POST /v1/wallet/transactions/init → sign → /complete → sign → /permit. Payment processes.

Step 1 is a single server-side call. Create your operator:

curl -X POST https://api.leepa.africa/v1/wallet/operator \
  -H "API-Key: $API_KEY" \
  -H "Merchant-ID: $MERCHANT_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My App Operator",
    "preferred_chain": 2,
    "preferred_token": 2,
    "whitelisted_addresses": ["0x215e3953a1bcb368dF42a23eb62cd4A72bf66181"]
  }'

{
  "data": {
    "id": "ed8c502f-5575-46c5-9a3f-22b278638aa7",
    "merchant_id": "959ee38b-2d68-4717-9144-71afa5dbb8f2",
    "name": "My App Operator",
    "network_id": 2,
    "token_id": 2,
    "whitelisted_addresses": ["0x215e3953a1bcb368dF42a23eb62cd4A72bf66181"]
  },
  "status": 200
}

Verify it worked

• The operator create call returns 200 with an id in the response body.
• The transfer completes and a wallet-transfer webhook fires to your registered endpoint.

When it fails

Next step: Signing & Recovery → — the passkey init → sign → complete pattern is the hardest part of the integration.

Wallet users are non-custodial and secured by a passkey (WebAuthn / FIDO2). Sensitive actions — user creation, transfers, recovery — are authorized by signing a challenge with the user's passkey on their device.

The init → sign → complete pattern

1. init: you call the endpoint; the API returns a challenge plus a challengeIdentifier / temporaryAuthenticationToken.
2. sign: your client signs the challenge with the user's passkey using the wallet client SDK (DFNS WebAuthn SDK).
3. complete: you submit the signed challenge to the matching /complete endpoint.

Transfers add a second signature (an ERC-2612 token permit): init → sign → complete → sign → permit. See Transactions.

Recovery

At user creation Leepa returns a one-time recoveryCode — surface it to the user for safekeeping. If they lose their device, the recovery flow restores access with that code and registers a new passkey credential.

What your frontend owns

• Collecting passkey credentials at wallet creation and at every transaction signature
• Running the WebAuthn ceremony (navigator.credentials.create() / .get()) via the DFNS SDK
• Handling EIP-712 typed data for on-chain transfers
• Implementing the recovery flow for users who lose their passkey device

When it fails

Next step: Payouts Quickstart → — put signing to work sending funds out to your users.

Send crypto from your merchant wallet to a customer or external address. Payouts can be initiated from the merchant dashboard (no code required) or via the Create Transfer Request API. Transfers within your configured daily allowance execute without an additional signature; larger amounts trigger an on-chain signing step.

A Leepa merchant platform lets you onboard sub-merchants, configure per-account fee structures, and view consolidated earnings — all from the dashboard, no API key required to get started. Each step also links to its API equivalent for programmatic automation.

Two product APIs share one host and auth model, separated by path:

• Wallet API — the wallet API (/v1/wallet/*): operator, users, wallets, transactions, recovery.
• Commerce / Checkout API — checkout/commerce (/v1/purchase/*): purchase sessions, agreements, payments, subscriptions, fees.

Start with Core Concepts for cross-cutting behavior (errors, rate limits, pagination, versioning, webhooks) that applies to both.

Base URLs

All requests must be made over HTTPS. See Authentication to authorize requests.

Cross-cutting behavior that applies to both the Commerce / Checkout API and the Wallet API.

The API uses standard HTTP status codes. Errors return a JSON body with an error_type, error_code, and message field. Split synchronous API errors from asynchronous webhook-delivered failures.

Each API key is rate-limited to 100 requests per minute by default, measured over a rolling 60-second window. Every response carries the current window state in its headers:

• x-ratelimit-remaining — requests left in the current window
• x-ratelimit-reset — seconds until the window resets
• x-ratelimit-window — window length in seconds (60)

Exceeding the limit returns 429 with body { "error": "Rate limit exceeded" }. Back off until the window resets. If you need a higher limit, contact the Leepa support team.

List endpoints return a pagination object alongside the results. Request a page with query parameters; read the totals from the response.

GET /v1/wallet/users/{user_id}/transactions?page=1&page_size=20

Response

{
  "data": {
    "pagination": { "page": 1, "page_size": 20, "total_count": 2, "total_pages": 1 },
    "transactions": [ "…" ]
  }
}

The API is versioned via the URL path (/v1/). Breaking changes are introduced in new versions. The current version is v1.

Asynchronous outcomes (payment settled, payment failed, wallet transfer completed) are delivered to your registered webhook endpoint. Handle them idempotently — events may be retried or arrive out of order.

Event catalog

Configuring your webhook URL

Dashboard: Settings → Merchant Settings, enter your webhook URL. As a platform managing sub-merchants, configure a connected account's endpoint via Create Webhook instead of asking them to self-serve.

Signature verification (HMAC-SHA256)

When signing is enabled, every delivery includes three headers:

• X-Webhook-Timestamp — Unix seconds
• X-Webhook-Signature — base64 HMAC
• X-Webhook-Signature-Version — v1

signature = base64( HMAC_SHA256( signing_secret, timestamp + "." + raw_body ) )

1. Read the raw request body bytes exactly as received — do not parse and re-serialize first.
2. Build timestamp + "." + raw_body and compute the HMAC.
3. Compare to X-Webhook-Signature using constant-time comparison.
4. Reject stale timestamps outside your replay window (5 minutes recommended); allow limited clock skew.

Deduplication

Every delivery includes an X-Event-Id header uniquely identifying that trigger. Multiple active webhooks on the same merchant each get an independent delivery; multiple active webhooks pointed at the same URL can produce duplicate deliveries at that URL — dedup on X-Event-Id. Failed-payment retries share a payment_id but each attempt gets its own X-Event-Id.

Base URL

Authentication

Response envelope

{ "data": { ... }, "status": 200 }

The model

• Operator — merchant config: default chain, default token, whitelisted addresses. See Operator.
• User — an end user, secured by a passkey. See Users.
• Wallet — the on-chain wallet provisioned for a user. See Wallets.

Sensitive actions use the init → sign → complete passkey pattern. See Signing & Recovery.

Merchant-level wallet config: default chain, default token, whitelisted addresses. One per merchant.

End users. Creation is a two-step passkey flow (init then complete). See Signing & Recovery for how the challenge is signed on the client.

The on-chain wallet provisioned for a user: address, network, managed signing key.

Peer-to-peer transfers. Three-call signed flow: init → complete → permit. See Signing & Recovery for the passkey signing steps.

Passkey recovery for wallet users. See Signing & Recovery for the full background on the recoveryCode and when to trigger this flow. Signing blobs come from the DFNS WebAuthn SDK on the client.

Purchase Sessions are the starting point for any payment flow on Leepa. A session holds all the details about a payment request — the amount, currency, product info, and configuration for one-time or recurring billing.

Once created, the session returns a hosted checkout URL that you can redirect the customer to, embed in an iframe, or open in a modal. For headless flows, you can use the session ID to request a typed data message and handle signing directly in your own UI.

The Create endpoint allows you to create a new payment request and retrieve URLs for making and monitoring payments. If the request is associated with an agreement, the system first checks whether it can be automatically processed according to the agreement rules. If it cannot be processed automatically, a unique payment URL will be generated where the user can complete the payment manually.

In production, the minimum scheduling frequency for recurring payments is once per day. In the test environment, you can schedule as frequently as once per minute for development and testing.

**Skip the personal-information step:** if you pass the buyer's identity in `metadata` — `email`, `firstName`, and `lastName` (all three, valid) — checkout registers the buyer for you and sends the payer straight to payment, skipping the personal-information form.

Returns the status of a specific purchase session.

Delete a specific purchase request.

Force expires a specific purchase session.

Purchase Messages enable a fully headless, signature-based payment flow. Instead of redirecting the customer to the hosted checkout UI, you request a typed data message (EIP-712) and present it to the user's wallet for signing — giving you complete control over the checkout experience.

Once the user signs the message, submit it back to Leepa for processing. If the user hasn't yet approved the smart contract to spend their token, the response will include a permit message in typed data format for the approval step.

The Request Message endpoint allows users to create a new message that can be cryptographically signed by your users using signedTypeData methods. This allows you to configure a purchase session and sign that purchase session agreement, or pass that agreement along to your users for them to sign, bypassing the need to use our checkout user interface.

If we can't process the request automatically, we'll create a unique payment URL where the payment can be made.

The Submit Signed Purchase Message endpoint allows you to submit signed messages for processing. If the user has already approved our network smart contract to spend their token then we can immediately process the payment.

If they need to approve our smart contract we will notify you and provide relevant information to complete the approval process. If token approval does not exist, the response will be permit message typed data.

A short demo on how to sign a message using EIP-712 is available here: CodeSandbox EIP-712 Demo.

Permit messages enable gasless token approvals by allowing users to sign an off-chain message that authorizes Leepa's smart contract to spend their tokens. Instead of requiring an on-chain approval transaction — which costs gas — users can simply sign a structured message with their wallet. This reduces friction at checkout and makes the payment process faster and more cost-effective.

When you submit a signed purchase session, Leepa checks whether the user has already approved token spending. If so, the payment is processed immediately. If not, the response will include a permit message in typed data format. You can present this message to the user for signing. Once signed, submit it to Leepa to complete the approval and proceed with the transaction — all without requiring an additional on-chain approval step.

The Submit Signed Permit Message endpoint enables you to submit the signed permit message from your user that gives our smart contract the ability to spend their tokens. Once we confirm the validity of the signed permit message we will process the related purchase session transaction.

A short demo on how to sign a message using EIP-712 is available here: CodeSandbox EIP-712 Demo.

Payment agreements generate recurring payments through Leepa's payment network based on pre-defined agreements signed by the customer. The customer is required to agree to any changes to a payment agreement.

Retrieve an agreement for your account or a connected account.

List all agreements for your account or a connected account.

Cancel an active recurring agreement so it stops renewing. Requires write access on the Purchase Sessions resource.

Paginated version of the agreements list. Use this endpoint for large result sets.

Payments represent transactions that merchants receive from their customers. Each payment record contains the amount, currency, transaction status, customer details, and what was purchased — whether a one-time payment or part of a recurring subscription.

Use the Payments API to view your complete payment history, look up specific transaction details, and monitor payment statuses across your account and connected accounts.

Retrieve a payment by its payment_id. A payment belongs either to your account or a connected account.

If a payment has multiple consecutive charge attempts that fail due to insufficient user balance, the metadata object will include a failed_dates array listing the timestamps of each failed attempt.

List all payments for your account or a connected account. You can filter results by agreement, status, or both.

Paginated version of the payments list. Use this endpoint instead of v1 for large result sets. Returns up to 200 records per page.

The v1 endpoint redirects to this endpoint if the result set is too large.

A product is a digital offer created by a merchant that users can purchase in exchange for access to a service, benefit, or digital experience. While many products are traditional subscriptions, they can also represent one-time access or single-purchase offerings.

• Merchant-Defined: Each product is owned and managed by a specific merchant, who determines its pricing, duration, and usage.
• Flexible Pricing: Products are priced in USD but payment may be made using crypto, supporting both recurring subscriptions and one-time purchases.
• Blockchain Integration: Payments are directed to a dedicated blockchain address, enabling secure on-chain transactions.
• Lifecycle Status: Products can be active, inactive, or discontinued, giving merchants full control over their offerings.

List all products for your merchant account.

List all active subscriptions and one-time purchases for a specific subscriber.

Check whether a specific subscriber has an active subscription to a given product.

Check the subscription status of a subscriber based on metadata. Returns one of three states: active subscription, inactive subscription, or no matching subscription found.

Paginated version of the product list. Use this endpoint when you have many products.

Leepa Merchant Wallets are secure, non-custodial wallets powered by DFNS's battle-tested wallet infrastructure. Designed with robust key management and WebAuthn-based authentication, these wallets ensure enterprise-grade security without exposing private keys or relying on vulnerable seed phrases.

With Merchant Wallets, Leepa merchants don't need to connect external wallets or manage third-party integrations. Everything is built-in — making on-chain payments, managing funds, and receiving crypto subscriptions frictionless and secure, straight from your dashboard.

Merchant wallets on the platform support two types of credentials:

Traditionally, sending crypto funds requires users to pay gas fees using the native token of the blockchain — for example, ETH on Ethereum or MATIC on Polygon. To remove this barrier, we've introduced gasless transfers — a seamless way to send funds without needing to hold or spend native tokens.

Gasless transfers can be executed in two ways:

To initiate a new transfer you must provide the following parameters: to_address (the recipient's email address registered with the platform, or wallet address — use the same email used when creating a purchase session), amount (amount of tokens to transfer), chainId (ID of the target blockchain), and token (symbol of the token being transferred, e.g. USDC, USDT, PYUSD).

This endpoint transfers funds directly to the recipient without requiring any signatures from the merchant. If the amount exceeds the allowance set on the Wallet Security page, the API will not process the transfer.

The Create Transfer endpoint processes funds directly without requiring a signature — as long as the transfer amount is within your configured allowance. If the amount exceeds the limit set on the Wallet Security page, the API will not process the transfer.

If your transfers regularly exceed the default $100 limit, you have two options:

Accounts are the basic organizations that use Leepa services. They can be individuals, businesses, or non-profit organizations. They can have one or more users associated with them, and they can be connected to other accounts.

Creating an account through the API will connect that account with your account, enabling you to call the API as that account in the future. This allows a platform account the ability to onboard users, and configure products and payment agreements for their users.

As a platform merchant, you can create accounts for your users (submerchants). If you've already collected information for your connected accounts, you can prefill that information here and we won't ask for it again during onboarding.

If you need to set up a wallet address for your users, send it in the default_deposit_address field. Leave it empty and the user will be guided to create their own wallet when they sign up.

Resends the verification email to a submerchant if it was not received. This endpoint has a 20-minute cooldown period between requests.

Update a connected submerchant account. To update your own account use the dashboard.

Retrieves the full details of a connected submerchant account.

Removes a connected submerchant account from your organization. Authenticate as the PARENT account and put the submerchant's ID in the path — a submerchant cannot delete itself.

There are two outcomes, both 200. `deleted` is true for both — the request succeeded either way. Read `unlinked` to tell which one happened.

**Deleted** — an account that has never traded is removed outright, along with its API keys. You do not need to disable the keys first. The delete is atomic: if anything blocks it, the account is left exactly as it was, still reachable from you, and the call can be retried once the blocker is cleared.

**Unlinked** — an account with payments, agreements, subscription products, purchase sessions, referrals or a wallet balance is never destroyed; those records are kept. It is detached from your organization instead. It stays a working merchant, its API keys keep authenticating, and it will no longer appear under `list_accounts`. Disable its API keys BEFORE calling this if you want them dead, because once unlinked you can no longer address the account through the API.

Retrieves a list of all submerchant accounts connected to your platform account.

Creates a new API key for a connected submerchant account. The returned key can be used to authenticate API requests on behalf of that account.

Retrieves all API keys for a connected submerchant account, along with their current status.

Disables an API key for a connected submerchant account. Disabled keys can no longer be used to authenticate requests.

Authenticate as the PARENT account (its API key and its Merchant-ID header) and put the SUBMERCHANT's ID in the path. A submerchant cannot disable its own keys through this endpoint — that combination returns 403. Note this differs from the webhook endpoints below, which are authenticated by the account that owns the webhook.

Returns 404 if the submerchant is not a connected account of the caller, or if the key does not belong to that submerchant. A 200 means a key was actually disabled.

Creates a webhook endpoint for a connected submerchant account. By default all events for that account are sent to the provided URL.

Use subscribed_event_types to have this endpoint receive only a subset of event types. Omit it (or send an empty list) to receive all events.

Returns a signing_secret once at creation time. Store it securely; it will not be returned again.

Authenticate with the API key of the account that owns the webhook — the submerchant's own key and its own ID in the path. The parent's key is rejected here, unlike the API key endpoints above.

Updates a webhook's URL and/or its per-endpoint event-type subscription for a connected submerchant account.

Only the fields you send are changed. Send subscribed_event_types as an empty list to clear the filter so the endpoint receives all events again.

Disables a webhook for a connected submerchant account. No further events will be delivered to the webhook URL once disabled.

Rotates the signing_secret for a webhook belonging to a connected submerchant account.

Returns the new signing_secret once. Store it securely; it will not be returned again.

Retrieves all webhooks registered for a connected submerchant account, including their current status and per-endpoint event-type subscription.

A null or empty subscribed_event_types means the endpoint receives all events.

Secrets are never returned by this endpoint.

Paginated version of the connected accounts list. Use this endpoint for platforms with large numbers of submerchants.

The v2 item shape is NOT the same as v1. `merchant_id` is a bare UUID (v1 prefixes it with `mrch_`), `object` is `merchant` (v1 says `account`), the emails are `business_email` and `individual_email` (v1 uses `email` for both), and branding is split into `color_r`/`color_g`/`color_b` (v1 returns a single `brand_color` hex). The paginated array is under `data`, not `accounts`.

Paginated version of the API key list for a submerchant. Useful for accounts with many keys.

The paginated array is under `data`. Each item carries the same fields as the v1 endpoint.

The Fees & Earnings endpoints expose how the platform calculates, distributes, and records transaction fees across merchants, resellers, and the platform. Fees are structured in multiple layers:

• Customer Percent — charged to buyers at the point of purchase.
• Merchant Percent — deducted from the merchant's settlement amount.
• Platform Percent — reserved for the platform (fixed, not configurable).

After settlement, fees are allocated across the merchant hierarchy and recorded as immutable earnings entries, including payment amounts, costs, merchant earnings, currency, payment type, and timestamps. These records support financial reporting, reconciliation, and aggregation over any time range.

Get the effective fee structure for the merchant, including any inherited defaults used for pricing and earnings calculations.

Update the merchant's fee structure for a specific transaction type (customer/merchant percent and network-fee inclusion). Platform percent is fixed by the system and cannot be changed.

Returns a paginated list of fee earnings for the authenticated merchant, grouped by payment. Each item is a summary view including payment amount, total fee cost, merchant earnings, currency, and timestamps.

Only MERCHANT earnings are returned for the merchant tied to the API key. This endpoint is intended for finance reporting, reconciliation, and aggregation over a specified time range.

Webhooks allow real-time communication between systems. They are used to synchronize disparate systems by publishing automated messages with predefined payloads that can be interpreted by integrated systems — enabling instant updates and data sharing without continuous polling.

Our platform webhooks provide notifications when specific actions occur on your account, such as when a customer subscribes to a product, purchases a one-off product, makes a payment, or cancels a subscription. By setting up webhooks, you can automate processes and keep your systems in sync with our platform in real-time.

The webhook is triggered during the following actions:

• When a customer subscribes to a recurring product.
• When a customer purchases a one-off product.
• When a customer makes a payment.
• When a customer cancels a subscription.
• When payment processing fails (e.g. insufficient customer balance).
• When you execute a wallet-to-wallet transfer from your account.

Choosing events per endpoint

Each endpoint can subscribe to a subset of event types. If you don't select any, the endpoint receives all events — this is the default, and it matches the behavior of any endpoint created before per-endpoint selection existed. Select event types on the Webhooks page, or set subscribed_event_types via the API (see Accounts & API Keys).

The available event-type identifiers are:

Webhook Event Uniqueness

Every webhook includes an X-Event-Id header that uniquely identifies a specific trigger/event. For failed payments, multiple charge attempts may be associated with the same payment_id — each attempt still gets its own unique X-Event-Id.

Webhook deliveries can be signed with HMAC-SHA256. When enabled, each webhook request includes:

• X-Webhook-Timestamp (unix seconds)
• X-Webhook-Signature (base64-encoded HMAC)
• X-Webhook-Signature-Version (v1)

Verification contract

Webhook signatures are computed over the exact request body bytes sent on the wire.

Signing input:

signature = base64(HMAC_SHA256(signing_secret, timestamp + "." + raw_body))

Where:

• timestamp is the exact ASCII string sent in X-Webhook-Timestamp
• . is a literal period byte
• raw_body is the exact HTTP request body bytes as received, before any parsing or modification

Required consumer behavior

Consumers must verify the signature using the exact raw HTTP request body bytes. Do not verify against a parsed JSON object, a re-serialized JSON string, pretty-printed/normalized JSON, or reordered keys.

Verification steps

• Read the raw request body bytes exactly as received.
• Read X-Webhook-Timestamp.
• Build the signed payload as: <timestamp> + "." + <raw_request_body_bytes>
• Compute base64(HMAC_SHA256(signing_secret, signed_payload)).
• Compare to X-Webhook-Signature using constant-time comparison.
• Reject requests with stale timestamps outside your replay window (for example, 5 minutes) and allow limited clock skew.
• Only parse the JSON body after signature verification succeeds.

Verification examples

Copy-paste starting points. Each reads the raw body, recomputes the signature, and compares it in constant time. Replace signingSecret with the secret returned when you created the webhook.

Go

package webhookverify

import (
	"crypto/hmac"
	"crypto/sha256"
	"encoding/base64"
	"strconv"
	"time"
)

// Verify returns true when the signature header matches the raw body.
// timestampHeader is X-Webhook-Timestamp; signatureHeader is X-Webhook-Signature.
func Verify(signingSecret, timestampHeader, signatureHeader string, rawBody []byte) bool {
	// Reject stale timestamps (replay protection); allow limited clock skew.
	ts, err := strconv.ParseInt(timestampHeader, 10, 64)
	if err != nil {
		return false
	}
	if time.Since(time.Unix(ts, 0)) > 5*time.Minute {
		return false
	}

	mac := hmac.New(sha256.New, []byte(signingSecret))
	mac.Write([]byte(timestampHeader))
	mac.Write([]byte("."))
	mac.Write(rawBody)
	expected := base64.StdEncoding.EncodeToString(mac.Sum(nil))

	return hmac.Equal([]byte(expected), []byte(signatureHeader))
}

Node.js

const crypto = require("crypto");

// rawBody must be the exact bytes received (a Buffer or string), NOT a re-serialized object.
// In Express, capture it with: express.json({ verify: (req, _res, buf) => { req.rawBody = buf; } })
function verify(signingSecret, timestampHeader, signatureHeader, rawBody) {
  const ageSeconds = Math.floor(Date.now() / 1000) - Number(timestampHeader);
  if (!Number.isFinite(ageSeconds) || Math.abs(ageSeconds) > 300) return false; // 5-min replay window

  const mac = crypto.createHmac("sha256", signingSecret);
  mac.update(timestampHeader);
  mac.update(".");
  mac.update(rawBody);
  const expected = mac.digest("base64");

  const a = Buffer.from(expected);
  const b = Buffer.from(signatureHeader);
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

Python

import base64
import hashlib
import hmac
import time

# raw_body must be the exact bytes received (bytes), not a re-serialized dict.
# In Flask, use request.get_data() (do NOT use request.json here).
def verify(signing_secret: str, timestamp_header: str, signature_header: str, raw_body: bytes) -> bool:
    try:
        age = time.time() - int(timestamp_header)
    except (TypeError, ValueError):
        return False
    if abs(age) > 300:  # 5-minute replay window
        return False

    signed = timestamp_header.encode() + b"." + raw_body
    mac = hmac.new(signing_secret.encode(), signed, hashlib.sha256)
    expected = base64.b64encode(mac.digest()).decode()

    return hmac.compare_digest(expected, signature_header)

Your signing_secret is returned once when you create a webhook. If you need to rotate it, use the Rotate Webhook Secret for connected account endpoint under Accounts & API Keys.

We currently deliver eight event types: Recurrence Signup, Payment, Failed Payment, Subscription Cancellation, Wallet Transfer, Failed Transfer, Embedded Wallet Transfer, and Headless Wallet Transfer.

Each event carries a type field that identifies it. Always branch on type rather than on payload shape, since some events share fields.

When a customer agrees to make recurring payments, the webhook sends the following data. Note that other than the first_payment_id, there is no information about the first payment made — payment information is sent as a separate payment event.

If webhook signing is enabled, requests include X-Webhook-Timestamp, X-Webhook-Signature, and X-Webhook-Signature-Version: v1. Verify against the exact raw request body bytes (before JSON parsing): base64(HMAC_SHA256(signing_secret, timestamp + "." + raw_body)).

When a customer makes a successful payment, the webhook sends the following data.

Every webhook includes an X-Event-ID header that uniquely identifies the event. You can use this to safely deduplicate deliveries on your end.

If you configure multiple active webhooks for the same merchant, each active webhook is treated as an independent subscription and will receive its own delivery. If multiple active webhooks point to the same URL, you may receive duplicate deliveries.

If webhook signing is enabled, requests include X-Webhook-Timestamp, X-Webhook-Signature, and X-Webhook-Signature-Version: v1. Verify against the exact raw request body bytes (before JSON parsing): base64(HMAC_SHA256(signing_secret, timestamp + "." + raw_body)).

When a customer makes a payment attempt and it fails, the webhook sends the following data.

For failed payments, multiple charge attempts may be associated with the same payment_id. Each charge attempt will still include its own unique X-Event-ID value, which you can use to differentiate between individual attempts.

If webhook signing is enabled, requests include X-Webhook-Timestamp, X-Webhook-Signature, and X-Webhook-Signature-Version: v1. Verify against the exact raw request body bytes (before JSON parsing): base64(HMAC_SHA256(signing_secret, timestamp + "." + raw_body)).

When a subscriber cancels a subscription, the webhook sends the following data.

If webhook signing is enabled, requests include X-Webhook-Timestamp, X-Webhook-Signature, and X-Webhook-Signature-Version: v1. Verify against the exact raw request body bytes (before JSON parsing): base64(HMAC_SHA256(signing_secret, timestamp + "." + raw_body)).

When you execute a wallet-to-wallet transfer from your merchant wallet, the following payload is sent to the webhook.

If webhook signing is enabled, requests include X-Webhook-Timestamp, X-Webhook-Signature, and X-Webhook-Signature-Version: v1. Verify against the exact raw request body bytes (before JSON parsing): base64(HMAC_SHA256(signing_secret, timestamp + "." + raw_body)).

Sent when a wallet-to-wallet transfer from your merchant wallet fails. The payload has the same shape as the Wallet Transfer event above; only type and status differ. The hash may be empty when the transfer failed before broadcast.

If webhook signing is enabled, requests include X-Webhook-Timestamp, X-Webhook-Signature, and X-Webhook-Signature-Version: v1. Verify against the exact raw request body bytes (before JSON parsing): base64(HMAC_SHA256(signing_secret, timestamp + "." + raw_body)).