@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.
- package/README.md +59 -49
- package/dist/types.d.ts +14 -2
- package/dist/types.js +49 -1
- package/dist/types.js.map +1 -1
- package/docs/1.introduction.md +58 -43
- package/docs/2.payments.md +180 -124
- package/docs/3.customers-and-methods.md +106 -65
- package/docs/4.webhooks.md +103 -88
- package/docs/5.provider-capability-matrix.md +85 -74
- package/docs/tsconfig.json +2 -0
- package/package.json +12 -3
package/docs/2.payments.md
CHANGED
|
@@ -1,14 +1,18 @@
|
|
|
1
|
-
|
|
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
|
-
|
|
4
|
-
payment
|
|
5
|
-
`Payment
|
|
6
|
-
|
|
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
|
|
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
|
|
23
|
-
|
|
24
|
-
|
|
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`.
|
|
28
|
-
|
|
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.
|
|
33
|
-
|
|
34
|
-
|
|
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
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
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
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
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
|
|
78
|
-
|
|
79
|
-
both fields
|
|
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.
|
|
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
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
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
|
|
100
|
-
`requires_action
|
|
101
|
-
|
|
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.
|
|
118
|
-
|
|
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
|
|
122
|
-
credentials, a malformed request, an unreachable provider. A
|
|
123
|
-
issuer is a `Payment` with status `failed` and a populated
|
|
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
|
-
|
|
126
|
-
or asynchronously as a `payment.failed` event, depending on
|
|
127
|
-
method.
|
|
128
|
-
|
|
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
|
|
132
|
-
`
|
|
133
|
-
`expired`, `processing_error`.
|
|
134
|
-
|
|
135
|
-
|
|
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
|
-
###
|
|
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
|
|
141
|
-
|
|
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
|
|
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
|
-
|
|
155
|
-
|
|
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
|
-
|
|
159
|
-
|
|
160
|
-
|
|
161
|
-
|
|
162
|
-
|
|
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
|
-
|
|
171
|
-
|
|
172
|
-
|
|
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
|
|
178
|
-
|
|
179
|
-
|
|
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
|
-
`
|
|
221
|
+
`CapturePayment` throws `InvalidPaymentStateError` when the payment is not
|
|
222
|
+
`authorized` or the amount exceeds what was authorized.
|
|
182
223
|
|
|
183
|
-
|
|
184
|
-
|
|
185
|
-
|
|
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
|
-
|
|
191
|
-
|
|
192
|
-
|
|
193
|
-
|
|
194
|
-
|
|
195
|
-
|
|
196
|
-
|
|
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.
|
|
201
|
-
|
|
202
|
-
tracks the running total, so the
|
|
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
|
|
206
|
-
|
|
207
|
-
|
|
208
|
-
|
|
209
|
-
|
|
210
|
-
|
|
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
|
|
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
|
|
216
|
-
|
|
217
|
-
|
|
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
|
|
225
|
-
| `CustomerNotFoundError` | No customer or payment method under that identifier
|
|
226
|
-
| `InvalidPaymentStateError` | Well-formed, but not applicable to
|
|
227
|
-
| `WebhookVerificationError` | A delivery
|
|
228
|
-
| `UnsupportedOperationError` | The
|
|
229
|
-
| `PaymentError` | The base class
|
|
230
|
-
|
|
231
|
-
|
|
232
|
-
|
|
233
|
-
|
|
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
|
-
|
|
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
|
|
4
|
-
|
|
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
|
-
|
|
7
|
-
backend
|
|
8
|
-
charges off-session each period. That works on every provider
|
|
9
|
-
|
|
10
|
-
|
|
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
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
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,
|
|
29
|
-
is
|
|
30
|
-
customer still exists, not
|
|
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
|
|
35
|
-
provider here lets you
|
|
36
|
-
`savePaymentMethod`
|
|
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
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
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
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
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
|
-
|
|
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
|
|
106
|
+
`payment.redirectUrl`. After they return, read the payment on the server.
|
|
73
107
|
|
|
74
|
-
|
|
75
|
-
`succeeded` or `authorized
|
|
76
|
-
returns,
|
|
77
|
-
asynchronous
|
|
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
|
-
|
|
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
|
|
99
|
-
duplicated renewal job replays within the provider-defined replay window.
|
|
100
|
-
After
|
|
101
|
-
|
|
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
|
|
104
|
-
to authenticate,
|
|
105
|
-
`requires_action`, because there is nobody to
|
|
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
|
|
121
|
-
and year.
|
|
122
|
-
|
|
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
|
|
125
|
-
|
|
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
|
|
169
|
+
`DetachPaymentMethod` removes one method and keeps the customer.
|
|
130
170
|
`DeleteCustomer` removes the customer and detaches every method saved against it.
|
|
131
|
-
|
|
132
|
-
|
|
133
|
-
past payments keep
|
|
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.
|