Introduction
@antelopejs/interface-payment defines a provider-agnostic payment interface for
AntelopeJS applications. A backend written against it takes payments, refunds
them, saves payment methods, and reacts to settlement events without naming a
provider. To change provider, it swaps the module that implements the interface.
What it covers
| Area | Functions |
|---|---|
| Hosted checkout | CreateCheckoutSession, GetCheckoutSession |
| Direct payments | CreatePayment, GetPayment, CapturePayment, CancelPayment |
| Refunds | RefundPayment, GetRefund |
| Customers and saved methods | CreateCustomer, GetCustomer, DeleteCustomer, ListPaymentMethods, DetachPaymentMethod |
| Webhooks | VerifyWebhook |
What it deliberately does not cover
The interface leaves out these areas:
- subscriptions, invoicing, proration, dunning, tax, and coupons
- marketplace split payments
- dispute management
- payment links
- in-person terminals
Providers differ most in these areas. Modelling them would produce an interface
that most implementations could only decline. For recurring access, use
@antelopejs/interface-subscriptions. With Stripe, use Stripe's native billing.
Choose @antelopejs/payment-subscriptions explicitly when you need a generic
renewal clock on saved methods and off-session charges. Give each subscription
one renewal owner. Billing features specific to one provider stay outside the
portable contract. The provider capability matrix
gives the reasoning for each feature.
When a backend needs something beyond this contract, it uses the provider's own
interface alongside this one, such as @antelopejs/interface-stripe for Stripe.
That is the way out of the contract, so this interface has no escape hatch of
its own. An escape hatch here would return an object shaped by one provider, and
code that used it would no longer be portable.
Installation
pnpm add @antelopejs/interface-payment
This package declares the contract and ships no provider logic. Add a module that implements it to your AntelopeJS project config.
Conventions
These conventions hold for every function. An implementation that breaks one does not conform to the contract.
Amounts are integer minor units. { value: 1050, currency: "EUR" } is €10.50.
Never use a float. Binary floating point cannot represent most decimal amounts,
and providers round a float differently. JPY has no subunit, so
{ value: 1050, currency: "JPY" } is ¥1050. KWD has three decimal places.
The derived amounts on a Payment, amountCaptured and amountRefunded, are in
the same currency as amount.
Every mutating call takes an idempotency key. A retried payment request must not do the work twice. Generate one key per logical operation, store it with your own record, and reuse it on retry. Within its provider-defined replay window, the provider returns the original result. Reads take no key. After the window expires, reconcile uncertain payments with the provider's records before you retry, because a reused key can charge again.
Provider identifiers are opaque. Payment.id, Refund.id, Customer.id,
PaymentMethod.id, and CheckoutSession.id are the provider's own strings. Do
not parse them, do not infer a type from a prefix, and do not assume that two
providers shape them alike. Correlate them with your own records through
reference and metadata.
A failed payment is not a thrown error. CreatePayment resolves with a
Payment whose status is failed. It rejects only when the call itself could
not be made. See Payments.
Settlement is asynchronous. Every provider this interface targets settles
some payments after the call returns, and some after the payer has left. Your
backend learns a terminal state from VerifyWebhook, not from the payer's return
to your successUrl. See Webhooks.
Multi-account setups
Every function takes an optional trailing provider argument. It names the
configured account to use, for a backend that runs more than one merchant
account or more than one provider at once. Omit it for the default account.
import {
CreatePayment,
type PaymentRequest,
} from "@antelopejs/interface-payment";
export async function charge(request: PaymentRequest, key: string) {
await CreatePayment(request, key); // default account
await CreatePayment(request, key, "marketplace"); // a named one
}