@antelopejs/interface-payment 0.1.0 → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -1,14 +1,18 @@
1
- # Payments
1
+ ---
2
+ title: Payments
3
+ description: Take a payment through hosted checkout or a direct call, authorize and capture it, refund it, and handle declines and errors.
4
+ mode: how-to
5
+ ---
2
6
 
3
- Two ways to take a payment: a hosted checkout page the provider renders, or a
4
- payment created directly against a method you already hold. Both produce a
5
- `Payment`, and everything after creation — capture, cancel, refund, events — is
6
- the same for either.
7
+ There are two ways to take a payment. The provider can render a hosted checkout
8
+ page, or you can create a payment directly against a method you already hold.
9
+ Both produce a `Payment`. Everything after creation is the same for either path:
10
+ capture, cancel, refund, and events.
7
11
 
8
12
  ## Status
9
13
 
10
14
  `PaymentStatus` is the normalised lifecycle. Providers report far more states
11
- than this; these are the ones a backend branches on.
15
+ than these six. These are the ones a backend branches on.
12
16
 
13
17
  | Status | Meaning | What to do |
14
18
  | ----------------- | ------------------------------------------------------------- | ------------------------------------- |
@@ -19,21 +23,21 @@ than this; these are the ones a backend branches on.
19
23
  | `failed` | Declined, errored, or expired unpaid | Map `failure.code` to payer-safe copy |
20
24
  | `canceled` | Voided before capture, by you or by the payer abandoning | Release the order |
21
25
 
22
- `succeeded`, `failed` and `canceled` are terminal — `isTerminalPaymentStatus`
23
- classifies them. The rest will change again, either because the payer acts or
24
- because the provider settles.
26
+ `succeeded`, `failed`, and `canceled` are terminal, and `isTerminalPaymentStatus`
27
+ returns `true` for them. The other statuses change again, when the payer acts or
28
+ when the provider settles.
25
29
 
26
30
  `redirectUrl` is present exactly when the status is `requires_action`, and
27
- `failure` exactly when it is `failed`. Those are invariants the conformance suite
28
- checks, so you can branch on the status alone.
31
+ `failure` exactly when it is `failed`. The conformance suite checks both
32
+ invariants, so you can branch on the status alone.
29
33
 
30
34
  ## Hosted checkout
31
35
 
32
- The provider hosts the page, collects the method and takes the payment. This is
33
- how most backends should take a one-off payment: no card data reaches your
34
- servers, and the provider handles 3DS, wallets and local methods for you.
36
+ The provider hosts the page, collects the method, and takes the payment. Use
37
+ hosted checkout for most one-off payments. No card data reaches your servers, and
38
+ the provider handles 3DS, wallets, and local methods.
35
39
 
36
- ```ts
40
+ ```ts fragment
37
41
  import {
38
42
  CreateCheckoutSession,
39
43
  GetCheckoutSession,
@@ -58,51 +62,70 @@ await orders.update(orderId, { sessionId: session.id });
58
62
  response.redirect(session.redirectUrl);
59
63
  ```
60
64
 
65
+ To set the language of the hosted page, pass `locale`, one of the
66
+ `PAYMENT_LOCALES` values. `auto` lets the provider pick from the payer's browser.
67
+ A provider without a matching language falls back to its own default.
68
+
61
69
  When the payer comes back to `successUrl`, read the session:
62
70
 
63
71
  ```ts
64
- const session = await GetCheckoutSession(order.sessionId);
65
- if (session.payment) {
66
- const payment = await GetPayment(session.payment);
67
- // render payment.status
72
+ import { GetCheckoutSession, GetPayment } from "@antelopejs/interface-payment";
73
+
74
+ export async function readOrderPayment(order: { sessionId: string }) {
75
+ const session = await GetCheckoutSession(order.sessionId);
76
+ if (session.payment) {
77
+ const payment = await GetPayment(session.payment);
78
+ // render payment.status
79
+ }
68
80
  }
69
81
  ```
70
82
 
71
- **The return is a prompt, not a report.** The payer's browser is not a
72
- trustworthy reporter: they can navigate to `successUrl` themselves, close the tab
73
- before the redirect, or lose the connection. Render what `GetCheckoutSession`
74
- says, and fulfil the order from the webhook.
83
+ **The return is a prompt, not a report.** The payer's browser does not report the
84
+ outcome reliably. The payer can open `successUrl` directly, close the tab before
85
+ the redirect, or lose the connection. Render what `GetCheckoutSession` returns,
86
+ and fulfil the order from the webhook.
75
87
 
76
88
  `CheckoutSession.payment` is absent until the provider has created a payment
77
- behind the session, which for some providers is only once the payer has acted.
78
- Providers whose session and payment are one object return the same identifier in
79
- both fields — which is fine, because identifiers are opaque.
89
+ behind the session. For some providers, that happens only after the payer has
90
+ acted. A provider whose session and payment are one object returns the same
91
+ identifier in both fields. Identifiers are opaque, so that causes no problem.
80
92
 
81
93
  ## Direct payments
82
94
 
83
- `CreatePayment` takes a payment without a hosted page. Two uses: charging a saved
84
- method with nobody present, and taking a payment through a form you host.
95
+ `CreatePayment` takes a payment without a hosted page. It has two uses: charging
96
+ a saved method with nobody present, and taking a payment through a form you host.
85
97
 
86
98
  ```ts
87
- const payment = await CreatePayment(
88
- {
89
- amount: { value: 4999, currency: "EUR" },
90
- reference: orderId,
91
- paymentMethod: savedMethodId,
92
- customer: customerId,
93
- offSession: true,
94
- },
95
- idempotencyKey,
96
- );
99
+ import { CreatePayment } from "@antelopejs/interface-payment";
100
+
101
+ export async function chargeSavedMethod(
102
+ orderId: string,
103
+ savedMethodId: string,
104
+ customerId: string,
105
+ idempotencyKey: string,
106
+ ) {
107
+ const payment = await CreatePayment(
108
+ {
109
+ amount: { value: 4999, currency: "EUR" },
110
+ reference: orderId,
111
+ paymentMethod: savedMethodId,
112
+ customer: customerId,
113
+ offSession: true,
114
+ },
115
+ idempotencyKey,
116
+ );
117
+ return payment;
118
+ }
97
119
  ```
98
120
 
99
- `offSession` says nobody can be prompted. The provider will not return
100
- `requires_action`; it declines instead. Leave it unset when the payer is at the
101
- keyboard, and pass a `returnUrl` so they can be sent through authentication.
121
+ `offSession` says that nobody can be prompted. The provider does not return
122
+ `requires_action`. It declines instead. Leave `offSession` unset when the payer is
123
+ present, and pass a `returnUrl` so the provider can send them through
124
+ authentication.
102
125
 
103
126
  ### A decline is a result, not an exception
104
127
 
105
- ```ts
128
+ ```ts fragment
106
129
  const payment = await CreatePayment(request, idempotencyKey);
107
130
 
108
131
  if (payment.status === "failed") {
@@ -114,120 +137,153 @@ if (payment.status === "failed") {
114
137
  }
115
138
  ```
116
139
 
117
- `PaymentFailure.message` is for server logs, not for the payer. Use your own
118
- customer-facing copy, optionally selected by `failure.code`; do not expose the
140
+ `PaymentFailure.message` is for server logs, not for the payer. Show your own
141
+ copy to the payer, optionally selected by `failure.code`. Do not expose the
119
142
  provider's message or `providerCode` in the response.
120
143
 
121
- `CreatePayment` rejects only when the call itself could not be made — bad
122
- credentials, a malformed request, an unreachable provider. A card declined by the
123
- issuer is a `Payment` with status `failed` and a populated `failure`.
144
+ `CreatePayment` rejects only when the call itself could not be made, for example
145
+ because of bad credentials, a malformed request, or an unreachable provider. A
146
+ card that the issuer declines is a `Payment` with status `failed` and a populated
147
+ `failure`.
124
148
 
125
- This is deliberate. The same decline can arrive synchronously from `CreatePayment`
126
- or asynchronously as a `payment.failed` event, depending on the provider and the
127
- method. Modelling one as an exception and the other as an event would mean
128
- writing the handling twice and keeping the two in step. Instead both give you a
129
- `Payment` with the same shape, so one function handles both.
149
+ The interface does this on purpose. The same decline can arrive synchronously
150
+ from `CreatePayment` or asynchronously as a `payment.failed` event, depending on
151
+ the provider and the method. If one were an exception and the other an event,
152
+ you would write the handling twice and keep the two copies in step. Both give
153
+ you a `Payment` with the same shape instead, so one function handles both.
130
154
 
131
- `PaymentFailure.code` is coarse on purpose — `declined`, `insufficient_funds`,
132
- `expired_card`, `incorrect_details`, `authentication_failed`, `canceled_by_payer`,
133
- `expired`, `processing_error`. Providers report hundreds of decline reasons under
134
- incompatible names, and a backend acts on very few of them. The provider's own
135
- code travels verbatim in `providerCode` for a support ticket.
155
+ `PaymentFailure.code` is coarse on purpose. Its values are `declined`,
156
+ `insufficient_funds`, `expired_card`, `incorrect_details`,
157
+ `authentication_failed`, `canceled_by_payer`, `expired`, and `processing_error`.
158
+ Providers report hundreds of decline reasons under incompatible names, and a
159
+ backend acts on very few of them. The provider's own code travels verbatim in
160
+ `providerCode`, for a support ticket.
136
161
 
137
- ### Authentication and 3DS
162
+ ### Payer authentication
138
163
 
139
164
  There is no separate mechanism for 3DS or SCA. A payment that needs the payer to
140
- authenticate comes back `requires_action` with a `redirectUrl`, which is the same
141
- redirect the hosted flow uses:
165
+ authenticate comes back `requires_action` with a `redirectUrl`. The hosted flow
166
+ uses the same redirect:
142
167
 
143
- ```ts
144
- if (payment.status === "requires_action") {
145
- return response.redirect(payment.redirectUrl!);
168
+ ```ts fragment
169
+ if (payment.status === "requires_action" && payment.redirectUrl) {
170
+ return response.redirect(payment.redirectUrl);
146
171
  }
147
172
  ```
148
173
 
149
- Any payment can turn out to need it, which is why `returnUrl` is required unless
150
- `offSession` is set.
174
+ Any payment can turn out to need authentication. For that reason `returnUrl` is
175
+ required unless `offSession` is set.
151
176
 
152
177
  ## Authorize now, capture later
153
178
 
154
- Set `authorizeOnly` to hold funds without taking them — the usual shape for
155
- physical goods, where you charge on dispatch.
179
+ To hold funds without taking them, set `authorizeOnly`. Physical goods usually
180
+ work this way, with the charge taken on dispatch.
156
181
 
157
182
  ```ts
158
- const authorized = await CreatePayment(
159
- {
160
- amount,
161
- reference: orderId,
162
- paymentMethod,
163
- offSession: true,
164
- authorizeOnly: true,
165
- },
166
- idempotencyKey,
167
- );
168
- // authorized.status === "authorized", authorized.amountCaptured.value === 0
183
+ import {
184
+ CapturePayment,
185
+ CreatePayment,
186
+ type Amount,
187
+ } from "@antelopejs/interface-payment";
169
188
 
170
- const captured = await CapturePayment(authorized.id, captureKey, {
171
- value: 3999,
172
- currency: "EUR",
173
- });
189
+ export async function authorizeThenCapture(
190
+ amount: Amount,
191
+ orderId: string,
192
+ paymentMethod: string,
193
+ idempotencyKey: string,
194
+ captureKey: string,
195
+ ) {
196
+ const authorized = await CreatePayment(
197
+ {
198
+ amount,
199
+ reference: orderId,
200
+ paymentMethod,
201
+ offSession: true,
202
+ authorizeOnly: true,
203
+ },
204
+ idempotencyKey,
205
+ );
206
+ // authorized.status === "authorized", authorized.amountCaptured.value === 0
207
+
208
+ const captured = await CapturePayment(authorized.id, captureKey, {
209
+ value: 3999,
210
+ currency: "EUR",
211
+ });
212
+ return captured;
213
+ }
174
214
  ```
175
215
 
176
216
  Omit the amount to capture everything authorized. Capturing less releases the
177
- remainder: there is no second capture against the same authorization here,
178
- because not every provider allows one. If you need to capture in instalments,
179
- authorize per instalment.
217
+ remainder. The interface allows one capture per authorization, because not every
218
+ provider allows a second one. To capture in instalments, authorize each
219
+ instalment separately.
180
220
 
181
- `CancelPayment` voids an uncaptured payment and releases the hold.
221
+ `CapturePayment` throws `InvalidPaymentStateError` when the payment is not
222
+ `authorized` or the amount exceeds what was authorized.
182
223
 
183
- Authorizations expire — after days, and by a rule that differs per provider and
184
- per card network. Capture promptly, and treat an expired authorization as a
185
- `payment.canceled` or `payment.failed` event rather than assuming the hold lasts.
224
+ `CancelPayment` voids an uncaptured payment and releases the hold. It throws
225
+ `InvalidPaymentStateError` when the payment was already captured or reached
226
+ another terminal status.
227
+
228
+ Authorizations expire after some days, by a rule that differs per provider and
229
+ per card network. Capture promptly. Expect an expired authorization to arrive as
230
+ a `payment.canceled` or `payment.failed` event, and do not assume the hold lasts.
186
231
 
187
232
  ## Refunds
188
233
 
189
234
  ```ts
190
- const refund = await RefundPayment(
191
- {
192
- payment: payment.id,
193
- amount: { value: 700, currency: "EUR" },
194
- reason: "requested_by_customer",
195
- },
196
- idempotencyKey,
197
- );
235
+ import { RefundPayment, type Payment } from "@antelopejs/interface-payment";
236
+
237
+ export async function refundPart(payment: Payment, idempotencyKey: string) {
238
+ const refund = await RefundPayment(
239
+ {
240
+ payment: payment.id,
241
+ amount: { value: 700, currency: "EUR" },
242
+ reason: "requested_by_customer",
243
+ },
244
+ idempotencyKey,
245
+ );
246
+ return refund;
247
+ }
198
248
  ```
199
249
 
200
- Omit `amount` to refund everything not yet refunded. Several partial refunds
201
- against one payment are allowed, up to the captured amount; `Payment.amountRefunded`
202
- tracks the running total, so the remaining refundable amount is
203
- `amountCaptured.value - amountRefunded.value`.
250
+ Omit `amount` to refund everything not yet refunded. The amount must be in the
251
+ payment's currency. You can make several partial refunds against one payment, up
252
+ to the captured amount. `Payment.amountRefunded` tracks the running total, so the
253
+ remaining refundable amount is `amountCaptured.value - amountRefunded.value`.
254
+ Refunding more than that throws `InvalidPaymentStateError`.
204
255
 
205
- **Refunds settle asynchronously on every provider this interface targets**, so
206
- the usual result of `RefundPayment` is a `Refund` with status `pending`. The
207
- terminal state arrives as a `refund.succeeded` or `refund.failed` event. Do not
208
- treat the call returning as the money having moved — a refund can still fail
209
- after being accepted, and a backend that credits the customer on the call alone
210
- will occasionally credit them for a refund that never landed.
256
+ **Refunds settle asynchronously on every provider this interface targets.** The
257
+ usual result of `RefundPayment` is a `Refund` with status `pending`. The terminal
258
+ state arrives as a `refund.succeeded` or `refund.failed` event. Do not treat the
259
+ returned call as money that has moved. A refund can still fail after the provider
260
+ accepts it. A backend that credits the customer on the call alone sometimes
261
+ credits them for a refund that never landed.
211
262
 
212
- `RefundStatus` is `pending`, `succeeded` or `failed`. `Refund.failure` is present
263
+ `RefundStatus` is `pending`, `succeeded`, or `failed`. `Refund.failure` is present
213
264
  exactly when the status is `failed`.
214
265
 
215
- `RefundReason` is `duplicate`, `fraudulent`, `requested_by_customer` or `other`.
216
- Providers that have no reason field take it as a note; providers that have one
217
- map the first three onto it. Either way the reason is for the provider's records
218
- and your own, not for the payer.
266
+ `RefundReason` is `duplicate`, `fraudulent`, `requested_by_customer`, or `other`.
267
+ A provider with no reason field takes it as a note. A provider with a reason field
268
+ maps the first three values onto it. Either way, the reason is for the provider's
269
+ records and your own, not for the payer.
219
270
 
220
271
  ## Errors
221
272
 
222
- | Error | When |
223
- | --------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
224
- | `PaymentNotFoundError` | No record under that identifier, including one the provider cannot parse |
225
- | `CustomerNotFoundError` | No customer or payment method under that identifier |
226
- | `InvalidPaymentStateError` | Well-formed, but not applicable to this payment's state — capturing something not authorized, refunding more than captured |
227
- | `WebhookVerificationError` | A delivery's signature does not verify |
228
- | `UnsupportedOperationError` | The provider does not offer the operation at all |
229
- | `PaymentError` | The base class; every error above is one |
230
-
231
- `UnsupportedOperationError` should be rare — the feature set is chosen so a
232
- typical backend never meets one. An implementation that raises it says so in its
233
- README, and raises it for every call to that function, never conditionally.
273
+ | Error | When |
274
+ | --------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
275
+ | `PaymentNotFoundError` | No payment, refund, or checkout session under that identifier, including an identifier the provider cannot parse |
276
+ | `CustomerNotFoundError` | No customer or payment method under that identifier, including an identifier the provider cannot parse |
277
+ | `InvalidPaymentStateError` | Well-formed, but not applicable to the payment's state, such as capturing a payment that is not authorized or over-refunding |
278
+ | `WebhookVerificationError` | A webhook delivery cannot be established as genuine |
279
+ | `UnsupportedOperationError` | The implementation does not offer the operation at all |
280
+ | `PaymentError` | The base class. Every error above extends it |
281
+
282
+ Every error has an optional `providerCode`, the provider's own error code,
283
+ verbatim and opaque. `InvalidPaymentStateError` also has an optional `status`,
284
+ the status the payment was actually in. `UnsupportedOperationError` has
285
+ `operation`, the name of the unavailable function.
286
+
287
+ `UnsupportedOperationError` is rare. The feature set is chosen so that a typical
288
+ backend never meets it. An implementation that raises it says so in its README,
289
+ and raises it for every call to that function, never conditionally.
@@ -1,17 +1,21 @@
1
- # Customers and saved payment methods
1
+ ---
2
+ title: Customers and saved payment methods
3
+ description: Create a customer, save a payment method during a payment, charge it off-session, and remove it.
4
+ mode: how-to
5
+ ---
2
6
 
3
- A customer is a container the provider associates saved payment methods with.
4
- Save a method once, charge it later with nobody present.
7
+ A customer is a container that the provider attaches saved payment methods to.
8
+ You save a method once and charge it later with nobody present.
5
9
 
6
- This is what makes recurring billing portable without modelling subscriptions: a
7
- backend selling monthly access saves a method, runs its own billing cycle, and
8
- charges off-session each period. That works on every provider here. A provider's
9
- own subscription object does not — see the
10
- [capability matrix](./5.provider-capability-matrix.md).
10
+ Saved methods make recurring billing portable without modelling subscriptions.
11
+ A backend that sells monthly access saves a method, runs its own billing cycle,
12
+ and charges the method off-session each period. That works on every provider in
13
+ the [capability matrix](./5.provider-capability-matrix.md). A provider's own
14
+ subscription object does not.
11
15
 
12
16
  ## Only the identifier round-trips
13
17
 
14
- ```ts
18
+ ```ts fragment
15
19
  const customer = await CreateCustomer(
16
20
  { email: user.email, name: user.fullName },
17
21
  idempotencyKey,
@@ -20,66 +24,99 @@ await users.update(user.id, { paymentCustomerId: customer.id });
20
24
  ```
21
25
 
22
26
  Store the identifier against your own user record. **Do not read the payer's
23
- details back out of the provider.** `email`, `name` and `metadata` are stored
24
- only by providers that have a first-class customer object; PayPal's vault and
25
- Adyen's `shopperReference` treat the identifier as a key they hang tokens on and
26
- store nothing else, so `GetCustomer` there returns the identifier alone.
27
+ details back from the provider.** Only providers with a first-class customer
28
+ object store `email`, `name`, and `metadata`. PayPal's vault and Adyen's
29
+ `shopperReference` use the identifier as a key for tokens and store nothing else,
30
+ so `GetCustomer` on those providers returns the identifier alone.
27
31
 
28
- The conformance suite asserts the identifier round-trips and nothing more, which
29
- is exactly the guarantee the contract makes. `GetCustomer` is for confirming a
30
- customer still exists, not for reading a profile you did not store yourself.
32
+ The conformance suite asserts that the identifier round-trips and nothing more,
33
+ which is the guarantee the contract makes. Use `GetCustomer` to confirm that a
34
+ customer still exists, not to read a profile you did not store yourself.
31
35
 
32
36
  ## Saving a method
33
37
 
34
- A method is saved as a side effect of a payment, not by a call of its own — no
35
- provider here lets you vault a card without the payer presenting it.
36
- `savePaymentMethod` sits on both payment paths and requires `customer` on either.
38
+ A payment saves a method as a side effect. No call saves one on its own, because
39
+ no provider here lets you store a card unless the payer presents it.
40
+ `savePaymentMethod` exists on both payment paths and requires `customer` on
41
+ either.
37
42
 
38
43
  Through hosted checkout:
39
44
 
40
45
  ```ts
41
- const session = await CreateCheckoutSession(
42
- {
43
- amount,
44
- reference: orderId,
45
- successUrl,
46
- cancelUrl,
47
- customer: user.paymentCustomerId,
48
- savePaymentMethod: true,
49
- },
50
- idempotencyKey,
51
- );
46
+ import {
47
+ CreateCheckoutSession,
48
+ type Amount,
49
+ } from "@antelopejs/interface-payment";
50
+
51
+ export async function startSavingCheckout(
52
+ amount: Amount,
53
+ orderId: string,
54
+ successUrl: string,
55
+ cancelUrl: string,
56
+ user: { paymentCustomerId: string },
57
+ idempotencyKey: string,
58
+ ) {
59
+ const session = await CreateCheckoutSession(
60
+ {
61
+ amount,
62
+ reference: orderId,
63
+ successUrl,
64
+ cancelUrl,
65
+ customer: user.paymentCustomerId,
66
+ savePaymentMethod: true,
67
+ },
68
+ idempotencyKey,
69
+ );
70
+ return session;
71
+ }
52
72
  ```
53
73
 
54
- On a direct payment, the same flag:
74
+ On a direct payment, set the same flag:
55
75
 
56
76
  ```ts
57
- const payment = await CreatePayment(
58
- {
59
- amount,
60
- reference: orderId,
61
- paymentMethod: presentedMethod,
62
- customer: user.paymentCustomerId,
63
- savePaymentMethod: true,
64
- returnUrl: "https://shop.example/payment-return",
65
- },
66
- idempotencyKey,
67
- );
77
+ import { CreatePayment, type Amount } from "@antelopejs/interface-payment";
78
+
79
+ export async function paySavingMethod(
80
+ amount: Amount,
81
+ orderId: string,
82
+ presentedMethod: string,
83
+ user: { paymentCustomerId: string },
84
+ idempotencyKey: string,
85
+ ) {
86
+ const payment = await CreatePayment(
87
+ {
88
+ amount,
89
+ reference: orderId,
90
+ paymentMethod: presentedMethod,
91
+ customer: user.paymentCustomerId,
92
+ savePaymentMethod: true,
93
+ returnUrl: "https://shop.example/payment-return",
94
+ },
95
+ idempotencyKey,
96
+ );
97
+ return payment;
98
+ }
68
99
  ```
69
100
 
70
- Set `returnUrl` to your application's return route even when charging a saved
101
+ `savePaymentMethod` and `offSession` are mutually exclusive. Saving a method takes
102
+ a mandate from the payer, so the payer must be present.
103
+
104
+ Set `returnUrl` to your application's return route, even when you charge a saved
71
105
  method on-session. If the result is `requires_action`, redirect the payer to
72
- `payment.redirectUrl`, then read the payment on the server after they return.
106
+ `payment.redirectUrl`. After they return, read the payment on the server.
73
107
 
74
- Either way the method appears in `ListPaymentMethods` once the payment reaches
75
- `succeeded` or `authorized` — not at session creation, not when the payer
76
- returns, and not as soon as `CreatePayment` resolves. Settlement is
77
- asynchronous; list after the payment has settled, or after the
108
+ On both paths, the method appears in `ListPaymentMethods` once the payment
109
+ reaches `succeeded` or `authorized`. It does not appear at session creation, when
110
+ the payer returns, or as soon as `CreatePayment` resolves. Settlement is
111
+ asynchronous, so list the methods after the payment has settled, or after the
78
112
  `payment.succeeded` event.
79
113
 
80
114
  ## Charging off-session
81
115
 
82
- ```ts
116
+ `ListPaymentMethods` returns the saved methods newest first, and an empty array
117
+ when there are none.
118
+
119
+ ```ts fragment
83
120
  const [method] = await ListPaymentMethods(user.paymentCustomerId);
84
121
  if (!method) return dunning.noMethodOnFile(user);
85
122
 
@@ -95,19 +132,21 @@ const payment = await CreatePayment(
95
132
  );
96
133
  ```
97
134
 
98
- The idempotency key is derived from the billing period, so a retried or
99
- duplicated renewal job replays within the provider-defined replay window.
100
- After expiration, reconcile uncertain payments before retrying: the same key
101
- may create another charge.
135
+ The example derives the idempotency key from the billing period. A retried or
136
+ duplicated renewal job then replays within the provider-defined replay window.
137
+ After the window expires, reconcile uncertain payments before you retry, because
138
+ the same key can create another charge.
102
139
 
103
- An off-session charge can still fail — the card expired, the bank wants the payer
104
- to authenticate, there is no money. It comes back `failed`, never
105
- `requires_action`, because there is nobody to send anywhere. Handle it by asking
140
+ An off-session charge can still fail. The card may have expired, the bank may
141
+ want the payer to authenticate, or the account may lack funds. The payment comes
142
+ back `failed`, never `requires_action`, because there is nobody to redirect. Ask
106
143
  the payer to return and pay on-session.
107
144
 
108
145
  ## What a saved method tells you
109
146
 
110
147
  ```ts
148
+ import type { CardDetails } from "@antelopejs/interface-payment";
149
+
111
150
  export interface PaymentMethod {
112
151
  id: string;
113
152
  type: "card" | "wallet" | "bank_account" | "other";
@@ -117,17 +156,19 @@ export interface PaymentMethod {
117
156
  }
118
157
  ```
119
158
 
120
- `card` is present when `type` is `card`: brand, last four digits, expiry month
121
- and year. Enough for a payer to recognise which card they saved, and nothing
122
- more — never the PAN, and never a token you could charge outside the provider.
159
+ `card` is present when `type` is `card`. It holds the brand, the last four
160
+ digits, the expiry month, and the expiry year. That is enough for a payer to
161
+ recognise the card they saved, and nothing more. It never holds the PAN, and
162
+ never a token you could charge outside the provider.
123
163
 
124
- A PayPal vault entry is a `wallet` and carries no `card`. Branch on `type` rather
125
- than assuming `card` is there.
164
+ A PayPal vault entry is a `wallet` and has no `card`. Branch on `type` instead of
165
+ assuming that `card` is there.
126
166
 
127
167
  ## Removing
128
168
 
129
- `DetachPaymentMethod` removes one method and leaves the customer.
169
+ `DetachPaymentMethod` removes one method and keeps the customer.
130
170
  `DeleteCustomer` removes the customer and detaches every method saved against it.
131
- Payments already taken are unaffected and stay readable by their identifiers —
132
- deleting a customer is not a way to erase a payment history, and refunds against
133
- past payments keep working.
171
+ Both throw `CustomerNotFoundError` for an unknown identifier. Payments already
172
+ taken are unaffected and stay readable by their identifiers. Deleting a customer
173
+ does not erase a payment history, and refunds against past payments keep
174
+ working.