@antelopejs/interface-payment 0.0.0-stage → 0.0.2
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/LICENSE +190 -0
- package/README.md +127 -2
- package/dist/antelope.test.d.ts +2 -0
- package/dist/antelope.test.js +10 -0
- package/dist/antelope.test.js.map +1 -0
- package/dist/errors.d.ts +78 -0
- package/dist/errors.js +101 -0
- package/dist/errors.js.map +1 -0
- package/dist/functions.d.ts +228 -0
- package/dist/functions.js +232 -0
- package/dist/functions.js.map +1 -0
- package/dist/index.d.ts +3 -0
- package/dist/index.js +20 -0
- package/dist/index.js.map +1 -0
- package/dist/tests/payment-charges.test.d.ts +1 -0
- package/dist/tests/payment-charges.test.js +188 -0
- package/dist/tests/payment-charges.test.js.map +1 -0
- package/dist/tests/payment.test.d.ts +1 -0
- package/dist/tests/payment.test.js +115 -0
- package/dist/tests/payment.test.js.map +1 -0
- package/dist/tests/support.d.ts +63 -0
- package/dist/tests/support.js +149 -0
- package/dist/tests/support.js.map +1 -0
- package/dist/types.d.ts +388 -0
- package/dist/types.js +87 -0
- package/dist/types.js.map +1 -0
- package/docs/1.introduction.md +91 -0
- package/docs/2.payments.md +233 -0
- package/docs/3.customers-and-methods.md +133 -0
- package/docs/4.webhooks.md +170 -0
- package/docs/5.provider-capability-matrix.md +147 -0
- package/docs/tsconfig.json +14 -0
- package/package.json +79 -4
- package/skills/taking-payments/SKILL.md +232 -0
package/dist/types.d.ts
ADDED
|
@@ -0,0 +1,388 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* A monetary amount as an integer number of minor units plus its currency.
|
|
3
|
+
*
|
|
4
|
+
* Minor units are the currency's smallest indivisible unit: cents for `EUR`,
|
|
5
|
+
* yen for `JPY` (which has no subunit), fils for `KWD` (which has three decimal
|
|
6
|
+
* places). `{ value: 1050, currency: "EUR" }` is €10.50. Never a float, and
|
|
7
|
+
* never a major-unit value.
|
|
8
|
+
*/
|
|
9
|
+
export interface Amount {
|
|
10
|
+
/** Integer number of minor units. Must not be fractional. */
|
|
11
|
+
value: number;
|
|
12
|
+
/** ISO-4217 alphabetic code, uppercase (e.g. `"EUR"`, `"USD"`, `"JPY"`). */
|
|
13
|
+
currency: string;
|
|
14
|
+
}
|
|
15
|
+
/**
|
|
16
|
+
* Every value {@link PaymentStatus} can take, in lifecycle order.
|
|
17
|
+
*/
|
|
18
|
+
export declare const PAYMENT_STATUSES: readonly ["pending", "requires_action", "authorized", "succeeded", "failed", "canceled"];
|
|
19
|
+
/**
|
|
20
|
+
* Normalised payment status.
|
|
21
|
+
*
|
|
22
|
+
* | Status | Meaning |
|
|
23
|
+
* | --- | --- |
|
|
24
|
+
* | `pending` | Accepted by the provider, no payer action outstanding, not yet settled. |
|
|
25
|
+
* | `requires_action` | The payer must be sent to {@link Payment.redirectUrl} (3DS/SCA, bank redirect, wallet approval). |
|
|
26
|
+
* | `authorized` | Funds are held. {@link CapturePayment} or {@link CancelPayment} must follow. |
|
|
27
|
+
* | `succeeded` | Captured. Terminal. |
|
|
28
|
+
* | `failed` | Declined, errored or expired without payment. Terminal. |
|
|
29
|
+
* | `canceled` | Voided before capture, by the merchant or by the payer abandoning. Terminal. |
|
|
30
|
+
*/
|
|
31
|
+
export type PaymentStatus = (typeof PAYMENT_STATUSES)[number];
|
|
32
|
+
/**
|
|
33
|
+
* Statuses from which a payment can no longer change without a new call.
|
|
34
|
+
*/
|
|
35
|
+
export declare const TERMINAL_PAYMENT_STATUSES: readonly PaymentStatus[];
|
|
36
|
+
/**
|
|
37
|
+
* Whether a payment has reached a state it cannot leave on its own.
|
|
38
|
+
*
|
|
39
|
+
* A non-terminal payment will change again, either because the payer acts or
|
|
40
|
+
* because settlement completes; expect a {@link PaymentEvent}.
|
|
41
|
+
*
|
|
42
|
+
* @param status - The status to classify
|
|
43
|
+
* @returns true for `succeeded`, `failed` and `canceled`
|
|
44
|
+
*/
|
|
45
|
+
export declare function isTerminalPaymentStatus(status: PaymentStatus): boolean;
|
|
46
|
+
/**
|
|
47
|
+
* Every value {@link PaymentFailureCode} can take.
|
|
48
|
+
*
|
|
49
|
+
* A coarse set, for branching. The verbatim code is available alongside it in
|
|
50
|
+
* {@link PaymentFailure.providerCode}.
|
|
51
|
+
*/
|
|
52
|
+
export declare const PAYMENT_FAILURE_CODES: readonly ["declined", "insufficient_funds", "expired_card", "incorrect_details", "authentication_failed", "canceled_by_payer", "expired", "processing_error"];
|
|
53
|
+
/** Normalised reason a payment or refund did not go through. */
|
|
54
|
+
export type PaymentFailureCode = (typeof PAYMENT_FAILURE_CODES)[number];
|
|
55
|
+
/**
|
|
56
|
+
* Detail attached to a `failed` payment or refund.
|
|
57
|
+
*/
|
|
58
|
+
export interface PaymentFailure {
|
|
59
|
+
/** Normalised reason, for branching. */
|
|
60
|
+
code: PaymentFailureCode;
|
|
61
|
+
/** Human-readable explanation, suitable for a log. Not for the payer. */
|
|
62
|
+
message: string;
|
|
63
|
+
/** The provider's own code, verbatim and opaque. For support tickets. */
|
|
64
|
+
providerCode?: string;
|
|
65
|
+
}
|
|
66
|
+
/**
|
|
67
|
+
* A payment, in whatever state it was last reported in.
|
|
68
|
+
*
|
|
69
|
+
* `id` is opaque: it is the provider's own identifier and carries no structure
|
|
70
|
+
* a caller may parse. Correlate with your own records through
|
|
71
|
+
* {@link Payment.reference}.
|
|
72
|
+
*/
|
|
73
|
+
export interface Payment {
|
|
74
|
+
/** Opaque provider identifier. */
|
|
75
|
+
id: string;
|
|
76
|
+
/** The amount the payment was created for. */
|
|
77
|
+
amount: Amount;
|
|
78
|
+
/**
|
|
79
|
+
* How much has been captured so far. Zero until capture.
|
|
80
|
+
* Always in {@link Payment.amount}'s currency.
|
|
81
|
+
*/
|
|
82
|
+
amountCaptured: Amount;
|
|
83
|
+
/**
|
|
84
|
+
* How much has been refunded so far. Zero until a refund settles.
|
|
85
|
+
* Always in {@link Payment.amount}'s currency.
|
|
86
|
+
*/
|
|
87
|
+
amountRefunded: Amount;
|
|
88
|
+
/** Normalised status. */
|
|
89
|
+
status: PaymentStatus;
|
|
90
|
+
/** The caller's own identifier, echoed back from the request. */
|
|
91
|
+
reference: string;
|
|
92
|
+
/** Opaque customer identifier, when the payment was attached to one. */
|
|
93
|
+
customer?: string;
|
|
94
|
+
/** Opaque payment method identifier, once the payer has chosen one. */
|
|
95
|
+
paymentMethod?: string;
|
|
96
|
+
/**
|
|
97
|
+
* Where to send the payer. Present exactly when `status` is
|
|
98
|
+
* `requires_action`.
|
|
99
|
+
*/
|
|
100
|
+
redirectUrl?: string;
|
|
101
|
+
/** Unix epoch milliseconds. */
|
|
102
|
+
createdAt: number;
|
|
103
|
+
/** Present exactly when `status` is `failed`. */
|
|
104
|
+
failure?: PaymentFailure;
|
|
105
|
+
/** The metadata the payment was created with. */
|
|
106
|
+
metadata?: Record<string, string>;
|
|
107
|
+
}
|
|
108
|
+
/**
|
|
109
|
+
* Parameters for {@link CreatePayment}.
|
|
110
|
+
*/
|
|
111
|
+
export interface PaymentRequest {
|
|
112
|
+
/** What to charge. */
|
|
113
|
+
amount: Amount;
|
|
114
|
+
/** Your own identifier for this payment. Echoed back on {@link Payment}. */
|
|
115
|
+
reference: string;
|
|
116
|
+
/**
|
|
117
|
+
* Authorize only, leaving capture to a later {@link CapturePayment}.
|
|
118
|
+
* Defaults to false, which captures immediately.
|
|
119
|
+
*/
|
|
120
|
+
authorizeOnly?: boolean;
|
|
121
|
+
/**
|
|
122
|
+
* Opaque identifier of a saved payment method to charge, from
|
|
123
|
+
* {@link ListPaymentMethods}.
|
|
124
|
+
*/
|
|
125
|
+
paymentMethod?: string;
|
|
126
|
+
/** Opaque customer identifier to attach the payment to. */
|
|
127
|
+
customer?: string;
|
|
128
|
+
/**
|
|
129
|
+
* The payer is not present and cannot be prompted. The provider will not
|
|
130
|
+
* return `requires_action`; it declines instead. Requires `paymentMethod`.
|
|
131
|
+
*/
|
|
132
|
+
offSession?: boolean;
|
|
133
|
+
/**
|
|
134
|
+
* Save the method this payment uses for later off-session charges.
|
|
135
|
+
*
|
|
136
|
+
* Requires `customer`. Mutually exclusive with `offSession`: saving a method
|
|
137
|
+
* takes a mandate from the payer, so the payer must be present.
|
|
138
|
+
*
|
|
139
|
+
* The saved method appears in {@link ListPaymentMethods} once the payment
|
|
140
|
+
* reaches `succeeded` or `authorized` — not as soon as this call returns.
|
|
141
|
+
*/
|
|
142
|
+
savePaymentMethod?: boolean;
|
|
143
|
+
/**
|
|
144
|
+
* Where to return the payer after an interactive step. Required unless
|
|
145
|
+
* `offSession` is set: any payment may turn out to need authentication.
|
|
146
|
+
*/
|
|
147
|
+
returnUrl?: string;
|
|
148
|
+
/** Shown to the payer where supported. */
|
|
149
|
+
description?: string;
|
|
150
|
+
/** Round-tripped opaque key/value pairs. */
|
|
151
|
+
metadata?: Record<string, string>;
|
|
152
|
+
}
|
|
153
|
+
/**
|
|
154
|
+
* Parameters for {@link CreateCheckoutSession}.
|
|
155
|
+
*/
|
|
156
|
+
export interface CheckoutSessionRequest {
|
|
157
|
+
/** What to charge. */
|
|
158
|
+
amount: Amount;
|
|
159
|
+
/** Your own identifier for this payment. Echoed back on {@link Payment}. */
|
|
160
|
+
reference: string;
|
|
161
|
+
/** Where the provider sends the payer after a completed payment. */
|
|
162
|
+
successUrl: string;
|
|
163
|
+
/** Where the provider sends the payer if they abandon. */
|
|
164
|
+
cancelUrl: string;
|
|
165
|
+
/**
|
|
166
|
+
* Authorize only, leaving capture to a later {@link CapturePayment}.
|
|
167
|
+
* Defaults to false.
|
|
168
|
+
*/
|
|
169
|
+
authorizeOnly?: boolean;
|
|
170
|
+
/** Opaque customer identifier to attach the payment to. */
|
|
171
|
+
customer?: string;
|
|
172
|
+
/**
|
|
173
|
+
* Save the method the payer chooses for later off-session charges.
|
|
174
|
+
* Requires `customer`. The saved method appears in
|
|
175
|
+
* {@link ListPaymentMethods} once the payment reaches `succeeded` or
|
|
176
|
+
* `authorized`.
|
|
177
|
+
*/
|
|
178
|
+
savePaymentMethod?: boolean;
|
|
179
|
+
/** Shown to the payer where supported. */
|
|
180
|
+
description?: string;
|
|
181
|
+
/** BCP-47 language tag for the hosted page, where supported. */
|
|
182
|
+
locale?: string;
|
|
183
|
+
/** Round-tripped opaque key/value pairs. */
|
|
184
|
+
metadata?: Record<string, string>;
|
|
185
|
+
}
|
|
186
|
+
/**
|
|
187
|
+
* A hosted checkout session: an externally hosted page that takes the payment.
|
|
188
|
+
*/
|
|
189
|
+
export interface CheckoutSession {
|
|
190
|
+
/** Opaque provider identifier for the session. */
|
|
191
|
+
id: string;
|
|
192
|
+
/** Send the payer here. */
|
|
193
|
+
redirectUrl: string;
|
|
194
|
+
/** Status of the payment behind the session. */
|
|
195
|
+
status: PaymentStatus;
|
|
196
|
+
/**
|
|
197
|
+
* Opaque identifier of the payment the session produced, for
|
|
198
|
+
* {@link GetPayment}, {@link CapturePayment} and {@link RefundPayment}.
|
|
199
|
+
*
|
|
200
|
+
* Absent until a payment exists behind the session, which may not be until
|
|
201
|
+
* the payer has acted. May be equal to {@link CheckoutSession.id}.
|
|
202
|
+
*/
|
|
203
|
+
payment?: string;
|
|
204
|
+
/** Unix epoch milliseconds after which `redirectUrl` stops working. */
|
|
205
|
+
expiresAt?: number;
|
|
206
|
+
}
|
|
207
|
+
/** Normalised refund lifecycle. */
|
|
208
|
+
export declare const REFUND_STATUSES: readonly ["pending", "succeeded", "failed"];
|
|
209
|
+
/**
|
|
210
|
+
* Normalised refund status.
|
|
211
|
+
*
|
|
212
|
+
* `pending` is the usual result of {@link RefundPayment}; the terminal state
|
|
213
|
+
* arrives as a `refund.succeeded` or `refund.failed` {@link PaymentEvent}.
|
|
214
|
+
*/
|
|
215
|
+
export type RefundStatus = (typeof REFUND_STATUSES)[number];
|
|
216
|
+
/**
|
|
217
|
+
* Every value {@link RefundReason} can take.
|
|
218
|
+
*/
|
|
219
|
+
export declare const REFUND_REASONS: readonly ["duplicate", "fraudulent", "requested_by_customer", "other"];
|
|
220
|
+
/** Normalised refund reason. */
|
|
221
|
+
export type RefundReason = (typeof REFUND_REASONS)[number];
|
|
222
|
+
/**
|
|
223
|
+
* A refund against a captured payment.
|
|
224
|
+
*/
|
|
225
|
+
export interface Refund {
|
|
226
|
+
/** Opaque provider identifier. */
|
|
227
|
+
id: string;
|
|
228
|
+
/** Opaque identifier of the payment refunded. */
|
|
229
|
+
payment: string;
|
|
230
|
+
/** How much was refunded. */
|
|
231
|
+
amount: Amount;
|
|
232
|
+
/** Normalised status. */
|
|
233
|
+
status: RefundStatus;
|
|
234
|
+
/** Unix epoch milliseconds. */
|
|
235
|
+
createdAt: number;
|
|
236
|
+
/** Present exactly when `status` is `failed`. */
|
|
237
|
+
failure?: PaymentFailure;
|
|
238
|
+
/** The metadata the refund was created with. */
|
|
239
|
+
metadata?: Record<string, string>;
|
|
240
|
+
}
|
|
241
|
+
/**
|
|
242
|
+
* Parameters for {@link RefundPayment}.
|
|
243
|
+
*/
|
|
244
|
+
export interface RefundRequest {
|
|
245
|
+
/** Opaque identifier of the payment to refund. */
|
|
246
|
+
payment: string;
|
|
247
|
+
/**
|
|
248
|
+
* How much to refund. Omit to refund everything not yet refunded.
|
|
249
|
+
* Must be in the payment's currency.
|
|
250
|
+
*/
|
|
251
|
+
amount?: Amount;
|
|
252
|
+
/** Why, for the provider's records. */
|
|
253
|
+
reason?: RefundReason;
|
|
254
|
+
/** Round-tripped opaque key/value pairs. */
|
|
255
|
+
metadata?: Record<string, string>;
|
|
256
|
+
}
|
|
257
|
+
/**
|
|
258
|
+
* A customer: the container saved payment methods are attached to.
|
|
259
|
+
*
|
|
260
|
+
* Only `id` is guaranteed to survive a round trip; {@link GetCustomer} may
|
|
261
|
+
* return it alone. Keep the payer's details in your own records rather than
|
|
262
|
+
* reading them back from here.
|
|
263
|
+
*/
|
|
264
|
+
export interface Customer {
|
|
265
|
+
/** Opaque provider identifier. */
|
|
266
|
+
id: string;
|
|
267
|
+
/** Not guaranteed to survive a round trip. */
|
|
268
|
+
email?: string;
|
|
269
|
+
/** Not guaranteed to survive a round trip. */
|
|
270
|
+
name?: string;
|
|
271
|
+
/** Not guaranteed to survive a round trip. */
|
|
272
|
+
metadata?: Record<string, string>;
|
|
273
|
+
}
|
|
274
|
+
/**
|
|
275
|
+
* Parameters for {@link CreateCustomer}.
|
|
276
|
+
*/
|
|
277
|
+
export interface CustomerRequest {
|
|
278
|
+
/** Stored where supported. */
|
|
279
|
+
email?: string;
|
|
280
|
+
/** Stored where supported. */
|
|
281
|
+
name?: string;
|
|
282
|
+
/** Stored where supported. */
|
|
283
|
+
metadata?: Record<string, string>;
|
|
284
|
+
}
|
|
285
|
+
/** Broad category of a saved payment method. */
|
|
286
|
+
export declare const PAYMENT_METHOD_TYPES: readonly ["card", "wallet", "bank_account", "other"];
|
|
287
|
+
/** Normalised payment method category. */
|
|
288
|
+
export type PaymentMethodType = (typeof PAYMENT_METHOD_TYPES)[number];
|
|
289
|
+
/**
|
|
290
|
+
* The displayable parts of a saved card.
|
|
291
|
+
*
|
|
292
|
+
* Enough to let a payer recognise which card they saved, and nothing more.
|
|
293
|
+
* Never the PAN, never a token you could charge directly.
|
|
294
|
+
*/
|
|
295
|
+
export interface CardDetails {
|
|
296
|
+
/** Network name as the provider reports it, e.g. `"visa"`. Opaque. */
|
|
297
|
+
brand: string;
|
|
298
|
+
/** Final four digits of the PAN. */
|
|
299
|
+
last4: string;
|
|
300
|
+
/** Expiry month, 1-12. */
|
|
301
|
+
expiryMonth: number;
|
|
302
|
+
/** Expiry year, four digits. */
|
|
303
|
+
expiryYear: number;
|
|
304
|
+
}
|
|
305
|
+
/**
|
|
306
|
+
* A payment method saved against a customer and chargeable off-session.
|
|
307
|
+
*/
|
|
308
|
+
export interface PaymentMethod {
|
|
309
|
+
/** Opaque provider identifier. Pass to {@link PaymentRequest.paymentMethod}. */
|
|
310
|
+
id: string;
|
|
311
|
+
/** Broad category. */
|
|
312
|
+
type: PaymentMethodType;
|
|
313
|
+
/** Opaque identifier of the customer it is saved against. */
|
|
314
|
+
customer: string;
|
|
315
|
+
/** Present when `type` is `card`. */
|
|
316
|
+
card?: CardDetails;
|
|
317
|
+
/** Unix epoch milliseconds. */
|
|
318
|
+
createdAt: number;
|
|
319
|
+
}
|
|
320
|
+
/**
|
|
321
|
+
* A payer's challenge to a captured payment.
|
|
322
|
+
*
|
|
323
|
+
* Reported so a backend can react — hold the goods, notify someone. Responding
|
|
324
|
+
* to a dispute is not modelled.
|
|
325
|
+
*/
|
|
326
|
+
export interface Dispute {
|
|
327
|
+
/** Opaque provider identifier. */
|
|
328
|
+
id: string;
|
|
329
|
+
/** Opaque identifier of the payment being disputed. */
|
|
330
|
+
payment: string;
|
|
331
|
+
/** The amount under dispute. */
|
|
332
|
+
amount: Amount;
|
|
333
|
+
/** The provider's own reason string, verbatim and opaque. */
|
|
334
|
+
reason?: string;
|
|
335
|
+
/** Unix epoch milliseconds. */
|
|
336
|
+
createdAt: number;
|
|
337
|
+
}
|
|
338
|
+
/**
|
|
339
|
+
* Every value {@link PaymentEventType} can take.
|
|
340
|
+
*
|
|
341
|
+
* The `payment.*` types are every {@link PaymentStatus} except
|
|
342
|
+
* `requires_action`, which is known synchronously from the call that created
|
|
343
|
+
* the payment and so never arrives as an event.
|
|
344
|
+
*/
|
|
345
|
+
export declare const PAYMENT_EVENT_TYPES: readonly ["payment.pending", "payment.authorized", "payment.succeeded", "payment.failed", "payment.canceled", "refund.succeeded", "refund.failed", "dispute.opened"];
|
|
346
|
+
/** Normalised webhook event type. */
|
|
347
|
+
export type PaymentEventType = (typeof PAYMENT_EVENT_TYPES)[number];
|
|
348
|
+
/**
|
|
349
|
+
* A verified webhook delivery, normalised.
|
|
350
|
+
*
|
|
351
|
+
* Exactly one of `payment`, `refund` and `dispute` is set, matching the `type`
|
|
352
|
+
* prefix. It carries the state at the moment the event was sent, which may
|
|
353
|
+
* already be stale.
|
|
354
|
+
*/
|
|
355
|
+
export interface PaymentEvent {
|
|
356
|
+
/**
|
|
357
|
+
* Opaque identifier for the delivery.
|
|
358
|
+
*
|
|
359
|
+
* Deliveries repeat and arrive out of order. Treat handling as idempotent and
|
|
360
|
+
* de-duplicate on this id.
|
|
361
|
+
*/
|
|
362
|
+
id: string;
|
|
363
|
+
/** Normalised type. */
|
|
364
|
+
type: PaymentEventType;
|
|
365
|
+
/** Unix epoch milliseconds, as reported with the delivery. */
|
|
366
|
+
createdAt: number;
|
|
367
|
+
/** Set when `type` starts with `payment.`. */
|
|
368
|
+
payment?: Payment;
|
|
369
|
+
/** Set when `type` starts with `refund.`. */
|
|
370
|
+
refund?: Refund;
|
|
371
|
+
/** Set when `type` is `dispute.opened`. */
|
|
372
|
+
dispute?: Dispute;
|
|
373
|
+
}
|
|
374
|
+
/**
|
|
375
|
+
* A webhook delivery, exactly as it arrived.
|
|
376
|
+
*/
|
|
377
|
+
export interface WebhookRequest {
|
|
378
|
+
/**
|
|
379
|
+
* The unparsed request body, exactly as it arrived.
|
|
380
|
+
*
|
|
381
|
+
* A body that has been through `JSON.parse` and re-serialised will not
|
|
382
|
+
* verify. Read it with a raw body handler. A Node `Buffer` is a
|
|
383
|
+
* `Uint8Array` and can be passed straight through.
|
|
384
|
+
*/
|
|
385
|
+
body: Uint8Array;
|
|
386
|
+
/** Every request header, lowercased names. */
|
|
387
|
+
headers: Record<string, string | string[] | undefined>;
|
|
388
|
+
}
|
package/dist/types.js
ADDED
|
@@ -0,0 +1,87 @@
|
|
|
1
|
+
"use strict";
|
|
2
|
+
Object.defineProperty(exports, "__esModule", { value: true });
|
|
3
|
+
exports.PAYMENT_EVENT_TYPES = exports.PAYMENT_METHOD_TYPES = exports.REFUND_REASONS = exports.REFUND_STATUSES = exports.PAYMENT_FAILURE_CODES = exports.TERMINAL_PAYMENT_STATUSES = exports.PAYMENT_STATUSES = void 0;
|
|
4
|
+
exports.isTerminalPaymentStatus = isTerminalPaymentStatus;
|
|
5
|
+
/**
|
|
6
|
+
* Every value {@link PaymentStatus} can take, in lifecycle order.
|
|
7
|
+
*/
|
|
8
|
+
exports.PAYMENT_STATUSES = Object.freeze([
|
|
9
|
+
"pending",
|
|
10
|
+
"requires_action",
|
|
11
|
+
"authorized",
|
|
12
|
+
"succeeded",
|
|
13
|
+
"failed",
|
|
14
|
+
"canceled",
|
|
15
|
+
]);
|
|
16
|
+
/**
|
|
17
|
+
* Statuses from which a payment can no longer change without a new call.
|
|
18
|
+
*/
|
|
19
|
+
exports.TERMINAL_PAYMENT_STATUSES = Object.freeze(["succeeded", "failed", "canceled"]);
|
|
20
|
+
/**
|
|
21
|
+
* Whether a payment has reached a state it cannot leave on its own.
|
|
22
|
+
*
|
|
23
|
+
* A non-terminal payment will change again, either because the payer acts or
|
|
24
|
+
* because settlement completes; expect a {@link PaymentEvent}.
|
|
25
|
+
*
|
|
26
|
+
* @param status - The status to classify
|
|
27
|
+
* @returns true for `succeeded`, `failed` and `canceled`
|
|
28
|
+
*/
|
|
29
|
+
function isTerminalPaymentStatus(status) {
|
|
30
|
+
return exports.TERMINAL_PAYMENT_STATUSES.includes(status);
|
|
31
|
+
}
|
|
32
|
+
/**
|
|
33
|
+
* Every value {@link PaymentFailureCode} can take.
|
|
34
|
+
*
|
|
35
|
+
* A coarse set, for branching. The verbatim code is available alongside it in
|
|
36
|
+
* {@link PaymentFailure.providerCode}.
|
|
37
|
+
*/
|
|
38
|
+
exports.PAYMENT_FAILURE_CODES = Object.freeze([
|
|
39
|
+
"declined",
|
|
40
|
+
"insufficient_funds",
|
|
41
|
+
"expired_card",
|
|
42
|
+
"incorrect_details",
|
|
43
|
+
"authentication_failed",
|
|
44
|
+
"canceled_by_payer",
|
|
45
|
+
"expired",
|
|
46
|
+
"processing_error",
|
|
47
|
+
]);
|
|
48
|
+
/** Normalised refund lifecycle. */
|
|
49
|
+
exports.REFUND_STATUSES = Object.freeze([
|
|
50
|
+
"pending",
|
|
51
|
+
"succeeded",
|
|
52
|
+
"failed",
|
|
53
|
+
]);
|
|
54
|
+
/**
|
|
55
|
+
* Every value {@link RefundReason} can take.
|
|
56
|
+
*/
|
|
57
|
+
exports.REFUND_REASONS = Object.freeze([
|
|
58
|
+
"duplicate",
|
|
59
|
+
"fraudulent",
|
|
60
|
+
"requested_by_customer",
|
|
61
|
+
"other",
|
|
62
|
+
]);
|
|
63
|
+
/** Broad category of a saved payment method. */
|
|
64
|
+
exports.PAYMENT_METHOD_TYPES = Object.freeze([
|
|
65
|
+
"card",
|
|
66
|
+
"wallet",
|
|
67
|
+
"bank_account",
|
|
68
|
+
"other",
|
|
69
|
+
]);
|
|
70
|
+
/**
|
|
71
|
+
* Every value {@link PaymentEventType} can take.
|
|
72
|
+
*
|
|
73
|
+
* The `payment.*` types are every {@link PaymentStatus} except
|
|
74
|
+
* `requires_action`, which is known synchronously from the call that created
|
|
75
|
+
* the payment and so never arrives as an event.
|
|
76
|
+
*/
|
|
77
|
+
exports.PAYMENT_EVENT_TYPES = Object.freeze([
|
|
78
|
+
"payment.pending",
|
|
79
|
+
"payment.authorized",
|
|
80
|
+
"payment.succeeded",
|
|
81
|
+
"payment.failed",
|
|
82
|
+
"payment.canceled",
|
|
83
|
+
"refund.succeeded",
|
|
84
|
+
"refund.failed",
|
|
85
|
+
"dispute.opened",
|
|
86
|
+
]);
|
|
87
|
+
//# sourceMappingURL=types.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":";;;AAwDA,0DAEC;AA3CD;;GAEG;AACU,QAAA,gBAAgB,GAAG,MAAM,CAAC,MAAM,CAAC;IAC5C,SAAS;IACT,iBAAiB;IACjB,YAAY;IACZ,WAAW;IACX,QAAQ;IACR,UAAU;CACF,CAAC,CAAC;AAgBZ;;GAEG;AACU,QAAA,yBAAyB,GACpC,MAAM,CAAC,MAAM,CAAC,CAAC,WAAW,EAAE,QAAQ,EAAE,UAAU,CAAC,CAAC,CAAC;AAErD;;;;;;;;GAQG;AACH,SAAgB,uBAAuB,CAAC,MAAqB;IAC3D,OAAO,iCAAyB,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;AACpD,CAAC;AAED;;;;;GAKG;AACU,QAAA,qBAAqB,GAAG,MAAM,CAAC,MAAM,CAAC;IACjD,UAAU;IACV,oBAAoB;IACpB,cAAc;IACd,mBAAmB;IACnB,uBAAuB;IACvB,mBAAmB;IACnB,SAAS;IACT,kBAAkB;CACV,CAAC,CAAC;AAkKZ,mCAAmC;AACtB,QAAA,eAAe,GAAG,MAAM,CAAC,MAAM,CAAC;IAC3C,SAAS;IACT,WAAW;IACX,QAAQ;CACA,CAAC,CAAC;AAUZ;;GAEG;AACU,QAAA,cAAc,GAAG,MAAM,CAAC,MAAM,CAAC;IAC1C,WAAW;IACX,YAAY;IACZ,uBAAuB;IACvB,OAAO;CACC,CAAC,CAAC;AAwEZ,gDAAgD;AACnC,QAAA,oBAAoB,GAAG,MAAM,CAAC,MAAM,CAAC;IAChD,MAAM;IACN,QAAQ;IACR,cAAc;IACd,OAAO;CACC,CAAC,CAAC;AAyDZ;;;;;;GAMG;AACU,QAAA,mBAAmB,GAAG,MAAM,CAAC,MAAM,CAAC;IAC/C,iBAAiB;IACjB,oBAAoB;IACpB,mBAAmB;IACnB,gBAAgB;IAChB,kBAAkB;IAClB,kBAAkB;IAClB,eAAe;IACf,gBAAgB;CACR,CAAC,CAAC"}
|
|
@@ -0,0 +1,91 @@
|
|
|
1
|
+
# Introduction
|
|
2
|
+
|
|
3
|
+
`@antelopejs/interface-payment` defines a provider-agnostic payment interface for
|
|
4
|
+
AntelopeJS applications. A backend written against it takes payments, refunds
|
|
5
|
+
them, saves payment methods and reacts to settlement events without naming a
|
|
6
|
+
provider, and can change provider by swapping the module wired underneath.
|
|
7
|
+
|
|
8
|
+
## What it covers
|
|
9
|
+
|
|
10
|
+
| Area | Functions |
|
|
11
|
+
| --------------------------- | ---------------------------------------------------------------------------------------------- |
|
|
12
|
+
| Hosted checkout | `CreateCheckoutSession`, `GetCheckoutSession` |
|
|
13
|
+
| Direct payments | `CreatePayment`, `GetPayment`, `CapturePayment`, `CancelPayment` |
|
|
14
|
+
| Refunds | `RefundPayment`, `GetRefund` |
|
|
15
|
+
| Customers and saved methods | `CreateCustomer`, `GetCustomer`, `DeleteCustomer`, `ListPaymentMethods`, `DetachPaymentMethod` |
|
|
16
|
+
| Webhooks | `VerifyWebhook` |
|
|
17
|
+
|
|
18
|
+
## What it deliberately does not cover
|
|
19
|
+
|
|
20
|
+
Subscriptions, invoicing, proration, dunning, tax and coupons; marketplace split
|
|
21
|
+
payments; dispute _management_; payment links; in-person terminals.
|
|
22
|
+
|
|
23
|
+
These are where providers diverge most, and modelling them would mean an
|
|
24
|
+
interface most implementations could only decline. For recurring access, use
|
|
25
|
+
`@antelopejs/interface-subscriptions`: Stripe native billing is recommended with
|
|
26
|
+
Stripe. Choose `@antelopejs/payment-subscriptions` explicitly when you need a
|
|
27
|
+
generic clock on saved methods and off-session charges. Each subscription must
|
|
28
|
+
have one renewal owner; provider-specific billing features remain outside the
|
|
29
|
+
portable contract.
|
|
30
|
+
[Provider capability matrix](./5.provider-capability-matrix.md) has the reasoning
|
|
31
|
+
per feature.
|
|
32
|
+
|
|
33
|
+
When a backend needs something beyond this contract, it uses the provider's own
|
|
34
|
+
interface — `@antelopejs/interface-stripe` for Stripe — alongside this one. That
|
|
35
|
+
is the escape hatch, and it is why this interface does not have one of its own:
|
|
36
|
+
an escape hatch here would hand back a provider-shaped object and quietly undo
|
|
37
|
+
the portability the interface exists for.
|
|
38
|
+
|
|
39
|
+
## Installation
|
|
40
|
+
|
|
41
|
+
```bash
|
|
42
|
+
pnpm add @antelopejs/interface-payment
|
|
43
|
+
```
|
|
44
|
+
|
|
45
|
+
Add a module that implements it to your Antelope config; this package declares
|
|
46
|
+
the contract and ships no provider logic.
|
|
47
|
+
|
|
48
|
+
## Conventions
|
|
49
|
+
|
|
50
|
+
These hold across every function, and an implementation that breaks one is
|
|
51
|
+
non-conformant.
|
|
52
|
+
|
|
53
|
+
**Amounts are integer minor units.** `{ value: 1050, currency: "EUR" }` is €10.50.
|
|
54
|
+
Never a float: binary floating point cannot represent most decimal amounts, and
|
|
55
|
+
providers round differently when you hand them one. `JPY` has no subunit, so
|
|
56
|
+
`{ value: 1050, currency: "JPY" }` is ¥1050. `KWD` has three decimal places.
|
|
57
|
+
Every derived amount on a `Payment` — `amountCaptured`, `amountRefunded` — is in
|
|
58
|
+
the same currency as `amount`.
|
|
59
|
+
|
|
60
|
+
**Every mutating call takes an idempotency key.** Payments are the canonical case
|
|
61
|
+
where a retried request must not do the work twice. Generate one key per
|
|
62
|
+
logical operation, store it with your own record, and reuse it on retry: the
|
|
63
|
+
provider returns the original result within its provider-defined replay window.
|
|
64
|
+
Reads take no key. After expiration, applications must reconcile uncertain
|
|
65
|
+
payments with provider records before retrying; a reused key can charge again.
|
|
66
|
+
|
|
67
|
+
**Provider identifiers are opaque.** `Payment.id`, `Refund.id`, `Customer.id`,
|
|
68
|
+
`PaymentMethod.id` and `CheckoutSession.id` are the provider's own strings. Do
|
|
69
|
+
not parse them, do not infer a type from a prefix, and do not assume two
|
|
70
|
+
providers shape them alike. Correlate with your own records through
|
|
71
|
+
`reference` and `metadata`.
|
|
72
|
+
|
|
73
|
+
**A failed payment is not a thrown error.** `CreatePayment` resolves with a
|
|
74
|
+
`Payment` whose status is `failed`; it rejects only when the call itself could
|
|
75
|
+
not be made. See [Payments](./2.payments.md).
|
|
76
|
+
|
|
77
|
+
**Settlement is asynchronous.** Every provider this interface targets settles
|
|
78
|
+
some payments after the call returns, and some after the payer has left. A
|
|
79
|
+
terminal state is learned from `VerifyWebhook`, not from the payer's return to
|
|
80
|
+
your `successUrl`. See [Webhooks](./4.webhooks.md).
|
|
81
|
+
|
|
82
|
+
## Multi-account setups
|
|
83
|
+
|
|
84
|
+
Every function takes an optional trailing `provider` argument naming which
|
|
85
|
+
configured account to use, for a backend running more than one merchant account
|
|
86
|
+
or more than one provider at once. Omit it for the default.
|
|
87
|
+
|
|
88
|
+
```ts
|
|
89
|
+
await CreatePayment(request, key); // default account
|
|
90
|
+
await CreatePayment(request, key, "marketplace"); // a named one
|
|
91
|
+
```
|