@nordhealth/provet-pay-elements 0.18.0 → 0.19.1
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 +28 -0
- package/README.md +28 -6
- package/dist/loader/provet-pay-elements.mjs +1400 -1310
- package/dist/loader/provet-pay-elements.mjs.map +1 -1
- package/dist/loader/provet-pay-elements.umd.js +7 -7
- package/dist/loader/provet-pay-elements.umd.js.map +1 -1
- package/dist/types/index.d.mts +7 -3
- package/dist/types/index.d.ts +7 -3
- package/package.json +1 -1
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,33 @@
|
|
|
1
1
|
# Changelog
|
|
2
2
|
|
|
3
|
+
## 0.19.1
|
|
4
|
+
|
|
5
|
+
### Patch Changes
|
|
6
|
+
|
|
7
|
+
- 8b4a21f: The README has a new "Integration requirements" section. It lists, in one place, everything a page that embeds the component must follow, such as serving the page over HTTPS, loading the package unchanged and keeping the version current. Provet may suspend the component for a page that does not follow them, or whose page is compromised.
|
|
8
|
+
- a7eb8e4: Text that a shipped language leaves empty, or has not translated yet, shows in English from `DEFAULT_TRANSLATIONS` instead of as an empty string or its key.
|
|
9
|
+
|
|
10
|
+
## 0.19.0
|
|
11
|
+
|
|
12
|
+
### Minor Changes
|
|
13
|
+
|
|
14
|
+
- A card form now ends 55 minutes after it opens its session, with an error, instead of taking a card into a session Adyen has ended. Adyen ends a card session an hour after it opens and tells no one, and its fields kept taking card details until Save was refused. Before, the form then showed "Something went wrong while checking the card. Try again, or use another card." and every retry failed the same way.
|
|
15
|
+
|
|
16
|
+
Now:
|
|
17
|
+
|
|
18
|
+
- After 55 minutes the card fields are cleared, the form ends with `onError` (`session_error`), and the banner shows the new `provetPay.errors.session_expired`, "Your session has expired, please reload the page", with `session_expired` in `data-provet-pay-elements-error`. The last 5 minutes are kept for a 3-D Secure check started just before. A check already under way finishes first.
|
|
19
|
+
- A Save that Adyen refuses because the session has expired ends the form the same way.
|
|
20
|
+
- No new session opens on its own: a reload or a new `mount()` opens one, and so does "Add a new card" back on the saved cards. `changeLocale` does nothing once the form has ended this way.
|
|
21
|
+
- A stored session whose form has had its 55 minutes is not resumed, unless the address carries its 3-D Secure result.
|
|
22
|
+
|
|
23
|
+
Also: a session stored by 0.18 is not resumed, since the component now stores when it opened each session. A shopper who had the card form open starts again, and a 3-D Secure return that spans the upgrade is not settled.
|
|
24
|
+
|
|
25
|
+
## 0.18.1
|
|
26
|
+
|
|
27
|
+
### Patch Changes
|
|
28
|
+
|
|
29
|
+
- Once the form has ended on Adyen's attempt limit and "Add a new card" opens a new session, `changeLocale` starts the form again in the new locale. Before, it did nothing for the rest of the mount.
|
|
30
|
+
|
|
3
31
|
## 0.18.0
|
|
4
32
|
|
|
5
33
|
### Minor Changes
|
package/README.md
CHANGED
|
@@ -9,10 +9,12 @@ Add a card step to a web page, and let a shopper save a payment card in Provet,
|
|
|
9
9
|
- **No secrets in the browser.** The component runs on a short-lived token, bound to one shopper, that the backend mints.
|
|
10
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
11
|
|
|
12
|
-
Contents: [Prerequisites](#prerequisites) · [Quick start](#quick-start) · [API](#api) · [Errors](#errors) · [Translations](#translations) · [Appearance](#appearance) · [Content Security Policy](#content-security-policy) · [How it works](#how-it-works) · [Versioning](#versioning)
|
|
12
|
+
Contents: [Prerequisites](#prerequisites) · [Integration requirements](#integration-requirements) · [Quick start](#quick-start) · [API](#api) · [Errors](#errors) · [Translations](#translations) · [Appearance](#appearance) · [Content Security Policy](#content-security-policy) · [How it works](#how-it-works) · [Versioning](#versioning)
|
|
13
13
|
|
|
14
14
|
## Prerequisites
|
|
15
15
|
|
|
16
|
+
**The component works only for integrations that Nordhealth has allowlisted.** To get access, email [pay.dev@nordhealth.com](mailto:pay.dev@nordhealth.com).
|
|
17
|
+
|
|
16
18
|
Three things must be in place before the card form can load on a page.
|
|
17
19
|
|
|
18
20
|
| # | Requirement | Set up by | Why |
|
|
@@ -21,14 +23,31 @@ Three things must be in place before the card form can load on a page.
|
|
|
21
23
|
| 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
24
|
| 3 | A backend that mints the browser token | The integrator | See [step 1](#1-mint-a-browser-token-on-the-backend) |
|
|
23
25
|
|
|
24
|
-
|
|
26
|
+
Send each origin, for example `https://booking.example.com`, for each environment (test and production), to [pay.dev@nordhealth.com](mailto:pay.dev@nordhealth.com).
|
|
25
27
|
|
|
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. Check your connection and try again." and the card fields do not appear. Ask
|
|
28
|
+
**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. Check your connection and try again." and the card fields do not appear. Ask for the port at the same address. In production, partners use their own domains, so this applies to the test environment only.
|
|
27
29
|
|
|
28
30
|
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
31
|
|
|
30
32
|
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
33
|
|
|
34
|
+
## Integration requirements
|
|
35
|
+
|
|
36
|
+
Every page that embeds the component follows all of these. Some are explained in more detail further down; this list is the complete set.
|
|
37
|
+
|
|
38
|
+
- **Register every origin.** Show the component only on origins Provet has added for Provet and for Adyen. See [Prerequisites](#prerequisites).
|
|
39
|
+
- **Serve the page over HTTPS.** Every page that shows the component uses `https:`. Plain `http:` works only for local development on the test environment.
|
|
40
|
+
- **Keep secrets on the backend.** The OAuth client secret and the API token stay on the server. The browser gets only the short-lived browser token. See [step 1](#1-mint-a-browser-token-on-the-backend).
|
|
41
|
+
- **Take the shopper from your own session.** The backend takes the shopper's `clientId` from the user signed in to your site. It never takes it from anything the browser sends, and it mints a token only for that signed-in user.
|
|
42
|
+
- **Use the package as delivered.** Load the published file unchanged, from npm or the CDN. Do not inject scripts into the component, place overlays over it, or change the elements it renders, beyond what [Appearance](#appearance) describes.
|
|
43
|
+
- **Do not proxy its calls.** The component talks to Provet and Adyen directly. Do not route, intercept or rewrite those calls.
|
|
44
|
+
- **Allow what it loads.** If the page sets a Content Security Policy, allow what [Content Security Policy](#content-security-policy) lists.
|
|
45
|
+
- **Keep the version current.** Pin a version as [Versioning](#versioning) describes, and upgrade regularly. Read [CHANGELOG.md](./CHANGELOG.md) before each upgrade.
|
|
46
|
+
- **Use it only for the agreed flow.** Use the component only for the card step it was set up for with Provet, for example a health plan signup.
|
|
47
|
+
- **Report security incidents.** Tell Provet through your usual support contact, without delay, if the page, its backend or its credentials may be compromised.
|
|
48
|
+
|
|
49
|
+
Provet may suspend the component for an integrator that does not follow these requirements, or whose page is compromised. Provet will tell the integrator when it does.
|
|
50
|
+
|
|
32
51
|
## Quick start
|
|
33
52
|
|
|
34
53
|
### 1. Mint a browser token on the backend
|
|
@@ -255,7 +274,7 @@ options.locale = 'sv-SE' // or: handle.changeLocale('sv-SE')
|
|
|
255
274
|
|
|
256
275
|
Adyen takes its locale only when its checkout starts, and 6.40.1 keeps that language through its own `update()`, so the card fields start again too: what the shopper typed into them is cleared, and `onReady` is called again once the form is back. An open card session is resumed rather than a second one opened, so a shopper who opened the card form comes back to it; otherwise the saved cards show again. Starting again calls Provet again, so once the token has expired it needs `auth.refreshToken`.
|
|
257
276
|
|
|
258
|
-
It does nothing for the locale the form already has, while a card check is running (from the save button until its result, 3-D Secure included), once the card is saved, after Adyen has ended the session for too many attempts, or after `unmount()`. Called while the form is still opening a card session, it waits for that session instead of opening a second one. A `locale` that is not a string throws `config_invalid` and leaves the form as it is.
|
|
277
|
+
It does nothing for the locale the form already has, while a card check is running (from the save button until its result, 3-D Secure included), once the card is saved, after Adyen has ended the session for too many attempts (until "Add a new card" opens a new session), or after `unmount()`. Called while the form is still opening a card session, it waits for that session instead of opening a second one. A `locale` that is not a string throws `config_invalid` and leaves the form as it is.
|
|
259
278
|
|
|
260
279
|
### Tokens
|
|
261
280
|
|
|
@@ -270,7 +289,7 @@ A `403` means the token authenticates but does not have the `card_tokenization`
|
|
|
270
289
|
|
|
271
290
|
## Errors
|
|
272
291
|
|
|
273
|
-
`mount()` throws `config_invalid` for a bad configuration. Everything else reaches `onError({ type, message })`. When the component cannot load or continue, the form shows a red banner worded for what went wrong (the `provetPay.errors.*` texts in [Translations](#translations)); the banner carries the cause as `data-provet-pay-elements-error`: one of `network`, `auth_error`, `auth_forbidden`, `session_error`, `attempts_exceeded`, `config_invalid`, `cancelled` or `technical`, the key it shows. If the card form fails while the back control is showing, the control stays: going back resets the form, on its card session, and offers the saved cards again, so `onSuccess` can still follow that `onError`. When Adyen reports an error while its card fields are loaded and on the page, for instance a call during the card check that fails, the
|
|
292
|
+
`mount()` throws `config_invalid` for a bad configuration. Everything else reaches `onError({ type, message })`. When the component cannot load or continue, the form shows a red banner worded for what went wrong (the `provetPay.errors.*` texts in [Translations](#translations)); the banner carries the cause as `data-provet-pay-elements-error`: one of `network`, `auth_error`, `auth_forbidden`, `session_error`, `session_expired`, `attempts_exceeded`, `config_invalid`, `cancelled` or `technical`, the key it shows. If the card form fails while the back control is showing, the control stays: going back resets the form, on its card session, and offers the saved cards again, so `onSuccess` can still follow that `onError`. When Adyen reports an error while its card fields are loaded and on the page, for instance a call during the card check that fails, the form stays with the `provetPay.notices.error` notice and the shopper can try again in place. The exceptions are Adyen's attempt limit and the form's time running out, below. `onError` is called either way, never `onRefused`, so it does not always mean the form is gone. `message` is a diagnostic for your logs and for support, not for the shopper: the component's own messages are English, but a `session_error` can carry Provet's message, which Provet words in the browser's language.
|
|
274
293
|
|
|
275
294
|
| `type` | Meaning | What to do |
|
|
276
295
|
| --------------- | -------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------- |
|
|
@@ -280,6 +299,8 @@ A `403` means the token authenticates but does not have the `card_tokenization`
|
|
|
280
299
|
|
|
281
300
|
A failed check is not an error: it calls `onRefused({ resultCode })` and the shopper tries again in place. Adyen ends a card session once the shopper has made too many attempts (it does not publish the number). The next attempt then ends the component with `onError` (`session_error`, "This card form had too many attempts. Try again later, or use another card."), and the banner shows `provetPay.errors.attempts_exceeded`. Do not mount the component again automatically on this error: a new mount opens a new session, which is a decision about this shopper for the page to make. The notice says what happened, with the `provetPay.notices.*` texts: "The card was declined. Try another card." for `Refused`, "The card check was cancelled. Try again." for `Cancelled`, and "Something went wrong while checking the card. Try again, or use another card." for `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.
|
|
282
301
|
|
|
302
|
+
A card form takes card details for 55 minutes after it opens its session. Adyen ends a card session an hour after it opens, without telling anyone, and its fields would take a card it then refuses; the last 5 minutes are kept for a 3-D Secure check started just before. When the time is up, the card fields are cleared and the form ends with `onError` (`session_error`), and the banner shows `provetPay.errors.session_expired`, "Your session has expired, please reload the page". A card check already under way finishes first: a saved card still calls `onSuccess`, and a refused one ends the form. A Save that Adyen refuses because the session has expired ends the form the same way. The component opens no new session on its own: a reload or a new `mount()` opens one, and so does "Add a new card" when the shopper goes back to their saved cards. If the saved cards are on screen when the time is up, the form's session is dropped with no banner.
|
|
303
|
+
|
|
283
304
|
## Translations
|
|
284
305
|
|
|
285
306
|
The card fields (card number, expiry date, security code, name on the card, the save button) are Adyen's, and so are the `locale` and `translations` options: they reach Adyen exactly as given, with `en-GB` for a `locale` left out, so [Adyen's localization docs](https://docs.adyen.com/online-payments/build-your-integration/sessions-flow/?platform=Web&integration=Components&version=6.40.1#localization) apply as written. The component's own text (the saved-card list, the notices, the error banner, the back control) follows the same two options, read Adyen's way.
|
|
@@ -343,6 +364,7 @@ The keys are part of the API: apart from the `provetPay.savedCards.remove*` keys
|
|
|
343
364
|
| `provetPay.errors.network` | Could not reach the server. Check your connection and try again. |
|
|
344
365
|
| `provetPay.errors.auth_error`, `provetPay.errors.auth_forbidden` | The card form is not available right now. Reload the page and try again. |
|
|
345
366
|
| `provetPay.errors.session_error` | The card form could not be opened. Try again later. |
|
|
367
|
+
| `provetPay.errors.session_expired` | Your session has expired, please reload the page |
|
|
346
368
|
| `provetPay.errors.attempts_exceeded` | This card form had too many attempts. Try again later, or use another card. |
|
|
347
369
|
| `provetPay.errors.cancelled` | The card setup was cancelled. |
|
|
348
370
|
| `provetPay.errors.config_invalid`, `provetPay.errors.technical` | Something went wrong while setting up the card. |
|
|
@@ -424,7 +446,7 @@ Saving the same card twice creates two Provet cards that share one Adyen token.
|
|
|
424
446
|
|
|
425
447
|
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 options: it settles the session it stored before the redirect, unless Adyen's `sessionId` names another session, removes `redirectResult` and `sessionId` from the address so a reload does not submit them twice, and calls `onSuccess` when the check passed. A failed check brings the form back with its notice and calls `onRefused`, and a call to Adyen that fails calls `onError`, as in the form. 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.
|
|
426
448
|
|
|
427
|
-
The component stores the unfinished session in `sessionStorage` under a key made from `provetOrigin`, `provetId`, `clientId` and `departmentId`, together with that `auth` and the `recurringModel` and page it was opened for. A refresh or a redirect resumes it only for a mount with the same `auth`, so a second shopper in the same tab starts their own. A mount with another `recurringModel`, or on another page, opens its own session, unless the address carries the stored session's 3-D Secure result. It never stores the token. A session stored by an earlier version of the component is not resumed. Adyen keeps its own copy of the session in `localStorage`.
|
|
449
|
+
The component stores the unfinished session in `sessionStorage` under a key made from `provetOrigin`, `provetId`, `clientId` and `departmentId`, together with that `auth` and the `recurringModel` and page it was opened for. A refresh or a redirect resumes it only for a mount with the same `auth`, so a second shopper in the same tab starts their own. A mount with another `recurringModel`, or on another page, opens its own session, unless the address carries the stored session's 3-D Secure result. A session whose form has had its 55 minutes is not resumed either, unless the address carries its 3-D Secure result. It never stores the token. A session stored by an earlier version of the component is not resumed. Adyen keeps its own copy of the session in `localStorage`.
|
|
428
450
|
|
|
429
451
|
## Versioning
|
|
430
452
|
|