[data-reveal]{opacity:1!important;transform:none!important}
Introduction
Payment

Introduction

What the payment interface covers, what it leaves out and why, and the conventions every function follows.

@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

AreaFunctions
Hosted checkoutCreateCheckoutSession, GetCheckoutSession
Direct paymentsCreatePayment, GetPayment, CapturePayment, CancelPayment
RefundsRefundPayment, GetRefund
Customers and saved methodsCreateCustomer, GetCustomer, DeleteCustomer, ListPaymentMethods, DetachPaymentMethod
WebhooksVerifyWebhook

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
}