@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/README.md
CHANGED
|
@@ -1,15 +1,16 @@
|
|
|
1
|
-
#
|
|
1
|
+
# `@antelopejs/interface-payment`
|
|
2
2
|
|
|
3
3
|
<div align="center">
|
|
4
|
-
<a href="https://www.npmjs.com/package/@antelopejs/interface-payment"><img alt="npm" src="https://img.shields.io/npm/v/@antelopejs/interface-payment?style=for-the-badge&labelColor=000000&color=000000"></a>
|
|
5
|
-
<a href="./LICENSE"><img alt="License" src="https://img.shields.io/npm/l/@antelopejs/interface-payment?style=for-the-badge&labelColor=000000&color=000000"></a>
|
|
6
|
-
<a href="https://discord.gg/
|
|
7
|
-
<a href="./docs/1.introduction.md"><img alt="Docs" src="https://img.shields.io/badge/Docs-18181B?style=for-the-badge&color=000000"></a>
|
|
4
|
+
<a href="https://www.npmjs.com/package/@antelopejs/interface-payment"><img data-illustration alt="npm" src="https://img.shields.io/npm/v/@antelopejs/interface-payment?style=for-the-badge&labelColor=000000&color=000000"></a>
|
|
5
|
+
<a href="./LICENSE"><img data-illustration alt="License" src="https://img.shields.io/npm/l/@antelopejs/interface-payment?style=for-the-badge&labelColor=000000&color=000000"></a>
|
|
6
|
+
<a href="https://discord.gg/g4pFt6eXqu"><img data-illustration alt="Discord" src="https://img.shields.io/badge/Discord-18181B?logo=discord&style=for-the-badge&color=000000"></a>
|
|
7
|
+
<a href="./docs/1.introduction.md"><img data-illustration alt="Docs" src="https://img.shields.io/badge/Docs-18181B?style=for-the-badge&color=000000"></a>
|
|
8
8
|
</div>
|
|
9
9
|
|
|
10
|
-
|
|
11
|
-
save payment methods and react to settlement events without naming
|
|
12
|
-
|
|
10
|
+
The provider-agnostic payment interface for AntelopeJS. You take payments,
|
|
11
|
+
refund them, save payment methods, and react to settlement events without naming
|
|
12
|
+
a provider. To change provider, you swap the module that implements the
|
|
13
|
+
interface.
|
|
13
14
|
|
|
14
15
|
## Installation
|
|
15
16
|
|
|
@@ -18,7 +19,8 @@ pnpm add @antelopejs/interface-payment
|
|
|
18
19
|
```
|
|
19
20
|
|
|
20
21
|
This package declares the contract and ships no provider logic. Wire a module
|
|
21
|
-
that implements it
|
|
22
|
+
that implements it, such as `@antelopejs/stripe`, in your AntelopeJS project
|
|
23
|
+
config.
|
|
22
24
|
|
|
23
25
|
## What it covers
|
|
24
26
|
|
|
@@ -30,9 +32,9 @@ that implements it — `@antelopejs/stripe` — in your Antelope config.
|
|
|
30
32
|
| Customers and saved methods | `CreateCustomer`, `GetCustomer`, `DeleteCustomer`, `ListPaymentMethods`, `DetachPaymentMethod` |
|
|
31
33
|
| Webhooks | `VerifyWebhook` |
|
|
32
34
|
|
|
33
|
-
Subscriptions, marketplace split payments, dispute management, payment links
|
|
34
|
-
in-person terminals are
|
|
35
|
-
|
|
35
|
+
Subscriptions, marketplace split payments, dispute management, payment links,
|
|
36
|
+
and in-person terminals are out of scope on purpose. Providers differ most in
|
|
37
|
+
those areas. For anything beyond this contract, use the provider's own interface
|
|
36
38
|
(`@antelopejs/interface-stripe`) alongside this one.
|
|
37
39
|
|
|
38
40
|
## Quick start
|
|
@@ -53,17 +55,19 @@ export async function startCheckout(orderId: string, idempotencyKey: string) {
|
|
|
53
55
|
}
|
|
54
56
|
```
|
|
55
57
|
|
|
56
|
-
Generate
|
|
57
|
-
retries. Call `startCheckout` from your authenticated checkout route
|
|
58
|
-
returned session ID against the order,
|
|
59
|
-
Use your own return URLs and configure the provider credentials
|
|
58
|
+
Generate one idempotency key per checkout attempt, persist it, and reuse it on
|
|
59
|
+
retries. Call `startCheckout` from your authenticated checkout route. Persist the
|
|
60
|
+
returned session ID against the order, then redirect the payer to
|
|
61
|
+
`redirectUrl`. Use your own return URLs, and configure the provider credentials
|
|
62
|
+
and the webhook route.
|
|
60
63
|
|
|
61
64
|
Fulfil the order from the `payment.succeeded` webhook, not from the payer's
|
|
62
|
-
return
|
|
65
|
+
return. The payer's browser can reach `successUrl` without a payment behind it.
|
|
63
66
|
|
|
64
67
|
Replay protection lasts only for the provider-defined replay window. Persist
|
|
65
|
-
operation keys and provider IDs
|
|
66
|
-
with provider records before
|
|
68
|
+
operation keys and provider IDs. After the window expires, reconcile uncertain
|
|
69
|
+
payments with the provider's records before you retry. Otherwise a reused key
|
|
70
|
+
can charge the payer again.
|
|
67
71
|
|
|
68
72
|
## Choose a task
|
|
69
73
|
|
|
@@ -71,52 +75,55 @@ with provider records before retrying. A reused key can otherwise charge again.
|
|
|
71
75
|
- Save a method or charge off-session: [customers and methods](./docs/3.customers-and-methods.md).
|
|
72
76
|
- Confirm settlement safely: [webhooks](./docs/4.webhooks.md).
|
|
73
77
|
- Add a provider: [capabilities and conformance](./docs/5.provider-capability-matrix.md).
|
|
74
|
-
- Add recurring billing: use Stripe's native subscriptions through
|
|
75
|
-
`@antelopejs/interface-subscriptions
|
|
76
|
-
`@antelopejs/payment-subscriptions` explicitly
|
|
77
|
-
|
|
78
|
+
- Add recurring billing with Stripe: use Stripe's native subscriptions through
|
|
79
|
+
`@antelopejs/interface-subscriptions`. To run a generic renewal clock instead,
|
|
80
|
+
choose `@antelopejs/payment-subscriptions` explicitly. Do not run both clocks
|
|
81
|
+
for the same subscription.
|
|
78
82
|
|
|
79
83
|
## Compatibility
|
|
80
84
|
|
|
81
|
-
<!-- docs-compat:
|
|
85
|
+
<!-- antelopejs-docs-compat:start -->
|
|
82
86
|
|
|
83
|
-
| Package |
|
|
84
|
-
| ---------------------------- | ---------------- |
|
|
85
|
-
| `@antelopejs/interface-core` | `>=0.0.3 <1.0.0` |
|
|
87
|
+
| Package | Supported | Tested with |
|
|
88
|
+
| ---------------------------- | ---------------- | ----------- |
|
|
89
|
+
| `@antelopejs/interface-core` | `>=0.0.3 <1.0.0` | `0.0.12` |
|
|
86
90
|
|
|
87
|
-
|
|
88
|
-
|
|
91
|
+
<!-- antelopejs-docs-compat:end -->
|
|
92
|
+
|
|
93
|
+
The table lists the peer requirements in `package.json`, not the development or
|
|
94
|
+
test-tool ranges. The implementing module can add requirements of its own.
|
|
89
95
|
|
|
90
96
|
## Conventions
|
|
91
97
|
|
|
92
98
|
- **Integer minor units.** `{ value: 1050, currency: "EUR" }` is €10.50, never a float.
|
|
93
|
-
- **An idempotency key on every mutating call
|
|
99
|
+
- **An idempotency key on every mutating call.** The key is the positional argument after the request.
|
|
94
100
|
- **Opaque provider identifiers.** Do not parse them.
|
|
95
101
|
- **A decline is a result, not an exception.** `CreatePayment` resolves with
|
|
96
|
-
`status: "failed"
|
|
97
|
-
- **An optional trailing `provider
|
|
102
|
+
`status: "failed"`. It rejects only when the call itself could not be made.
|
|
103
|
+
- **An optional trailing `provider` argument.** It selects one of several configured accounts.
|
|
98
104
|
|
|
99
105
|
## Documentation
|
|
100
106
|
|
|
101
|
-
| Document | Contents
|
|
102
|
-
| -------------------------------------------------------------------- |
|
|
103
|
-
| [Introduction](./docs/1.introduction.md) | Scope, conventions, installation
|
|
104
|
-
| [Payments](./docs/2.payments.md) | Checkout, direct payments, authorize
|
|
105
|
-
| [Customers and methods](./docs/3.customers-and-methods.md) | Saved methods, off-session and recurring charges
|
|
106
|
-
| [Webhooks](./docs/4.webhooks.md) | Verification, the event set, handling
|
|
107
|
-
| [Provider capability matrix](./docs/5.provider-capability-matrix.md) | What each provider family does behind each call, and why the scope is
|
|
107
|
+
| Document | Contents |
|
|
108
|
+
| -------------------------------------------------------------------- | ------------------------------------------------------------------------- |
|
|
109
|
+
| [Introduction](./docs/1.introduction.md) | Scope, conventions, and installation |
|
|
110
|
+
| [Payments](./docs/2.payments.md) | Checkout, direct payments, authorize and capture, refunds, and errors |
|
|
111
|
+
| [Customers and methods](./docs/3.customers-and-methods.md) | Saved methods, and off-session and recurring charges |
|
|
112
|
+
| [Webhooks](./docs/4.webhooks.md) | Verification, the event set, and handling |
|
|
113
|
+
| [Provider capability matrix](./docs/5.provider-capability-matrix.md) | What each provider family does behind each call, and why the scope is set |
|
|
108
114
|
|
|
109
115
|
## Conformance suite
|
|
110
116
|
|
|
111
|
-
`src/tests/payment.test.ts`
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
117
|
+
The package ships a conformance suite, `src/tests/payment.test.ts` and
|
|
118
|
+
`src/tests/payment-charges.test.ts`. The build publishes it as
|
|
119
|
+
`@antelopejs/interface-payment/tests/*`, and it runs against whichever provider
|
|
120
|
+
module is wired in. The suite tests the contract, not one provider's behavior. A
|
|
121
|
+
new provider implementation must pass it.
|
|
115
122
|
|
|
116
|
-
Session creation, customer lifecycle, idempotency replay, unknown-identifier
|
|
117
|
-
errors and webhook rejection need no fixture
|
|
118
|
-
provider
|
|
119
|
-
suite times out
|
|
123
|
+
Session creation, the customer lifecycle, idempotency replay, unknown-identifier
|
|
124
|
+
errors, and webhook rejection need no fixture. They also cannot pass without a
|
|
125
|
+
live provider. With nothing implementing the interface, the calls queue and the
|
|
126
|
+
suite times out instead of reporting green.
|
|
120
127
|
|
|
121
128
|
The charge tests need a provider test token, because there is no portable way to
|
|
122
129
|
mint a chargeable payment method:
|
|
@@ -129,7 +136,8 @@ mint a chargeable payment method:
|
|
|
129
136
|
|
|
130
137
|
## Contributing
|
|
131
138
|
|
|
132
|
-
Read [CONTRIBUTING.md](./CONTRIBUTING.md). Use Node.js
|
|
139
|
+
Read [CONTRIBUTING.md](./CONTRIBUTING.md). Use the Node.js version in `.nvmrc`
|
|
140
|
+
and the pnpm version in the `packageManager` field of `package.json`:
|
|
133
141
|
|
|
134
142
|
```bash
|
|
135
143
|
pnpm install --frozen-lockfile
|
|
@@ -139,7 +147,9 @@ pnpm format:check
|
|
|
139
147
|
pnpm knip
|
|
140
148
|
```
|
|
141
149
|
|
|
142
|
-
`pnpm test` runs local contract tests through the AntelopeJS runner
|
|
150
|
+
`pnpm test` runs the local contract tests through the AntelopeJS runner, with no
|
|
151
|
+
payment provider and no credentials. The provider conformance suite above is a
|
|
152
|
+
separate integration check.
|
|
143
153
|
|
|
144
154
|
## License
|
|
145
155
|
|
package/dist/types.d.ts
CHANGED
|
@@ -150,6 +150,18 @@ export interface PaymentRequest {
|
|
|
150
150
|
/** Round-tripped opaque key/value pairs. */
|
|
151
151
|
metadata?: Record<string, string>;
|
|
152
152
|
}
|
|
153
|
+
/**
|
|
154
|
+
* Every value {@link PaymentLocale} can take: the hosted page languages
|
|
155
|
+
* Stripe Checkout accepts. `auto` lets the provider pick from the payer's
|
|
156
|
+
* browser.
|
|
157
|
+
*/
|
|
158
|
+
export declare const PAYMENT_LOCALES: readonly ["auto", "bg", "cs", "da", "de", "el", "en", "en-GB", "es", "es-419", "et", "fi", "fil", "fr", "fr-CA", "hr", "hu", "id", "it", "ja", "ko", "lt", "lv", "ms", "mt", "nb", "nl", "pl", "pt", "pt-BR", "ro", "ru", "sk", "sl", "sv", "th", "tr", "vi", "zh", "zh-HK", "zh-TW"];
|
|
159
|
+
/**
|
|
160
|
+
* Language of a hosted checkout page. Providers that name their languages
|
|
161
|
+
* differently map each value to their own code, and fall back to their own
|
|
162
|
+
* default where they have no match.
|
|
163
|
+
*/
|
|
164
|
+
export type PaymentLocale = (typeof PAYMENT_LOCALES)[number];
|
|
153
165
|
/**
|
|
154
166
|
* Parameters for {@link CreateCheckoutSession}.
|
|
155
167
|
*/
|
|
@@ -178,8 +190,8 @@ export interface CheckoutSessionRequest {
|
|
|
178
190
|
savePaymentMethod?: boolean;
|
|
179
191
|
/** Shown to the payer where supported. */
|
|
180
192
|
description?: string;
|
|
181
|
-
/**
|
|
182
|
-
locale?:
|
|
193
|
+
/** Language of the hosted page, where supported. */
|
|
194
|
+
locale?: PaymentLocale;
|
|
183
195
|
/** Round-tripped opaque key/value pairs. */
|
|
184
196
|
metadata?: Record<string, string>;
|
|
185
197
|
}
|
package/dist/types.js
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
"use strict";
|
|
2
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;
|
|
3
|
+
exports.PAYMENT_EVENT_TYPES = exports.PAYMENT_METHOD_TYPES = exports.REFUND_REASONS = exports.REFUND_STATUSES = exports.PAYMENT_LOCALES = exports.PAYMENT_FAILURE_CODES = exports.TERMINAL_PAYMENT_STATUSES = exports.PAYMENT_STATUSES = void 0;
|
|
4
4
|
exports.isTerminalPaymentStatus = isTerminalPaymentStatus;
|
|
5
5
|
/**
|
|
6
6
|
* Every value {@link PaymentStatus} can take, in lifecycle order.
|
|
@@ -45,6 +45,54 @@ exports.PAYMENT_FAILURE_CODES = Object.freeze([
|
|
|
45
45
|
"expired",
|
|
46
46
|
"processing_error",
|
|
47
47
|
]);
|
|
48
|
+
/**
|
|
49
|
+
* Every value {@link PaymentLocale} can take: the hosted page languages
|
|
50
|
+
* Stripe Checkout accepts. `auto` lets the provider pick from the payer's
|
|
51
|
+
* browser.
|
|
52
|
+
*/
|
|
53
|
+
exports.PAYMENT_LOCALES = Object.freeze([
|
|
54
|
+
"auto",
|
|
55
|
+
"bg",
|
|
56
|
+
"cs",
|
|
57
|
+
"da",
|
|
58
|
+
"de",
|
|
59
|
+
"el",
|
|
60
|
+
"en",
|
|
61
|
+
"en-GB",
|
|
62
|
+
"es",
|
|
63
|
+
"es-419",
|
|
64
|
+
"et",
|
|
65
|
+
"fi",
|
|
66
|
+
"fil",
|
|
67
|
+
"fr",
|
|
68
|
+
"fr-CA",
|
|
69
|
+
"hr",
|
|
70
|
+
"hu",
|
|
71
|
+
"id",
|
|
72
|
+
"it",
|
|
73
|
+
"ja",
|
|
74
|
+
"ko",
|
|
75
|
+
"lt",
|
|
76
|
+
"lv",
|
|
77
|
+
"ms",
|
|
78
|
+
"mt",
|
|
79
|
+
"nb",
|
|
80
|
+
"nl",
|
|
81
|
+
"pl",
|
|
82
|
+
"pt",
|
|
83
|
+
"pt-BR",
|
|
84
|
+
"ro",
|
|
85
|
+
"ru",
|
|
86
|
+
"sk",
|
|
87
|
+
"sl",
|
|
88
|
+
"sv",
|
|
89
|
+
"th",
|
|
90
|
+
"tr",
|
|
91
|
+
"vi",
|
|
92
|
+
"zh",
|
|
93
|
+
"zh-HK",
|
|
94
|
+
"zh-TW",
|
|
95
|
+
]);
|
|
48
96
|
/** Normalised refund lifecycle. */
|
|
49
97
|
exports.REFUND_STATUSES = Object.freeze([
|
|
50
98
|
"pending",
|
package/dist/types.js.map
CHANGED
|
@@ -1 +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;
|
|
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;AA0GZ;;;;GAIG;AACU,QAAA,eAAe,GAAG,MAAM,CAAC,MAAM,CAAC;IAC3C,MAAM;IACN,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,OAAO;IACP,IAAI;IACJ,QAAQ;IACR,IAAI;IACJ,IAAI;IACJ,KAAK;IACL,IAAI;IACJ,OAAO;IACP,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,OAAO;IACP,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,OAAO;IACP,OAAO;CACC,CAAC,CAAC;AAiEZ,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"}
|
package/docs/1.introduction.md
CHANGED
|
@@ -1,9 +1,13 @@
|
|
|
1
|
-
|
|
1
|
+
---
|
|
2
|
+
title: Introduction
|
|
3
|
+
description: What the payment interface covers, what it leaves out and why, and the conventions every function follows.
|
|
4
|
+
mode: explanation
|
|
5
|
+
---
|
|
2
6
|
|
|
3
7
|
`@antelopejs/interface-payment` defines a provider-agnostic payment interface for
|
|
4
8
|
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
|
|
9
|
+
them, saves payment methods, and reacts to settlement events without naming a
|
|
10
|
+
provider. To change provider, it swaps the module that implements the interface.
|
|
7
11
|
|
|
8
12
|
## What it covers
|
|
9
13
|
|
|
@@ -17,24 +21,28 @@ provider, and can change provider by swapping the module wired underneath.
|
|
|
17
21
|
|
|
18
22
|
## What it deliberately does not cover
|
|
19
23
|
|
|
20
|
-
|
|
21
|
-
payments; dispute _management_; payment links; in-person terminals.
|
|
24
|
+
The interface leaves out these areas:
|
|
22
25
|
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
26
|
+
- subscriptions, invoicing, proration, dunning, tax, and coupons
|
|
27
|
+
- marketplace split payments
|
|
28
|
+
- dispute _management_
|
|
29
|
+
- payment links
|
|
30
|
+
- in-person terminals
|
|
31
|
+
|
|
32
|
+
Providers differ most in these areas. Modelling them would produce an interface
|
|
33
|
+
that most implementations could only decline. For recurring access, use
|
|
34
|
+
`@antelopejs/interface-subscriptions`. With Stripe, use Stripe's native billing.
|
|
35
|
+
Choose `@antelopejs/payment-subscriptions` explicitly when you need a generic
|
|
36
|
+
renewal clock on saved methods and off-session charges. Give each subscription
|
|
37
|
+
one renewal owner. Billing features specific to one provider stay outside the
|
|
38
|
+
portable contract. The [provider capability matrix](./5.provider-capability-matrix.md)
|
|
39
|
+
gives the reasoning for each feature.
|
|
32
40
|
|
|
33
41
|
When a backend needs something beyond this contract, it uses the provider's own
|
|
34
|
-
interface
|
|
35
|
-
is the
|
|
36
|
-
|
|
37
|
-
|
|
42
|
+
interface alongside this one, such as `@antelopejs/interface-stripe` for Stripe.
|
|
43
|
+
That is the way out of the contract, so this interface has no escape hatch of
|
|
44
|
+
its own. An escape hatch here would return an object shaped by one provider, and
|
|
45
|
+
code that used it would no longer be portable.
|
|
38
46
|
|
|
39
47
|
## Installation
|
|
40
48
|
|
|
@@ -42,50 +50,57 @@ the portability the interface exists for.
|
|
|
42
50
|
pnpm add @antelopejs/interface-payment
|
|
43
51
|
```
|
|
44
52
|
|
|
45
|
-
|
|
46
|
-
|
|
53
|
+
This package declares the contract and ships no provider logic. Add a module that
|
|
54
|
+
implements it to your AntelopeJS project config.
|
|
47
55
|
|
|
48
56
|
## Conventions
|
|
49
57
|
|
|
50
|
-
These hold
|
|
51
|
-
|
|
58
|
+
These conventions hold for every function. An implementation that breaks one
|
|
59
|
+
does not conform to the contract.
|
|
52
60
|
|
|
53
61
|
**Amounts are integer minor units.** `{ value: 1050, currency: "EUR" }` is €10.50.
|
|
54
|
-
Never a float
|
|
55
|
-
providers round
|
|
62
|
+
Never use a float. Binary floating point cannot represent most decimal amounts,
|
|
63
|
+
and providers round a float differently. `JPY` has no subunit, so
|
|
56
64
|
`{ value: 1050, currency: "JPY" }` is ¥1050. `KWD` has three decimal places.
|
|
57
|
-
|
|
65
|
+
The derived amounts on a `Payment`, `amountCaptured` and `amountRefunded`, are in
|
|
58
66
|
the same currency as `amount`.
|
|
59
67
|
|
|
60
|
-
**Every mutating call takes an idempotency key.**
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
provider returns the original result
|
|
64
|
-
|
|
65
|
-
|
|
68
|
+
**Every mutating call takes an idempotency key.** A retried payment request must
|
|
69
|
+
not do the work twice. Generate one key per logical operation, store it with your
|
|
70
|
+
own record, and reuse it on retry. Within its provider-defined replay window, the
|
|
71
|
+
provider returns the original result. Reads take no key. After the window
|
|
72
|
+
expires, reconcile uncertain payments with the provider's records before you
|
|
73
|
+
retry, because a reused key can charge again.
|
|
66
74
|
|
|
67
75
|
**Provider identifiers are opaque.** `Payment.id`, `Refund.id`, `Customer.id`,
|
|
68
|
-
`PaymentMethod.id
|
|
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
|
|
76
|
+
`PaymentMethod.id`, and `CheckoutSession.id` are the provider's own strings. Do
|
|
77
|
+
not parse them, do not infer a type from a prefix, and do not assume that two
|
|
78
|
+
providers shape them alike. Correlate them with your own records through
|
|
71
79
|
`reference` and `metadata`.
|
|
72
80
|
|
|
73
81
|
**A failed payment is not a thrown error.** `CreatePayment` resolves with a
|
|
74
|
-
`Payment` whose status is `failed
|
|
82
|
+
`Payment` whose status is `failed`. It rejects only when the call itself could
|
|
75
83
|
not be made. See [Payments](./2.payments.md).
|
|
76
84
|
|
|
77
85
|
**Settlement is asynchronous.** Every provider this interface targets settles
|
|
78
|
-
some payments after the call returns, and some after the payer has left.
|
|
79
|
-
terminal state
|
|
80
|
-
your `successUrl`. See [Webhooks](./4.webhooks.md).
|
|
86
|
+
some payments after the call returns, and some after the payer has left. Your
|
|
87
|
+
backend learns a terminal state from `VerifyWebhook`, not from the payer's return
|
|
88
|
+
to your `successUrl`. See [Webhooks](./4.webhooks.md).
|
|
81
89
|
|
|
82
90
|
## Multi-account setups
|
|
83
91
|
|
|
84
|
-
Every function takes an optional trailing `provider` argument
|
|
85
|
-
configured account to use, for a backend
|
|
86
|
-
or more than one provider at once. Omit it for the default.
|
|
92
|
+
Every function takes an optional trailing `provider` argument. It names the
|
|
93
|
+
configured account to use, for a backend that runs more than one merchant
|
|
94
|
+
account or more than one provider at once. Omit it for the default account.
|
|
87
95
|
|
|
88
96
|
```ts
|
|
89
|
-
|
|
90
|
-
|
|
97
|
+
import {
|
|
98
|
+
CreatePayment,
|
|
99
|
+
type PaymentRequest,
|
|
100
|
+
} from "@antelopejs/interface-payment";
|
|
101
|
+
|
|
102
|
+
export async function charge(request: PaymentRequest, key: string) {
|
|
103
|
+
await CreatePayment(request, key); // default account
|
|
104
|
+
await CreatePayment(request, key, "marketplace"); // a named one
|
|
105
|
+
}
|
|
91
106
|
```
|