Customers and saved payment methods
A customer is a container that the provider attaches saved payment methods to. You save a method once and charge it later with nobody present.
Saved methods make recurring billing portable without modelling subscriptions. A backend that sells monthly access saves a method, runs its own billing cycle, and charges the method off-session each period. That works on every provider in the capability matrix. A provider's own subscription object does not.
Only the identifier round-trips
const customer = await CreateCustomer(
{ email: user.email, name: user.fullName },
idempotencyKey,
);
await users.update(user.id, { paymentCustomerId: customer.id });
Store the identifier against your own user record. Do not read the payer's
details back from the provider. Only providers with a first-class customer
object store email, name, and metadata. PayPal's vault and Adyen's
shopperReference use the identifier as a key for tokens and store nothing else,
so GetCustomer on those providers returns the identifier alone.
The conformance suite asserts that the identifier round-trips and nothing more,
which is the guarantee the contract makes. Use GetCustomer to confirm that a
customer still exists, not to read a profile you did not store yourself.
Saving a method
A payment saves a method as a side effect. No call saves one on its own, because
no provider here lets you store a card unless the payer presents it.
savePaymentMethod exists on both payment paths and requires customer on
either.
Through hosted checkout:
import {
CreateCheckoutSession,
type Amount,
} from "@antelopejs/interface-payment";
export async function startSavingCheckout(
amount: Amount,
orderId: string,
successUrl: string,
cancelUrl: string,
user: { paymentCustomerId: string },
idempotencyKey: string,
) {
const session = await CreateCheckoutSession(
{
amount,
reference: orderId,
successUrl,
cancelUrl,
customer: user.paymentCustomerId,
savePaymentMethod: true,
},
idempotencyKey,
);
return session;
}
On a direct payment, set the same flag:
import { CreatePayment, type Amount } from "@antelopejs/interface-payment";
export async function paySavingMethod(
amount: Amount,
orderId: string,
presentedMethod: string,
user: { paymentCustomerId: string },
idempotencyKey: string,
) {
const payment = await CreatePayment(
{
amount,
reference: orderId,
paymentMethod: presentedMethod,
customer: user.paymentCustomerId,
savePaymentMethod: true,
returnUrl: "https://shop.example/payment-return",
},
idempotencyKey,
);
return payment;
}
savePaymentMethod and offSession are mutually exclusive. Saving a method takes
a mandate from the payer, so the payer must be present.
Set returnUrl to your application's return route, even when you charge a saved
method on-session. If the result is requires_action, redirect the payer to
payment.redirectUrl. After they return, read the payment on the server.
On both paths, the method appears in ListPaymentMethods once the payment
reaches succeeded or authorized. It does not appear at session creation, when
the payer returns, or as soon as CreatePayment resolves. Settlement is
asynchronous, so list the methods after the payment has settled, or after the
payment.succeeded event.
Charging off-session
ListPaymentMethods returns the saved methods newest first, and an empty array
when there are none.
const [method] = await ListPaymentMethods(user.paymentCustomerId);
if (!method) return dunning.noMethodOnFile(user);
const payment = await CreatePayment(
{
amount: { value: 999, currency: "EUR" },
reference: `sub-${user.id}-${period}`,
customer: user.paymentCustomerId,
paymentMethod: method.id,
offSession: true,
},
`renewal-${user.id}-${period}`,
);
The example derives the idempotency key from the billing period. A retried or duplicated renewal job then replays within the provider-defined replay window. After the window expires, reconcile uncertain payments before you retry, because the same key can create another charge.
An off-session charge can still fail. The card may have expired, the bank may
want the payer to authenticate, or the account may lack funds. The payment comes
back failed, never requires_action, because there is nobody to redirect. Ask
the payer to return and pay on-session.
What a saved method tells you
import type { CardDetails } from "@antelopejs/interface-payment";
export interface PaymentMethod {
id: string;
type: "card" | "wallet" | "bank_account" | "other";
customer: string;
card?: CardDetails;
createdAt: number;
}
card is present when type is card. It holds the brand, the last four
digits, the expiry month, and the expiry year. That is enough for a payer to
recognise the card they saved, and nothing more. It never holds the PAN, and
never a token you could charge outside the provider.
A PayPal vault entry is a wallet and has no card. Branch on type instead of
assuming that card is there.
Removing
DetachPaymentMethod removes one method and keeps the customer.
DeleteCustomer removes the customer and detaches every method saved against it.
Both throw CustomerNotFoundError for an unknown identifier. Payments already
taken are unaffected and stay readable by their identifiers. Deleting a customer
does not erase a payment history, and refunds against past payments keep
working.