| Function | Description |
|---|
createBillingClient({ providers, defaultProvider }) | Build a BillingClient from a map of adapters and the default provider name |
createBillingClientFor(adapter) | Wrap a single PaymentProvider adapter |
createBillingClientFromEnv(options?) | Resolve the provider from BILLING_PROVIDER (default 'zazu') and its config from the environment; options.config overrides per provider |
createProvider(name, config?) | Instantiate a registered provider by name; throws UnknownProviderError |
registerProvider(name, factory) / isProviderRegistered(name) / registeredProviders() | The provider registry adapters register into |
BillingClient
| Member | Description |
|---|
provider / adapter | Active provider name and the underlying PaymentProvider (escape hatch for provider-specific calls) |
createCheckoutSession(input) / getCheckoutSession(id) | Hosted checkout |
createPaymentLink(input) / getPaymentLink(id) / listPaymentLinks(params?) / cancelPaymentLink(id) | Payment links (cursor-paginated list) |
handleWebhookEvent({ rawBody, headers }) | Verify the signature and return a normalized PaymentEvent |
invoicing / transfers / accounts / webhookEndpoints | Optional capabilities — null when the provider lacks them |
requireInvoicing() / requireTransfers() / requireAccounts() / requireWebhookEndpoints() | Assert a capability; throw CapabilityNotSupportedError |
Capability interfaces: InvoicingCapable (createInvoice, getInvoice, listInvoices, sendInvoice, markInvoicePaid, cancelInvoice, createCustomer, getCustomer, listCustomers, updateCustomer, deleteCustomer), TransferCapable (createTransfer, getTransfer, listTransfers), AccountCapable (listAccounts, getAccount, listAccountTransactions, getAccountTransaction), WebhookEndpointCapable (listWebhookEndpoints, createWebhookEndpoint, getWebhookEndpoint, updateWebhookEndpoint, deleteWebhookEndpoint, enableWebhookEndpoint). Capability checks: supportsInvoicing(adapter), supportsTransfers(adapter), supportsAccounts(adapter), supportsWebhookEndpoints(adapter).
| Export | Description |
|---|
isCheckoutSessionCompleted(event) | Narrow a PaymentEvent to checkout_session.completed |
isPaymentLinkPaid(event) | Narrow to payment_link.paid |
isTransferExecuted(event) | Narrow to transfer.executed |
Every PaymentEvent carries type, eventId, objectId, correlation? ({ reference?, metadata? }), amount? and raw.
| Class | Description |
|---|
BillingError | Base class |
ProviderError | Provider/API failure; transient tells you whether a deliberate retry is reasonable |
WebhookSignatureError | Signature or freshness check failed — answer 401 |
WebhookPayloadError | Authentic request the adapter cannot consume — answer 400, not 401 |
CapabilityNotSupportedError | require*() on a provider lacking the capability |
InvalidCorrelationError / UnsupportedCorrelationError | Malformed correlation, or metadata on a flow that cannot round-trip it |
MissingConfigError | A required credential could not be resolved (message includes the fix) |
UnknownProviderError / MockProviderNotAllowedError | Unregistered provider name / mock constructed outside a provably local environment |
| Function | Description |
|---|
createZazuAdapter(config?) | The PaymentProvider for Zazu; config fields override env / secret resolution per credential |
resolveZazuConfig(overrides?) | The resolution logic on its own (ZAZU_* env → ZAZU_SECRET_ARN) |
createZazuHttpClient(config) | Low-level HTTP client — retries GETs only |
createZazuSecretsResolver(options?) | Lazy, once-per-container reader of the ZAZU_SECRET_ARN secret |
resolveSecretValue(...) / resolveOptionalSecretValue(...) | Per-field precedence helpers used by the resolver |
verifyZazuSignature(secret, timestamp, rawBody, signature, toleranceSeconds?) | Signature + replay-window check; throws WebhookSignatureError (DEFAULT_WEBHOOK_TOLERANCE_SECONDS = 300) |
parseZazuWebhook(rawBody, headers) | Normalize an already-verified Zazu payload into a PaymentEvent |
handleZazuWebhook(secret, request, options?) | Verify + normalize in one step — what the adapter’s handleWebhookEvent() calls |
| Function | Description |
|---|
createMockProvider(options?) | In-memory provider recording calls; failNext makes the next N calls fail. Throws MockProviderNotAllowedError unless VENTURE_LOCAL=true or NODE_ENV=test |
registerMockProvider() | Opt-in registration so createProvider('mock') works in tests |
BillingClient, PaymentProvider, ProviderName, CreateBillingClientOptions, CreateBillingClientFromEnvOptions, CreateCheckoutSessionInput, CheckoutSession, CreatePaymentLinkInput, PaymentLink, ListPaymentLinksParams, CursorPage<T>, CreateInvoiceInput, Invoice, CreateCustomerInput, Customer, CreateTransferInput, Transfer, Account, AccountTransaction, CreateWebhookEndpointInput, WebhookEndpoint, WebhookRequest, PaymentEvent, CorrelationFlow, CorrelationSupport, HandleZazuWebhookOptions.