Every public method, option, and return type in @radonsdk/payments — the RadonPayments client, money helpers, subscriptions, webhooks, and coupons.

Complete reference for @radonsdk/payments. Types are shown in TypeScript.

Constructor

new RadonPayments(config: RadonPaymentsConfig)

Create a client. Pair with createPayments(config) if you prefer a factory.

RadonPaymentsConfig

providersRecord<string, ProviderOptions>required

The providers to enable, keyed by slug. {} reads credentials from env vars.

mode"test" | "live"default: "test"

Sandbox vs live for every provider at once. (Stripe decides from its key prefix.)

defaultProviderstring

Slug used when a call omits { provider }. Defaults to the sole provider; throws if ambiguous.

couponStoreCouponStoredefault: InMemoryCouponStore

Where coupons and redemption counts live. Swap in a DB-backed store for production.

licenseKeystringdefault: process.env.RADON_LICENSE_KEY

Radon Pro key. Required to use any Pro provider.

fetchtypeof fetchdefault: globalThis.fetch

Inject a custom fetch (proxies, tests).

now() => Datedefault: () => new Date()

Injectable clock for tests.

onHookError(error, hook) => voiddefault: console.error

Called when a hook or middleware throws.

ProviderOptions is { webhookSecret?: string } plus any provider-specific keys; every field is optional (env vars are the default source).

Client methods

payments.init(): Promise<void>

Verify the Pro license (if any Pro provider is configured) and eagerly load providers. Required before using Pro providers; optional for free-only setups.

payments.charge(input: ChargeInput, options?: OperationOptions): Promise<ChargeResult>

Take a one-time payment. See Charges.

payments.retrieveCharge(id: string, options?: OperationOptions): Promise<ChargeResult>

Fetch a charge to confirm redirect/async outcomes.

payments.refund(input: RefundInput, options?: OperationOptions): Promise<RefundResult>

Full or partial refund. See Refunds.

payments.provider(slug?: string): Promise<PaymentProvider>

Get the (lazy-loaded) provider instance — for capabilities checks or advanced use.

payments.on(event, handler): () => void

payments.useMiddleware(mw: ChargeMiddleware): this

Add around-style charge middleware (onion order).

payments.use(plugin: Plugin): this

Install a plugin — a bundle of hooks and middleware.

Getters: payments.defaultProvider: string · payments.isLicensed: boolean.

OperationOptions is { provider?: string } — route a single call to a specific provider.

ChargeInput

amountMoneyrequired

Integer minor units + currency.

customer{ email?; id?; name? }

The payer; some providers require email.

idempotencyKeystring

Makes retries safe where supported.

metadataRecord<string, string>

Echoed back in webhooks.

ChargeResult

Normalized outcome.

idstring

Provider charge id.

redirectUrlstring | undefined

Present when the customer must finish on a hosted page.

amountMoney

Normalized amount + currency.

rawunknown

Untouched provider response.

Money helpers

money(amount: number, currency: string): Money

Integer minor units. Throws on a non-integer.

majorMoney(major: number, currency: string): Money

From a decimal, e.g. 19.99.

toMinorUnits(major: number, currency: string): number

fromMinorUnits(minor: number, currency: string): number

formatMinorUnits(minor: number, currency: string): string

"123.45" for display/wire.

currencyExponent(currency: string): number

0, 2, or 3.

isZeroDecimal(currency: string): boolean

subscriptions

payments.subscriptions.create(input: SubscriptionInput, options?): Promise<SubscriptionResult>

payments.subscriptions.retrieve(id: string, options?): Promise<SubscriptionResult>

payments.subscriptions.cancel(id: string, options?: OperationOptions & CancelSubscriptionOptions): Promise<void>

webhooks

payments.webhooks.handle(request: WebhookRequest, options?: HandleWebhookOptions): Promise<NormalizedEvent>

Verify a signature and normalize the payload. WebhookRequest is { body: string | Buffer; headers: Record<string, string> } — pass the raw body.

coupons

payments.coupons.create(coupon: Coupon): Promise<Coupon>

payments.coupons.get(code: string): Promise<Coupon | null>

payments.coupons.list(): Promise<Coupon[]>

payments.coupons.validate(code: string, amount: Money, customerId?: string): Promise<Coupon>

Throws if invalid/expired/limit reached. Read-only.

payments.coupons.apply(code: string, amount: Money, customerId?: string): Promise<DiscountResult>

Returns the discounted amount.

payments.coupons.redeem(code: string, amountDiscounted: number, customerId?: string): Promise<void>

Record a redemption (after a successful charge).

payments.coupons.expire(code: string): Promise<void>

payments.coupons.delete(code: string): Promise<void>

Registry (bring-your-own-provider)

registerProvider(slug: string, loader: ProviderLoader): void

hasProvider(slug: string): boolean

knownProviders(): string[]

Hooks & middleware

onPaymentSucceeded(charge: ChargeResult) => void | Promise<void>

Fired after a successful charge. Errors are isolated to onHookError.

onPaymentFailed(charge: ChargeResult) => void | Promise<void>

Fired on a failed charge.

onRefundIssued(refund: RefundResult) => void | Promise<void>

Fired after a refund.

Hook vs middleware error handling

A throwing hook is caught and routed to onHookError — it never breaks the charge. A throwing charge middleware does propagate to the caller (it's in the critical path).

API reference