Integration
HTTP API
Hosts, authentication, idempotency and the API route reference.
The SDK is a client of Infi's HTTP API. Use these endpoints from your own language or when debugging a request.
Environments
| Environment | API | Hosted checkout |
|---|---|---|
Sandbox (sk_test_) | https://api-sandbox.beinfi.com | https://app-sandbox.beinfi.com |
Production (sk_live_) | https://api.beinfi.com | https://app.beinfi.com |
Use the correct host for the key. Sandbox resources do not exist in production.
Authentication
curl https://api-sandbox.beinfi.com/metering/products \
-H "Authorization: Bearer $INFI_SECRET_KEY"Use Authorization: Bearer, not X-Api-Key. Keep secret keys server-side.
Public checkout routes under /pay/{slug} do not take a merchant secret key.
Agent provisioning
POST /public/v1/claimables is public and accepts optional ref, accountName
and email. It returns apiKeySecret, publishableKey, tenantSlug, productId,
claimUrl and expiresAt. Email is an unverified contact, never an identity.
With the claim-email update, providing an address queues a transactional message
with the link and deadline, at most once per address every 24 hours. A 201
confirms provisioning, not email delivery. Always preserve the returned claim URL.
Read agent onboarding for questions, credentials and human handoff. Do not blindly repeat this POST after a lost response: the account may already exist.
Idempotency
Authenticated mutations require an Idempotency-Key. Use a stable, unique value
for each operation and reuse it only when retrying that same operation.
curl -X POST "https://api-sandbox.beinfi.com/metering/products/$PRODUCT_ID/payment-links" \
-H "Authorization: Bearer $INFI_SECRET_KEY" \
-H "Idempotency-Key: create-link-for-order-123"This requires a published product. Creating a link does not charge a customer.
Missing keys return 400 idempotency_key_required; reusing a key with a
different body returns 409 idempotency_key_reused.
Public bootstrap routes have their own requirements. Do not assume every public route needs a merchant key or uses the same request shape.
Responses and errors
Collection reads return envelopes such as {"products": [...]} .
Resource creation may return a composite response: product creation returns
both product and a draft version. Check the endpoint contract instead of
assuming every resource is at the root.
Errors may use the handler envelope (error_code, message, errors,
tracer_id) or the middleware envelope (error.code, error.message,
error.request_id). Preserve diagnostic IDs when reporting a problem.
Routes
The tables below are generated from the backend OpenAPI contract. Provider capabilities and Early access availability still apply; an endpoint's presence is not a promise that every connected provider supports its operation.
Catalog and customers
| Method | Route | |
|---|---|---|
GET · POST | /metering/customers | List tenant customers |
GET | /metering/customers/{customerID} | Get tenant customer detail or legacy enrollment by ID |
GET · POST | /metering/customers/{customerID}/credit | Get a customer's credit balance and ledger entries |
POST | /metering/customers/{customerID}/credit/consume | Consume (deduct) credit from a customer |
GET · POST | /metering/customers/{customerID}/rate-cards | List a customer's rate cards |
DELETE | /metering/customers/{customerID}/rate-cards/{rateCardID} | Delete a rate card |
GET | /metering/customers/{customerID}/state | Single-read customer state (enrollment, credit, subscriptions, usage) |
GET | /metering/customers/{customerID}/wallet | Get meter wallet balances for an enrollment |
POST | /metering/customers/{customerID}/wallet/credit | Credit a meter balance |
POST | /metering/customers/{customerID}/wallet/debit | Debit a meter balance |
POST | /metering/events | Ingest a single usage event |
POST | /metering/events/batch | Ingest a batch of usage events (all-or-nothing) |
GET | /metering/overview | Tenant KPI summary for the dashboard overview |
GET · POST | /metering/products | List products |
GET · PATCH | /metering/products/{productID} | Get a product |
GET · POST | /metering/products/{productID}/customers | List product enrollments |
GET | /metering/products/{productID}/customers/{enrollmentID} | Get a product enrollment by enrollment ID |
GET · PUT · DELETE | /metering/products/{productID}/deliverable | Get a product's deliverable metadata |
POST | /metering/products/{productID}/deliverable/presign | Presign an R2 upload URL for a file deliverable |
GET · POST | /metering/products/{productID}/meters | List meters of a product |
PATCH | /metering/products/{productID}/meters/{meterID} | Update a meter's display name / unit / aggregation |
GET · POST | /metering/products/{productID}/payment-links | List a product's payment links |
DELETE | /metering/products/{productID}/payment-links/{linkID} | Revoke a payment link |
GET · POST | /metering/products/{productID}/versions | List versions of a product |
PUT | /metering/products/{productID}/versions/{versionID}/commitment | Set a committed minimum on a version |
PUT | /metering/products/{productID}/versions/{versionID}/entitlements | Replace the complete entitlement snapshot of a draft version |
GET · POST | /metering/products/{productID}/versions/{versionID}/prices | List prices on a version |
POST | /metering/products/{productID}/versions/{versionID}/publish | Publish a draft version (makes pricing immutable) |
GET | /metering/usage | Get usage totals for a customer |
Billing and payments
| Method | Route | |
|---|---|---|
GET · POST | /billing/coupons | List the tenant's coupons |
GET · PATCH · DELETE | /billing/coupons/{couponID} | Get a coupon |
GET | /billing/customers/{customerID}/invoices | List a customer's invoices |
GET | /billing/customers/{customerID}/payment-methods | List a payer's stored payment methods |
DELETE | /billing/customers/{customerID}/payment-methods/{instrumentID} | Remove a stored payment method |
POST | /billing/customers/{customerID}/payment-methods/{instrumentID}/default | Make a stored payment method the payer's default |
GET | /billing/customers/{customerID}/subscriptions | List a customer's subscriptions |
GET · POST | /billing/invoices | List all invoices for the tenant |
GET | /billing/invoices/{invoiceID} | Get an invoice |
POST | /billing/invoices/{invoiceID}/charge | Charge an open invoice via the PSP |
GET | /billing/invoices/{invoiceID}/deliverable | List the download grants an invoice's payments produced |
GET | /billing/invoices/{invoiceID}/invoice.pdf | Get an invoice PDF |
GET | /billing/invoices/{invoiceID}/payments | List payments against an invoice |
GET | /billing/invoices/{invoiceID}/receipt.pdf | Get an invoice receipt PDF |
POST | /billing/invoices/{invoiceID}/send | Finalize and send an invoice |
POST | /billing/invoices/{invoiceID}/uncollectible | Mark an invoice uncollectible |
POST | /billing/invoices/{invoiceID}/void | Void an invoice |
POST | /billing/invoices/from-usage | Generate an invoice from an enrollment's accrued usage (on demand) |
GET | /billing/payments | List all payments for the tenant |
GET | /billing/payments/{paymentID} | Get one payment |
POST | /billing/payments/{paymentID}/refund | Refund a payment (full or partial) |
GET | /billing/payments/{paymentID}/refunds | List the refunds recorded against a payment |
POST | /billing/products/{productID}/invoices | Purchase a product — enroll the customer and open a finalized invoice |
POST | /billing/products/{productID}/subscriptions | Create a subscription for a customer |
GET · PUT | /billing/settings | Get the tenant's collection settings |
GET | /billing/subscriptions | List all subscriptions for the tenant |
GET · PATCH | /billing/subscriptions/{subscriptionID} | Get a subscription |
GET · POST | /billing/subscriptions/{subscriptionID}/alerts | List usage alerts on a subscription |
DELETE | /billing/subscriptions/{subscriptionID}/alerts/{alertID} | Delete a usage alert |
POST | /billing/subscriptions/{subscriptionID}/invoices | Generate an invoice for the subscription's current ended period |
GET | /billing/subscriptions/{subscriptionID}/periods | List billing periods of a subscription |
Account
| Method | Route | |
|---|---|---|
GET · POST | /account/api-keys | List API keys |
DELETE | /account/api-keys/{keyID} | Revoke an API key |
GET · POST | /account/notification-subscriptions | List notification subscriptions |
PATCH · DELETE | /account/notification-subscriptions/{subscriptionID} | Activate or deactivate a notification subscription |
GET | /account/notifications/deliveries | List notification delivery audit records |
GET | /account/plan | Effective plan, approved payment volume, invoice projection and entitlements |
POST | /account/plan/activate | Accept the current Terms and activate a postpaid live plan |
POST | /account/plan/downgrade | Schedule a paid self-service tier to Free at the next cycle boundary |
POST | /account/plan/upgrade | Confirm Scale as the account's minimum economic tier |
GET · PATCH | /account/tenant | Get the authenticated tenant |
GET · POST | /account/webhooks | List webhook endpoints |
GET · PATCH · DELETE | /account/webhooks/{endpointID} | Get a webhook endpoint |
POST | /account/webhooks/{endpointID}/rotate-secret | Rotate a webhook endpoint's signing secret |
GET | /account/webhooks/deliveries | List webhook delivery audit records |
Public — no merchant key
| Method | Route | |
|---|---|---|
GET | /pay/{slug}/download/{token} | Redeem a tokenized digital-product download (unauthenticated) |
GET | /pay/{slug}/invoices/{invoiceID} | Public hosted-checkout invoice read (unauthenticated) |
POST | /pay/{slug}/invoices/{invoiceID}/charge | Initiate payment on a public checkout invoice (unauthenticated) |
POST | /pay/{slug}/invoices/{invoiceID}/coupon | Apply a coupon to a public checkout invoice (unauthenticated) |
GET | /pay/{slug}/invoices/{invoiceID}/invoice.pdf | Public hosted-checkout invoice PDF (unauthenticated) |
GET | /pay/{slug}/invoices/{invoiceID}/payments/{paymentID} | Read authoritative public payment status (unauthenticated) |
GET | /pay/{slug}/invoices/{invoiceID}/receipt.pdf | Public hosted-checkout receipt PDF (unauthenticated) |
GET | /pay/{slug}/links/{token} | Resolve a payment link for display (unauthenticated) |
POST | /pay/{slug}/links/{token}/checkout | Materialize an invoice from a payment link (unauthenticated, legacy) |
POST | /pay/{slug}/links/{token}/sessions | Open (or reuse) a checkout session for a payment link (unauthenticated) |
GET | /pay/{slug}/links/{token}/sessions/{sessionID} | Read a checkout session (unauthenticated) |
POST | /pay/{slug}/links/{token}/sessions/{sessionID}/charge | Materialize the invoice and charge a checkout session (unauthenticated) |
GET | /pay/{slug}/links/{token}/sessions/{sessionID}/payments/{paymentID} | Read authoritative link-session payment status (unauthenticated) |
GET | /public/platform-plans | Published Infi platform plans for the landing and calculators |
POST | /public/v1/claimables | Provision a claimable tenant (instant creds, claim later; no auth) |
GET | /public/v1/claimables/{claimableID} | Public claimable-tenant status (no secrets) |
Operations — sessions and inbound webhooks
| Method | Route | |
|---|---|---|
POST | /auth/claimables/{claimableID}/claim | Claim a provisional tenant to the signed-in user |
POST | /auth/cli/token | Exchange dashboard session for CLI API key |
POST | /auth/session/bootstrap | Provision tenant on first dashboard signup |
POST | /auth/session/onboarding/complete | Mark tenant onboarding complete |
POST | /auth/session/sync | Sync dashboard session with backend membership |
POST | /webhook/provider/payments/webhook | Inbound PSP webhook (authenticated by the gateway signature) |
POST | /webhook/provider/webhooks/{provider}/{externalAccountID}/{token} | Inbound webhook for a provider whose deliveries are not self-authenticating |
POST | /webhook/provider/webhooks/adyen/{externalAccountID} | Inbound Adyen Standard webhook |