[data-reveal]{opacity:1!important;transform:none!important}
Customers and saved payment methods
Payment

Customers and saved payment methods

Create a customer, save a payment method during a payment, charge it off-session, and remove it.

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.