@nordhealth/provet-pay-elements 0.15.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/CHANGELOG.md +95 -0
- package/LICENSE.md +28 -0
- package/README.md +338 -0
- package/dist/loader/provet-pay-elements.mjs +6304 -0
- package/dist/loader/provet-pay-elements.mjs.map +1 -0
- package/dist/loader/provet-pay-elements.umd.js +8 -0
- package/dist/loader/provet-pay-elements.umd.js.map +1 -0
- package/dist/types/index.d.mts +141 -0
- package/dist/types/index.d.ts +141 -0
- package/package.json +66 -0
package/CHANGELOG.md
ADDED
|
@@ -0,0 +1,95 @@
|
|
|
1
|
+
# Changelog
|
|
2
|
+
|
|
3
|
+
## 0.15.0 - 29/09/2026
|
|
4
|
+
|
|
5
|
+
- (Minor) A shopper returning from a redirect-based 3-D Secure challenge is settled. The element reads the `redirectResult` Adyen appends to the page, hands it to Adyen for the session it stored before the redirect, and then removes it from the address bar so a reload does not submit it twice. A mount that ends before Adyen has the result, as in React StrictMode, leaves it for the next mount. The card form stays out of view while Adyen answers: a saved card reaches `onSuccess` as after any other save, a refusal brings the form back with the decline notice. A result without a stored session of this mount is left alone (VPP-1077)
|
|
6
|
+
- (Patch) A card that fails 3-D Secure, by a wrong challenge answer or an issuer that denies or rejects the authentication, no longer leaves the shopper with the decline notice and no card fields. Adyen empties its container when that happens, so the component mounts the card again on the same session and the shopper can try another card in place. A re-mount still pending from the last failure is cancelled when the shopper presses pay again. `onReady` fires once, not again for the fields coming back (VPP-1077)
|
|
7
|
+
- (Minor) A failed attempt is worded for what happened. Adyen reports it as `Refused`, `Cancelled` or `Error`, and the notice used to say "That card was declined" for all three. A refusal now says "The card was declined. Try another card."; a 3-D Secure check the shopper cancelled says "The card check was cancelled. Try again."; an Adyen error says "Something went wrong while checking the card. Try again, or use another card." `onRefused` still fires for all three, so a consumer that counts attempts sees no change (VPP-1077)
|
|
8
|
+
- (Patch) When the card fields are mounted again after a failed 3-D Secure check, the name on the card the shopper had typed is put back. The card number, expiry date and security code cannot be, because they live in Adyen's iframes, so the shopper types those again (VPP-1077)
|
|
9
|
+
- (Patch) The notice about a failed attempt is taken down as soon as the shopper presses the pay button again, instead of staying over the next attempt until it finishes (VPP-1077)
|
|
10
|
+
- (Patch) The messages the element reports for a failed call no longer name a product: they say "the server", for example "The server did not answer in time." The shopper can read these messages in the form (VPP-1077)
|
|
11
|
+
- (Patch) A `checkout-sessions` answer whose card id is an empty string is refused as incomplete instead of handing the page an empty card id. A stored session is held to the same bar on resume: an empty card id or an Adyen environment other than `test` or `live` discards the record and a fresh session starts (VPP-1077)
|
|
12
|
+
- (Patch) `onSuccess` answers once per decision. The "Back to saved cards" control now hides while an attempt is being authorised, and picking a saved card ends an attempt the shopper had walked away from, so its late outcome can no longer call `onSuccess` a second time with another card. A save already under way when `unmount()` is called still reports, as documented (VPP-1077)
|
|
13
|
+
|
|
14
|
+
## 0.14.0 - 29/09/2026
|
|
15
|
+
|
|
16
|
+
- (Minor) A refused token now stops a remount that would have resumed a stored session. The saved-card list that runs beside a resumed session no longer swallows a 401 or 403, so the session is not continued for a token Provet will not accept, and the failure reaches `onError` as `auth_error` (VPP-1077)
|
|
17
|
+
- (Minor) A 403 from Provet, a token that authenticates but lacks the `card_tokenization` scope, is reported as `auth_error` at once. It used to surface as a generic session error carrying the message of Provet, and `refreshToken` is not called for it, because the same backend would mint the same token (VPP-1077)
|
|
18
|
+
- (Minor) An `auth.refreshToken` that does not answer within 60 seconds ends the wait with `auth_error`. It used to leave the card UI on its loading state for as long as the consumer's promise stayed pending (VPP-1077)
|
|
19
|
+
- (Minor) A call to Provet that does not start answering within five minutes ends in a `session_error` reading "The server did not answer in time." It used to leave the card UI on its loading state for as long as the browser waited. A call that times out is not retried: the first `checkout-sessions` call may still be running on the server, and a second would open a second pending card (VPP-1077)
|
|
20
|
+
- (Patch) A declined card is shown in the red alert banner instead of the yellow status one, matching every other blocking message. The yellow style is removed (VPP-1077)
|
|
21
|
+
|
|
22
|
+
## 0.13.0 - 29/09/2026
|
|
23
|
+
|
|
24
|
+
- (Minor) `auth.provetOrigin` is optional. Left out, the element calls the Provet instance its build was made for, so a consumer of a `prod` build passes nothing. Passing a Provet origin still names another instance, and a value that is not one is still refused with `config_invalid` (VPP-1077)
|
|
25
|
+
|
|
26
|
+
## 0.11.1 - 24/09/2026
|
|
27
|
+
|
|
28
|
+
- (Patch) A saved-card list that cannot be fetched is reported through `onError` instead of being read as "no saved cards", so the element no longer opens a session, and a pending card, when Provet answers with an error. Going back from the card form still shows the last list if the refetch fails (VPP-1077)
|
|
29
|
+
- (Patch) A new session whose card fields fail to load is reported as the error it is, for example a client key or an origin Adyen does not accept, instead of "The card session is no longer usable." followed by a second session with its own pending card. Only a resumed session that fails is treated as expired and replaced (VPP-1077)
|
|
30
|
+
- (Patch) An `auth.refreshToken` that rejects is reported as `auth_error` with its message, instead of `technical` (VPP-1077)
|
|
31
|
+
- (Patch) Picking a saved card drops a session the shopper had opened for a new card, so the next mount in the tab offers the saved cards again instead of reopening that form (VPP-1077)
|
|
32
|
+
- (Patch) Saved cards and the checkout-sessions response are read field by field: a card reaches `onSuccess` with only `id`, `brand`, `last4`, `expiration_date` and `default`, each only when it has the right type, and a malformed `brand` no longer breaks the saved-card list (VPP-1077)
|
|
33
|
+
- (Patch) The README lists the Content Security Policy a consumer page needs for the card UI (VPP-1077)
|
|
34
|
+
|
|
35
|
+
## 0.11.0 - 24/09/2026
|
|
36
|
+
|
|
37
|
+
- (Breaking) `mount()` takes who it acts for as one required `auth` object: `token`, `provetOrigin`, `provetId`, `clientId` (the Provet client, the pet owner in the token's audience) and `departmentId`, all required. A missing field, or a `provetOrigin` that is not a Provet instance, fails the mount with `config_invalid` (VPP-1077)
|
|
38
|
+
- (Breaking) The `Auth` class and its `AuthOptions` type are gone, and so are the top-level `provetId`, `provetCloudOrigin` and `department` options; `provetCloudOrigin` is now `auth.provetOrigin` and `department` is `auth.departmentId`. The consumer passes the token itself, and the optional `auth.refreshToken` takes over from `fetchToken` on a 401: the element retries the same call once with the fresh token. Without it, an expired token is reported through `onError` as `auth_error` (VPP-1077)
|
|
39
|
+
- (Patch) The stored session is keyed by the Provet origin, tenant, pet owner and department it was opened for. It used to be keyed by tenant and department only, so a second pet owner mounting in the same tab resumed the first one's session, and `onSuccess` returned the first pet owner's card (VPP-1077)
|
|
40
|
+
|
|
41
|
+
## 0.10.0 - 23/09/2026
|
|
42
|
+
|
|
43
|
+
- (Minor) Once a card is saved, the card UI shows a final success state — a green check and "Card saved" — in place of the spent form, which could otherwise be submitted again; after a 3-D Secure challenge it fills the space the challenge left. The back control hides, the view takes focus when the form had it, and it renders before `onSuccess` runs (VPP-1077)
|
|
44
|
+
- (Minor) The saved cards are fetched each time they are shown, so going back from the card form lists the current cards rather than the ones offered at mount; an empty list returns to the card form without opening a second session, and a list that cannot be fetched falls back to the one shown before (VPP-1077)
|
|
45
|
+
- (Patch) An error thrown by the consumer's `onSuccess` is reported as an uncaught error of its own. Adyen used to settle it as a failed payment, so a card that had been saved showed as declined and `onRefused` fired (VPP-1077)
|
|
46
|
+
- (Patch) An unmounted element does nothing more. A token that arrives after `unmount()` starts nothing, so React StrictMode's mount → unmount → mount opens one session instead of two; no `onReady`, `onRefused` or `onError` fires after it; and a session it was opening is kept for the next mount instead of being left unused. A card whose save was already under way still reports through `onSuccess` (VPP-1077)
|
|
47
|
+
|
|
48
|
+
## 0.9.0 - 23/09/2026
|
|
49
|
+
|
|
50
|
+
- (Breaking) The card UI renders in the consumer's own page instead of an iframe served from ours. `npm i @provet-pay/elements` and `mount()` are now the whole integration: there is no second document, no hosted `index.html`, `.js` or `.css`, and nothing for a consumer to serve. The package is one JavaScript file with both stylesheets — ours and Adyen's — inlined and injected at mount (VPP-1081)
|
|
51
|
+
- (Breaking) `elementOrigin` is gone from `mount()`; there is no element origin to point at. A consumer's own origin is what Adyen and Provet see, so it is registered once with Adyen as an allowed origin and added to `CARD_ELEMENT_ALLOWED_ORIGINS` on the Provet instance it uses (VPP-1081)
|
|
52
|
+
- (Minor) A redirect-based 3DS challenge is now an ordinary top-level navigation back to the consumer's `return_url`. Same-origin with the page that hosts it, the card UI is not subject to the constraint `DESIGN.md` §12 (spike S4) puts on a cross-domain frame, which cannot redirect at all (VPP-1081)
|
|
53
|
+
- (Minor) The stored session is keyed by the mount it belongs to — tenant and department — so a session opened for one mount is never resumed by another on the same page (VPP-1081)
|
|
54
|
+
- (Patch) The card UI's stylesheet is scoped to the node the mount creates: no `html`, `body` or `#root` rules, and its tokens sit on that node rather than `:root`, so a consumer's typography, spacing and background are untouched (VPP-1081)
|
|
55
|
+
|
|
56
|
+
## 0.8.0 - 22/09/2026
|
|
57
|
+
|
|
58
|
+
- (Minor) `provetCloudOrigin` on `mount()` — the Provet instance the tenant lives on. Provet runs one instance per domain, so a consumer names its own and one published version serves every consumer instead of one build per instance. Only a Provet origin is accepted (`config_invalid` otherwise), and the element falls back to the instance its build was made for (VPP-1077)
|
|
59
|
+
- (Patch) The element document admits every Provet instance in its CSP — `connect-src 'self' https://*.provetcloud.com https://provetcloud.com` alongside the build's own origin — so naming an instance needs no rebuild (VPP-1077)
|
|
60
|
+
- (Patch) Only the local build emits a source map; the element's source is not part of what a consumer receives (VPP-1077)
|
|
61
|
+
|
|
62
|
+
- (Breaking) The element owns its styling. Its chrome is drawn from its own `--pp-*` tokens instead of `@nordhealth/css`, which is no longer a dependency, and it renders in a system font stack rather than a webfont. A release is one script and one stylesheet — no font files — so nothing of a design system lands in whatever hosts it (VPP-1077)
|
|
63
|
+
- (Minor) `appearance.variables` now moves the element's own chrome as well as the card fields: each variable writes one `--pp-*` token, and the element's stylesheet derives Adyen's `--adyen-sdk-*` properties from those, so one value styles both. `cssVariables` takes `--pp-*` as well as `--adyen-sdk-*`, and wins over `variables` (VPP-1077)
|
|
64
|
+
|
|
65
|
+
## 0.7.0 - 22/09/2026
|
|
66
|
+
|
|
67
|
+
- (Breaking) A card is its Provet id and the details Provet prints beside it: `SavedCard` is `id`, `brand`, `last4`, `expiration_date`, `default`, and `tokenized_card_ref` is gone. No card status travels anywhere any more — not on a listed card, not on the one `onSuccess` returns, not in the stored session — and `GET /<provet_id>/api/0.1/pay/saved-cards/` lists only the cards that can be charged, so the element offers that list as it is given instead of filtering it (VPP-1077)
|
|
68
|
+
- (Breaking) `expiry` ("M/YYYY") is replaced by `expiration_date`, Provet's ISO date; the saved-card list prints it as the month on the card and marks it expired once that month has passed (VPP-1077)
|
|
69
|
+
- (Minor) Removing a saved card is off: the icon button no longer renders, so a card is picked or left alone. Provet has no delete endpoint for the element yet, and what removal means for health plans and other charges is undecided (VPP-1487)
|
|
70
|
+
|
|
71
|
+
## 0.6.0 - 10/09/2026
|
|
72
|
+
|
|
73
|
+
- (Breaking) `appearance.theme` and the `PayTheme` type are gone, and with them the light, dark and `auto` palettes. The element renders one way: Nord's light palette with no surface and no padding of its own, so it sits flush on the host page. `appearance.variables` and `appearance.secured` are unchanged and remain how a consumer matches its own design (VPP-1077)
|
|
74
|
+
- (Patch) `@nordhealth/themes` is no longer a dependency; its two palettes were inlined into the bundle, which is 1.6 KB smaller gzipped (VPP-1077)
|
|
75
|
+
|
|
76
|
+
## 0.5.0 - 09/09/2026
|
|
77
|
+
|
|
78
|
+
- (Minor) The Provet contract as merged (provetcloud !17554): the element mints with `POST /<provet_id>/api/0.1/pay/checkout-sessions/` sending `department`, `recurring_model` and `return_url`; `intent_key` is gone from the request and the session envelope; the integer card id is handed on as a string (VPP-1079)
|
|
79
|
+
- (Minor) Saved cards move to `/<provet_id>/api/0.1/pay/saved-cards/` (list and delete) (VPP-1079)
|
|
80
|
+
- (Minor) `test` and `prod` origins are known to the build, so `TARGET_ENV=test pnpm build` needs no environment variables; the package ships to npm, and `pnpm pack` produces the tarball a consumer takes until it is published (VPP-1083)
|
|
81
|
+
- (Patch) Provet error bodies — DRF `{detail, code}` and field errors — surface as the element's error message (VPP-1080)
|
|
82
|
+
- (Patch) `department` on `mount()` is documented as the Provet department id (VPP-1077)
|
|
83
|
+
- (Patch) The local host page and Provet stand-in move from port 6002 to 3000, the port the other local UIs use and therefore an origin Adyen already allows, so the card fields render locally without registering anything (VPP-1077)
|
|
84
|
+
|
|
85
|
+
## 0.4.0 - 31/07/2026
|
|
86
|
+
|
|
87
|
+
- (Minor) Project layout for the checkout card tokenizer: one package, two build targets — a host-page loader (npm + versioned CDN) and the element iframe served from our own origin, sharing one version so a pinned install always frames its matching element release (VPP-1057)
|
|
88
|
+
- (Minor) `mount(container, options)` + an `Auth`-style token provider as the public surface; `onSuccess({ card })` returns the Provet card id and nothing else (VPP-1057)
|
|
89
|
+
- (Minor) Element internals: the Provet client, the `sessionStorage` session envelope for refresh survival, the Adyen Web v6 adapter, typed error states and the saved-card offer, where a card is removed by an icon button behind a confirmation and "add a new card" is reversible — the card fields keep a back button to the offer, and returning to the fields reuses the intent already minted (VPP-1057)
|
|
90
|
+
- (Minor) `appearance.theme` — `plain` (the default: the light palette with no background or padding, so the element sits flush on the host page), `light`, `dark`, or `auto` (light or dark from the shopper's operating-system setting). Dark uses Nord's dark palette and reaches Adyen's cross-origin card fields, which cannot resolve a design token themselves (VPP-1057)
|
|
91
|
+
- (Minor) The chrome is Nord: its buttons, dropdown, popout surface, group heading and spinner carry the CSS of `nord-button` and `nord-dropdown`, so the element renders as the design system rather than an approximation of it. `appearance.variables.colorBorder` now also drives the resting card-field edge, which Adyen paints from a property of its own (VPP-1057)
|
|
92
|
+
- (Minor) `mount` renders a back control into the container, returning a shopper from the card form to their saved cards; it shows only when there is something to return to, sits above the frame against its trailing edge, renders as a `nord-button` of the plain variant under every theme, and carries the class `provet-pay-elements-back` (VPP-1057)
|
|
93
|
+
- (Minor) Local development environment on ports 6002 (host page + Provet stand-in) and 3003 (the element), minting real Adyen TEST `$0` sessions, with `PCLOUD_BASE_URL` to proxy to a real Provet (VPP-1057)
|
|
94
|
+
- (Minor) Both targets build with Vite per environment from `TARGET_ENV`, reading their origins from the environment so a build never guesses a hostname; the loader ships as ESM + UMD (`dist/loader/`), deploy wiring waits on those origins being decided (VPP-1057)
|
|
95
|
+
- (Patch) Strict TypeScript and type-aware ESLint, both gating `pnpm build` (VPP-1057)
|
package/LICENSE.md
ADDED
|
@@ -0,0 +1,28 @@
|
|
|
1
|
+
# License
|
|
2
|
+
|
|
3
|
+
<!-- Adapted from the Nord Design System package license for an integrator-facing
|
|
4
|
+
package. Needs a review by Nordhealth legal before 1.0.0. -->
|
|
5
|
+
|
|
6
|
+
This package (the “Package”) is brought to you by Nordhealth Ltd (“Nordhealth”, or “we” or “us”) and all rights, including copyright, in the content of the Package are owned or controlled by Nordhealth.
|
|
7
|
+
|
|
8
|
+
## Conditions of Use
|
|
9
|
+
|
|
10
|
+
Nordhealth hereby grants you a limited, non-exclusive, revocable license to install and use the Package solely for the purpose of integrating Nordhealth’s payment services into your own product under an agreement with Nordhealth (the “Purpose”).
|
|
11
|
+
|
|
12
|
+
You may not use the Package for any other purpose, or reproduce, retransmit, disseminate, sell, publish or broadcast it.
|
|
13
|
+
|
|
14
|
+
If Nordhealth is informed or has any reason to believe that the Package is being used other than in accordance with these terms, Nordhealth reserves the right to suspend or permanently prevent access by the user to the Package and its related services and shall have no liability to the user whatsoever in such event.
|
|
15
|
+
|
|
16
|
+
## Package Accuracy
|
|
17
|
+
|
|
18
|
+
Nordhealth makes every effort to ensure that the Package is accurate and up-to-date, but Nordhealth does not offer any warranties (whether express, implied or otherwise) as to the reliability, accuracy or completeness of the Package. The Package is provided “as is” and “as available” without express or implied warranty or condition of any kind.
|
|
19
|
+
|
|
20
|
+
## Intellectual Property Rights
|
|
21
|
+
|
|
22
|
+
You acknowledge and agree that all copyright, rights in data, databases, trade-marks, names, images, logos and other intellectual property rights in the Package (“Intellectual Property Rights”) shall remain at all times vested in Nordhealth and its subsidiaries, and that these are protected by copyright and other laws and international treaty provisions.
|
|
23
|
+
|
|
24
|
+
Nothing contained in the Package shall be construed as conferring by implication or otherwise any license or right to use any of the Intellectual Property Rights other than in accordance with these terms.
|
|
25
|
+
|
|
26
|
+
## Limitation of Liability
|
|
27
|
+
|
|
28
|
+
While Nordhealth takes all reasonable steps to ensure that the Package is properly functioning at all times, Nordhealth does not warrant that the Package will be uninterrupted, timely, secure or error-free, that defects will be corrected, or that the Package is free of software bugs or other defects.
|
package/README.md
ADDED
|
@@ -0,0 +1,338 @@
|
|
|
1
|
+
# @nordhealth/provet-pay-elements
|
|
2
|
+
|
|
3
|
+
Add a card step to a web page, and let a shopper save a payment card in Provet, through Provet Pay, Nordhealth's payment service.
|
|
4
|
+
|
|
5
|
+
`@nordhealth/provet-pay-elements` draws a card form into an element chosen by the page, checks the card with a zero-value (`$0`) authorization at Adyen, and hands the page back a **Provet card id**. It never charges the card: charging happens later, on the server, using that id. Provet keeps the saved card, so a feature such as a health plan signup can use it for later payments.
|
|
6
|
+
|
|
7
|
+
- **Nothing to host.** One JavaScript file, with its styles inside. Install it, call `mount()`.
|
|
8
|
+
- **No card number on the page.** Adyen's card fields are iframes Adyen creates; the number never reaches the page or the package.
|
|
9
|
+
- **No secrets in the browser.** The component runs on a short-lived token, bound to one shopper, that the backend mints.
|
|
10
|
+
- **3-D Secure included.** A challenge appears inside the form; a redirect-based one returns to the page and is settled by the component.
|
|
11
|
+
|
|
12
|
+
Contents: [Prerequisites](#prerequisites) · [Quick start](#quick-start) · [API](#api) · [Errors](#errors) · [Appearance](#appearance) · [Content Security Policy](#content-security-policy) · [How it works](#how-it-works) · [Versioning](#versioning)
|
|
13
|
+
|
|
14
|
+
## Prerequisites
|
|
15
|
+
|
|
16
|
+
Three things must be in place before the card form can load on a page.
|
|
17
|
+
|
|
18
|
+
| # | Requirement | Set up by | Why |
|
|
19
|
+
| --- | -------------------------------------------------------------------------------------- | ------------------ | --------------------------------------------------------- |
|
|
20
|
+
| 1 | The page's origin is in the CORS allow list of Provet (`CARD_ELEMENT_ALLOWED_ORIGINS`) | Provet, on request | The browser blocks calls to Provet from any other origin |
|
|
21
|
+
| 2 | The same origin is registered with Adyen as an allowed origin for the client key | Provet, on request | Adyen renders the card fields only on a registered origin |
|
|
22
|
+
| 3 | A backend that mints the browser token | The integrator | See [step 1](#1-mint-a-browser-token-on-the-backend) |
|
|
23
|
+
|
|
24
|
+
Ask Provet to add each origin, for example `https://booking.example.com`, for each environment (test and production).
|
|
25
|
+
|
|
26
|
+
**Local development on the test environment.** These local origins already work: `http://localhost` and `http://127.0.0.1` on ports 3000, 4200, 5173, 6002, 7200 and 8080. Each origin is listed exactly, because Adyen does not accept a port wildcard. On any other port the component shows "Could not reach the server." and the card fields do not appear. Ask Provet to add the port. In production, partners use their own domains, so this applies to the test environment only.
|
|
27
|
+
|
|
28
|
+
If the card form never appears and the browser console shows a blocked cross-origin request to `provetcloud.com` or an Adyen origin error, requirement 1 or 2 is missing for that origin.
|
|
29
|
+
|
|
30
|
+
The Provet setup supplies the rest: an OAuth application that may use the `card_tokenization` scope, the clinic's **instance id** (`provetId`) and **department id** (`departmentId`), and the shopper's **client id** (`clientId`).
|
|
31
|
+
|
|
32
|
+
## Quick start
|
|
33
|
+
|
|
34
|
+
### 1. Mint a browser token on the backend
|
|
35
|
+
|
|
36
|
+
The component authenticates with a token that is valid for one shopper and for at most 10 minutes, with no refresh token. The backend makes two calls to the token endpoint of Provet, `POST https://<provet-instance>/<provetId>/oauth2/token/`, authenticating as its OAuth application (client id and secret, HTTP Basic).
|
|
37
|
+
|
|
38
|
+
First, an API token with the `card_tokenization` scope:
|
|
39
|
+
|
|
40
|
+
```
|
|
41
|
+
grant_type=client_credentials
|
|
42
|
+
scope=card_tokenization
|
|
43
|
+
```
|
|
44
|
+
|
|
45
|
+
Then exchange it (RFC 8693 token exchange) for the browser token, naming the shopper as the audience:
|
|
46
|
+
|
|
47
|
+
```
|
|
48
|
+
grant_type=urn:ietf:params:oauth:grant-type:token-exchange
|
|
49
|
+
subject_token=<the token from the first call>
|
|
50
|
+
subject_token_type=urn:ietf:params:oauth:token-type:access_token
|
|
51
|
+
scope=card_tokenization
|
|
52
|
+
audience=client:<clientId>
|
|
53
|
+
```
|
|
54
|
+
|
|
55
|
+
Take `clientId` from the signed-in user on the server, never from anything the browser sends. Keep the first token and the client secret on the backend; send the browser only the exchanged token.
|
|
56
|
+
|
|
57
|
+
A minimal endpoint (Node 18+, Express):
|
|
58
|
+
|
|
59
|
+
```js
|
|
60
|
+
const PROVET = 'https://provetcloud.com' // the Provet instance
|
|
61
|
+
const PROVET_ID = 922 // the instance id
|
|
62
|
+
const basic = Buffer.from(
|
|
63
|
+
`${process.env.CLIENT_ID}:${process.env.CLIENT_SECRET}`
|
|
64
|
+
).toString('base64')
|
|
65
|
+
|
|
66
|
+
const tokenCall = async (params) => {
|
|
67
|
+
const response = await fetch(`${PROVET}/${PROVET_ID}/oauth2/token/`, {
|
|
68
|
+
method: 'POST',
|
|
69
|
+
headers: {
|
|
70
|
+
Authorization: `Basic ${basic}`,
|
|
71
|
+
'Content-Type': 'application/x-www-form-urlencoded',
|
|
72
|
+
},
|
|
73
|
+
body: new URLSearchParams(params),
|
|
74
|
+
})
|
|
75
|
+
if (!response.ok) throw new Error(`Provet answered ${response.status}`)
|
|
76
|
+
return (await response.json()).access_token
|
|
77
|
+
}
|
|
78
|
+
|
|
79
|
+
app.post('/api/card-token', requireSignedInShopper, async (req, res, next) => {
|
|
80
|
+
try {
|
|
81
|
+
const apiToken = await tokenCall({
|
|
82
|
+
grant_type: 'client_credentials',
|
|
83
|
+
scope: 'card_tokenization',
|
|
84
|
+
})
|
|
85
|
+
const token = await tokenCall({
|
|
86
|
+
grant_type: 'urn:ietf:params:oauth:grant-type:token-exchange',
|
|
87
|
+
subject_token: apiToken,
|
|
88
|
+
subject_token_type: 'urn:ietf:params:oauth:token-type:access_token',
|
|
89
|
+
scope: 'card_tokenization',
|
|
90
|
+
audience: `client:${req.user.providerClientId}`, // from the session, not the request
|
|
91
|
+
})
|
|
92
|
+
res.json({ token })
|
|
93
|
+
} catch (error) {
|
|
94
|
+
next(error)
|
|
95
|
+
}
|
|
96
|
+
})
|
|
97
|
+
```
|
|
98
|
+
|
|
99
|
+
### 2. Add the component to the page
|
|
100
|
+
|
|
101
|
+
With a bundler:
|
|
102
|
+
|
|
103
|
+
```bash
|
|
104
|
+
npm install @nordhealth/provet-pay-elements
|
|
105
|
+
```
|
|
106
|
+
|
|
107
|
+
```js
|
|
108
|
+
import { mount } from '@nordhealth/provet-pay-elements'
|
|
109
|
+
```
|
|
110
|
+
|
|
111
|
+
Without a bundler, copy `node_modules/@nordhealth/provet-pay-elements/dist/loader/provet-pay-elements.umd.js` to the site's own server and load it with a script tag; it defines `window.ProvetPayElements`:
|
|
112
|
+
|
|
113
|
+
```html
|
|
114
|
+
<script src="/assets/provet-pay-elements.umd.js"></script>
|
|
115
|
+
<!-- then: ProvetPayElements.mount(...) -->
|
|
116
|
+
```
|
|
117
|
+
|
|
118
|
+
### 3. Give the component a container and mount it
|
|
119
|
+
|
|
120
|
+
The **container** is any empty block element on the page. The component renders its form inside it and removes everything it added when `unmount()` is called. Pass the element itself or a CSS selector.
|
|
121
|
+
|
|
122
|
+
A complete plain-JavaScript page:
|
|
123
|
+
|
|
124
|
+
```html
|
|
125
|
+
<!DOCTYPE html>
|
|
126
|
+
<html>
|
|
127
|
+
<head>
|
|
128
|
+
<!-- the card labels use non-ASCII characters; without this they render garbled -->
|
|
129
|
+
<meta charset="utf-8" />
|
|
130
|
+
</head>
|
|
131
|
+
<body>
|
|
132
|
+
<h1>Save your card</h1>
|
|
133
|
+
|
|
134
|
+
<!-- the container: empty, on the page -->
|
|
135
|
+
<div id="card"></div>
|
|
136
|
+
<p id="result"></p>
|
|
137
|
+
|
|
138
|
+
<script src="/assets/provet-pay-elements.umd.js"></script>
|
|
139
|
+
<script>
|
|
140
|
+
async function fetchToken() {
|
|
141
|
+
const response = await fetch('/api/card-token', { method: 'POST' })
|
|
142
|
+
if (!response.ok) {
|
|
143
|
+
throw new Error(`Token request failed (${response.status})`)
|
|
144
|
+
}
|
|
145
|
+
const { token } = await response.json()
|
|
146
|
+
if (!token) {
|
|
147
|
+
throw new Error('Token response did not include a token')
|
|
148
|
+
}
|
|
149
|
+
return token
|
|
150
|
+
}
|
|
151
|
+
|
|
152
|
+
fetchToken()
|
|
153
|
+
.then((token) => {
|
|
154
|
+
ProvetPayElements.mount('#card', {
|
|
155
|
+
auth: {
|
|
156
|
+
token: token, // from step 1
|
|
157
|
+
provetId: 922, // the clinic's instance id
|
|
158
|
+
clientId: 2624, // the shopper: the id put in the token's audience
|
|
159
|
+
departmentId: 42, // the clinic's department id
|
|
160
|
+
refreshToken: fetchToken, // optional: a new token when the current one expires
|
|
161
|
+
},
|
|
162
|
+
onSuccess: function (result) {
|
|
163
|
+
// Send result.card.id to the backend, for example as payment_card when signing up.
|
|
164
|
+
document.getElementById('result').textContent =
|
|
165
|
+
'Saved card ' + result.card.id
|
|
166
|
+
},
|
|
167
|
+
onRefused: function () {
|
|
168
|
+
// The card was declined; the form shows a notice and the shopper can try again.
|
|
169
|
+
},
|
|
170
|
+
onError: function (error) {
|
|
171
|
+
console.error(error.type, error.message)
|
|
172
|
+
},
|
|
173
|
+
})
|
|
174
|
+
})
|
|
175
|
+
.catch((error) => {
|
|
176
|
+
document.getElementById('result').textContent =
|
|
177
|
+
'Could not load the card form'
|
|
178
|
+
console.error(error)
|
|
179
|
+
})
|
|
180
|
+
</script>
|
|
181
|
+
</body>
|
|
182
|
+
</html>
|
|
183
|
+
```
|
|
184
|
+
|
|
185
|
+
With a bundler the call is the same, using `mount` from the import.
|
|
186
|
+
|
|
187
|
+
The component is on the page's origin, so the page must be served from an origin Provet has allowed ([Prerequisites](#prerequisites)).
|
|
188
|
+
|
|
189
|
+
### 4. Use the result
|
|
190
|
+
|
|
191
|
+
`onSuccess({ card })` is the only success signal. `card.id` is the Provet card id: pass it to the feature that needs a saved card, for example as `payment_card` when signing a patient up to a health plan.
|
|
192
|
+
|
|
193
|
+
If the shopper already has saved cards, the component offers them first.
|
|
194
|
+
|
|
195
|
+
| Where the card comes from | `onSuccess` receives | Chargeable |
|
|
196
|
+
| --------------------------- | ---------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
197
|
+
| Entered in the form | `{ card: { id } }` | A few seconds later, when Adyen's confirmation reaches Provet. The id can be used straight away; the feature waits for the card to become active. |
|
|
198
|
+
| Picked from the saved cards | `{ card: { id, brand, last4, expiration_date, default } }` | Already active |
|
|
199
|
+
|
|
200
|
+
After a card is saved, the form is replaced by a "Card saved" confirmation and the back control hides, so the same form cannot be submitted twice.
|
|
201
|
+
|
|
202
|
+
---
|
|
203
|
+
|
|
204
|
+
## API
|
|
205
|
+
|
|
206
|
+
### `mount(container, options)`
|
|
207
|
+
|
|
208
|
+
Returns `{ unmount() }`. `container` is an `HTMLElement` or a CSS selector; a selector that matches nothing throws.
|
|
209
|
+
|
|
210
|
+
| Option | Type | Required | Description |
|
|
211
|
+
| ------------------- | ----------------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
212
|
+
| `auth.token` | `string` | yes | The browser token from [step 1](#1-mint-a-browser-token-on-the-backend). |
|
|
213
|
+
| `auth.provetId` | `string \| number` | yes | The clinic's Provet instance id (the tenant). |
|
|
214
|
+
| `auth.clientId` | `string \| number` | yes | The shopper's Provet client id: the `client:<id>` put in the token's audience. Not an OAuth client id. It must match the token; see below. |
|
|
215
|
+
| `auth.departmentId` | `string \| number` | yes | The clinic's Provet department id. It picks the Adyen store for the card check; Provet refuses a department without Provet Pay. |
|
|
216
|
+
| `auth.provetOrigin` | `string` | no | The Provet instance the token came from, for example `https://us.provetcloud.com`. Defaults to the instance the package was built for. |
|
|
217
|
+
| `auth.refreshToken` | `() => Promise<string>` | no | Returns a new token after the current one is refused with 401. See [Tokens](#tokens). |
|
|
218
|
+
| `recurringModel` | `'subscription' \| 'one-off'` | no | What the card will be used for. Defaults to `'subscription'`. |
|
|
219
|
+
| `locale` | `string` | no | The form's language, for example `sv-SE`. Defaults to English. |
|
|
220
|
+
| `appearance` | object | no | See [Appearance](#appearance). |
|
|
221
|
+
| `onSuccess` | `({ card }) => void` | yes | The shopper is done with a card. |
|
|
222
|
+
| `onRefused` | `() => void` | no | An attempt failed: the card was declined, the shopper cancelled the 3-D Secure check, or Adyen answered with an error. The form stays and the shopper can try again. |
|
|
223
|
+
| `onError` | `({ type, message }) => void` | no | Something the shopper cannot fix by retrying. See [Errors](#errors). |
|
|
224
|
+
| `onReady` | `() => void` | no | The card fields are on screen. |
|
|
225
|
+
|
|
226
|
+
A missing required field, or a `provetOrigin` that is not a Provet instance, makes `mount()` throw an error with code `config_invalid` before anything is shown or requested.
|
|
227
|
+
|
|
228
|
+
`provetOrigin` matters when the Provet instance is not the one the package was built for. Provet runs one instance per domain (`https://provetcloud.com`, `https://us.provetcloud.com`, and others), so pass the right one if it differs. Only Provet origins are accepted.
|
|
229
|
+
|
|
230
|
+
`clientId` must be the client the token was exchanged for. The component cannot check that, because the client is only in Provet's records, and it uses `clientId` to keep one shopper's unfinished session from being resumed for another. Always pass the same client to both.
|
|
231
|
+
|
|
232
|
+
### `handle.unmount()`
|
|
233
|
+
|
|
234
|
+
Removes everything the component added to the container. After it, no callback fires, except `onSuccess` for a card whose save was already under way. A session the component was opening is kept, so mounting again for the same shopper after Provet has answered resumes it instead of opening a second one.
|
|
235
|
+
|
|
236
|
+
A mount that starts while another for the same shopper is still opening its session is not coordinated with it, and both can open a session. React StrictMode in development mounts, unmounts and mounts again straight away, so it can hit this. Mount the component once per shopper and container.
|
|
237
|
+
|
|
238
|
+
### Tokens
|
|
239
|
+
|
|
240
|
+
The token lasts at most 10 minutes. When Provet answers a call with `401`:
|
|
241
|
+
|
|
242
|
+
- with `auth.refreshToken`, the component calls it once, retries the same call with the new token, and continues. If `refreshToken` rejects, or does not answer within 60 seconds, the failure is reported as `auth_error`;
|
|
243
|
+
- without it, the expiry is reported as `auth_error`.
|
|
244
|
+
|
|
245
|
+
A `403` means the token authenticates but does not have the `card_tokenization` scope. It is reported as `auth_error` at once and `refreshToken` is not called, because the backend would mint the same token again.
|
|
246
|
+
|
|
247
|
+
## Errors
|
|
248
|
+
|
|
249
|
+
`mount()` throws `config_invalid` for a bad configuration. Everything else reaches `onError({ type, message })`, and the form shows the message in a red banner.
|
|
250
|
+
|
|
251
|
+
| `type` | Meaning | What to do |
|
|
252
|
+
| --------------- | -------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------- |
|
|
253
|
+
| `auth_error` | The token expired, was refused, or lacks the scope. | Mint a new token and mount again. A 403 points at the OAuth application's scopes. |
|
|
254
|
+
| `session_error` | Provet or Adyen could not open or continue the card session: an unavailable service, a department without Provet Pay, and so on. | Show the message, offer to try again. |
|
|
255
|
+
| `technical` | Anything else, including an origin Adyen does not accept or a card setup that was cancelled. | Show a generic failure; the message helps support. |
|
|
256
|
+
|
|
257
|
+
A failed attempt is not an error: it calls `onRefused` and the shopper tries again in place. The notice says what happened: "The card was declined. Try another card." for a refusal, "The card check was cancelled. Try again." when the shopper cancelled the 3-D Secure check, and "Something went wrong while checking the card. Try again, or use another card." for an Adyen error. After a failed 3-D Secure check Adyen removes the card fields, so the component mounts them again; the name on the card is put back, but the card number, expiry date and security code cannot be, and the shopper types those again.
|
|
258
|
+
|
|
259
|
+
## Appearance
|
|
260
|
+
|
|
261
|
+
The card UI draws itself from its own design tokens: a light palette, no background or padding of its own, and a system font. It depends on no stylesheet from the page, and its rules reach only the element it creates, so the page is untouched.
|
|
262
|
+
|
|
263
|
+
Two options match the component to the page's design:
|
|
264
|
+
|
|
265
|
+
```js
|
|
266
|
+
mount('#card', {
|
|
267
|
+
auth,
|
|
268
|
+
onSuccess,
|
|
269
|
+
appearance: {
|
|
270
|
+
variables: { colorAccent: '#5b21b6', borderRadius: '8px' },
|
|
271
|
+
secured: { base: { color: '#1f2733' } },
|
|
272
|
+
},
|
|
273
|
+
})
|
|
274
|
+
```
|
|
275
|
+
|
|
276
|
+
`variables` change the component's own colors, radius and font, and Adyen's card fields follow:
|
|
277
|
+
|
|
278
|
+
| `variables` | Changes |
|
|
279
|
+
| -------------- | ------------------------------------------------ |
|
|
280
|
+
| `colorAccent` | field focus ring and active outline |
|
|
281
|
+
| `colorButton` | Adyen's pay button |
|
|
282
|
+
| `colorText` | field labels and the text inside the card fields |
|
|
283
|
+
| `colorBorder` | field outlines |
|
|
284
|
+
| `colorSurface` | the component's own background |
|
|
285
|
+
| `colorError` | field error text and outline |
|
|
286
|
+
| `borderRadius` | field corners |
|
|
287
|
+
| `fontFamily` | the text inside the card fields |
|
|
288
|
+
|
|
289
|
+
`secured` styles reach inside Adyen's card-field iframes. Those are cross-origin, so only concrete values (`'#1f2733'`, `'16px'`) work there, never `var(…)`.
|
|
290
|
+
|
|
291
|
+
`cssVariables` sets raw `--pp-*` or `--adyen-sdk-*` properties and wins over `variables` on the component's own UI; for instance `--pp-color-success` colors the "Card saved" check. Inside Adyen's card fields, `colorText`, `fontFamily` and `colorError` from `variables` win over `cssVariables`, and `secured` wins over both.
|
|
292
|
+
|
|
293
|
+
The "Back to saved cards" control the component adds carries the class `provet-pay-elements-back`, and the container gets `provet-pay-elements`. Both can be styled by the page.
|
|
294
|
+
|
|
295
|
+
## Content Security Policy
|
|
296
|
+
|
|
297
|
+
If the page sets a Content Security Policy, allow what the component and Adyen load. `{env}` is `test` or `live`, the Adyen environment Provet returns with each session.
|
|
298
|
+
|
|
299
|
+
| Directive | Allow | Because |
|
|
300
|
+
| ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
|
|
301
|
+
| `connect-src` | the Provet instance, `https://checkoutshopper-{env}.adyen.com`, `https://checkoutanalytics-{env}.adyen.com`, `https://checkoutshopper-{env}.cdn.adyen.com` | the component calls Provet; Adyen calls its session API and analytics, and fetches translations for any locale but `en-US` from its CDN |
|
|
302
|
+
| `frame-src` | `https://checkoutshopper-{env}.adyen.com` and the card issuers' 3-D Secure pages | the card fields and Adyen's risk check are iframes from that host, and a 3-D Secure challenge opens the issuer's page in an iframe |
|
|
303
|
+
| `form-action` | the card issuers' 3-D Secure pages | Adyen posts the 3-D Secure challenge to the issuer as a form |
|
|
304
|
+
| `img-src` | `https://checkoutshopper-{env}.cdn.adyen.com` and `data:` | card brand logos come from the CDN, and Adyen's stylesheet draws some icons as `data:` SVGs |
|
|
305
|
+
| `style-src` | `'unsafe-inline'`, only for browsers without constructable stylesheets | the component adds its styles as a constructed stylesheet, which CSP does not block; without one it falls back to a `<style>` element |
|
|
306
|
+
|
|
307
|
+
Adyen publishes no list of issuer hosts, so `frame-src` and `form-action` need `https:` in practice.
|
|
308
|
+
|
|
309
|
+
---
|
|
310
|
+
|
|
311
|
+
## How it works
|
|
312
|
+
|
|
313
|
+
```
|
|
314
|
+
the page (its own origin)
|
|
315
|
+
└── @nordhealth/provet-pay-elements one JavaScript file
|
|
316
|
+
├── Provet checkout-sessions · saved-cards
|
|
317
|
+
└── Adyen card fields · the $0 authorization · 3-D Secure
|
|
318
|
+
```
|
|
319
|
+
|
|
320
|
+
1. The backend exchanges its credentials for a browser token bound to one shopper.
|
|
321
|
+
2. The page mounts the component with that token. The component first lists the shopper's saved cards from Provet; a refused token stops here, before anything else happens.
|
|
322
|
+
3. To add a card, the component asks Provet to open a session. Provet creates a **pending card** and opens the Adyen session; the browser only ever talks to Provet and Adyen.
|
|
323
|
+
4. The shopper types the card into Adyen's fields. Adyen runs the `$0` authorization and any 3-D Secure challenge, then tells the component, which calls `onSuccess` with the pending card's id.
|
|
324
|
+
5. Adyen's confirmation reaches Provet a few seconds later and turns the pending card into an active one. Nothing on the page polls for that.
|
|
325
|
+
|
|
326
|
+
Saving the same card twice creates two Provet cards that share one Adyen token.
|
|
327
|
+
|
|
328
|
+
### 3-D Secure
|
|
329
|
+
|
|
330
|
+
Most challenges appear inside the form. When an issuer needs a full-page redirect, the browser returns to the page with `redirectResult` in the address. Mount the component there again with the same `auth`: it settles the session it stored before the redirect, removes `redirectResult` from the address so a reload does not submit it twice, and calls `onSuccess` when the check passed. A refused or cancelled check brings the form back with its notice and calls `onRefused`, as in the form; an error calls `onError`. The return address is the page's path without its query string, so a page that needs query parameters to render should keep them somewhere else, for instance its own storage, before the shopper leaves for the challenge.
|
|
331
|
+
|
|
332
|
+
The component stores the unfinished session in `sessionStorage` under a key made from `provetOrigin`, `provetId`, `clientId` and `departmentId`, so a refresh or a redirect resumes the same session, and a second shopper in the same tab starts their own. It never stores the token.
|
|
333
|
+
|
|
334
|
+
## Versioning
|
|
335
|
+
|
|
336
|
+
The package follows semantic versioning. Pin a minor version (`~1.0.0`) and read [CHANGELOG.md](./CHANGELOG.md) before upgrading; breaking changes are announced ahead of time.
|
|
337
|
+
|
|
338
|
+
Working on the package itself: see `DEVELOPMENT.md` in the package's directory of the pay-js repository.
|