@nordhealth/provet-pay-elements 0.15.0 → 0.18.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 CHANGED
@@ -1,5 +1,73 @@
1
1
  # Changelog
2
2
 
3
+ ## 0.18.1
4
+
5
+ ### Patch Changes
6
+
7
+ - 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.
8
+
9
+ ## 0.18.0
10
+
11
+ ### Minor Changes
12
+
13
+ - c2f3925: Breaking: an unfinished card session belongs to the `auth` it was opened with. The component stores it together with that `auth` (Provet instance, tenant, client and department), the `recurringModel` and the page it was opened on, and resumes it only for a mount with the same `auth`. 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 stored by an earlier version is not resumed: a shopper who had the card form open starts again, and a 3-D Secure return that spans the upgrade is not settled.
14
+
15
+ Also breaking:
16
+
17
+ - `auth.clientId` must be the Provet client id as the token's audience carries it (`client:<id>`), digits only; anything else makes `mount()` throw `config_invalid`.
18
+ - A container holds one form. A second `mount()` into it for the same shopper throws `config_invalid` and keeps the first form; one for another shopper stops the first form as well and throws.
19
+
20
+ Fixed:
21
+
22
+ - Mounts for the same shopper on one page share one card session. Mounting again, or calling `changeLocale`, while the form is still opening a session waits for it instead of opening a second pending card, and so do a second container, "Add a new card" beside a session another form stored, and two forms replacing a session Adyen no longer starts.
23
+ - A session still being opened when the shopper picks a saved card or saves a card is not stored, so the next mount offers the saved cards instead of reopening the form. Clearing a finished session no longer removes a newer one another form stored.
24
+ - `auth.refreshToken` is not called after `unmount()`, and a token it returns after `unmount()` is not used.
25
+ - With two forms on a 3-D Secure return page, the result is submitted to Adyen once.
26
+ - `changeLocale` does nothing after Adyen has ended the session for too many attempts, instead of opening a new session.
27
+
28
+ ### Patch Changes
29
+
30
+ - cec47ff: Going back to the saved cards from a card form that shows an error (the error banner, a notice such as "The card was declined", or a field Adyen marks invalid) now resets the form, on the same card session, so "Add a new card" shows it empty. Before, the same form came back with its field errors, and after a load failure without its banner. A form with no errors still keeps what the shopper typed.
31
+
32
+ `unmount()` with the saved-card list open now closes the list. Before, the list kept listening for presses on the page, and kept the unmounted component in memory, until the next press anywhere on the page.
33
+
34
+ - 7bb2e67: The component's loading indicator now matches the spinner Adyen shows over the card fields: the same size, colours and motion. Before, it was a smaller spinner with its own colours and speed, so the two read as two different loaders. Both draw their arc in `appearance.variables.colorAccent` and their faint track in `colorText`, so they stay alike under any appearance.
35
+
36
+ ## 0.17.0
37
+
38
+ ### Minor Changes
39
+
40
+ - d1cb6ee: Breaking: `appearance.secured` is now `styles`, Adyen's own option with all of its properties, and the `SecuredFieldStyle` type is now Adyen's `StyleDefinitions`. The error banner shows the component's text for the error's code (`provetPay.errors.<code>`), named in a new `data-provet-pay-elements-error` attribute, instead of `onError`'s `message`. `mount()` throws `config_invalid` for a `locale` that is not a string.
41
+
42
+ New:
43
+
44
+ - `translations`, Adyen's custom translations keyed by locale: Adyen's keys change the card fields, the `provetPay.*` keys (`PayCardTranslations`) the component's own text. The component resolves `locale` by Adyen's rules over the locales it has text for (British English, which this version ships, and `translations` entries holding `provetPay.*` keys), else British English.
45
+ - With no or an empty `locale`, the component uses `en-GB` and passes it to Adyen, which ships no British English, so its card fields read US English. Both defaults are exported: `DEFAULT_LOCALE` and `DEFAULT_TRANSLATIONS`.
46
+ - Setting `locale` on the options object given to `mount()`, or calling `changeLocale(locale)` on what `mount()` returns, starts the form again in that locale, resuming its open card session. Adyen takes its locale only when it starts, so what the shopper typed into the card fields is cleared. While a card check runs, it does nothing.
47
+ - `disclaimerMessage`, Adyen's line under the card fields.
48
+ - `onRefused` gets `{ resultCode }`: `Refused`, `Cancelled` or `Error`. `onSuccess` gets `resultCode` for a card saved in the form.
49
+ - Also exported: the `CustomTranslations`, `DisclaimerMsgObject`, `ResultCode` and `StylesObject` types.
50
+
51
+ Fixed:
52
+
53
+ - A call to Adyen that fails during the card check no longer shows "The card was declined" or calls `onRefused`: `onError` is called, and while the card fields are on the page the form stays for another try.
54
+ - `onError` is called once when Adyen cannot start a session, and `onReady` once per start of the form, when the shopper first has something to act on.
55
+ - A 3-D Secure redirect result for another session is left for that session.
56
+
57
+ ### Patch Changes
58
+
59
+ - 6cf60ee: When Adyen ends a card session because the shopper made too many attempts, the component now ends with one error: `onError` with `session_error` and "This card form had too many attempts. Try again later, or use another card." Before, the form said "The card was declined" and every further attempt failed the same way, while the page received both `onError` and `onRefused`. The component does not open a new session on its own: Adyen's limit is a guard against repeated card attempts, so whether to mount again is the page's decision.
60
+
61
+ ## 0.16.0
62
+
63
+ ### Minor Changes
64
+
65
+ - c1e92c3: The package is published on npm as `@nordhealth/provet-pay-elements`, replacing the hand-delivered tarball. Install it with `npm install @nordhealth/provet-pay-elements`; the `mount()` API is unchanged. Each version is also served on the CDN at its own URL with an SRI hash for script-tag consumers.
66
+
67
+ ### Patch Changes
68
+
69
+ - c1e92c3: The package ships one flattened type declaration (`dist/types/index.d.ts`) instead of per-module files, so the published types are exactly the documented API and internal module paths cannot be imported for their types.
70
+
3
71
  ## 0.15.0 - 29/09/2026
4
72
 
5
73
  - (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)
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) · [Appearance](#appearance) · [Content Security Policy](#content-security-policy) · [How it works](#how-it-works) · [Versioning](#versioning)
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)
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,9 +23,9 @@ 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
- Ask Provet to add each origin, for example `https://booking.example.com`, for each environment (test and production).
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." 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.
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
 
@@ -164,8 +166,8 @@ A complete plain-JavaScript page:
164
166
  document.getElementById('result').textContent =
165
167
  'Saved card ' + result.card.id
166
168
  },
167
- onRefused: function () {
168
- // The card was declined; the form shows a notice and the shopper can try again.
169
+ onRefused: function (result) {
170
+ // result.resultCode is Refused, Cancelled or Error; the form shows a notice and the shopper can try again.
169
171
  },
170
172
  onError: function (error) {
171
173
  console.error(error.type, error.message)
@@ -194,7 +196,7 @@ If the shopper already has saved cards, the component offers them first.
194
196
 
195
197
  | Where the card comes from | `onSuccess` receives | Chargeable |
196
198
  | --------------------------- | ---------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
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. |
199
+ | Entered in the form | `{ card: { id }, resultCode }` | 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
200
  | Picked from the saved cards | `{ card: { id, brand, last4, expiration_date, default } }` | Already active |
199
201
 
200
202
  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.
@@ -205,35 +207,57 @@ After a card is saved, the form is replaced by a "Card saved" confirmation and t
205
207
 
206
208
  ### `mount(container, options)`
207
209
 
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.
210
+ Returns `{ unmount(), changeLocale(locale) }`. `container` is an `HTMLElement` or a CSS selector; a selector that matches nothing throws.
211
+
212
+ | Option | Type | Required | Description |
213
+ | ------------------- | -------------------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
214
+ | `auth.token` | `string` | yes | The browser token from [step 1](#1-mint-a-browser-token-on-the-backend). |
215
+ | `auth.provetId` | `string \| number` | yes | The clinic's Provet instance id (the tenant). |
216
+ | `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. |
217
+ | `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. |
218
+ | `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. |
219
+ | `auth.refreshToken` | `() => Promise<string>` | no | Returns a new token after the current one is refused with 401. See [Tokens](#tokens). |
220
+ | `recurringModel` | `'subscription' \| 'one-off'` | no | What the card will be used for: Provet stores it for Adyen's `Subscription` or `CardOnFile` model. Defaults to `'subscription'`. |
221
+ | `locale` | `string` | no | Adyen's `locale`, for example `fi-FI`. The card fields and the component's text follow it. Defaults to `en-GB`. See [Translations](#translations). |
222
+ | `translations` | object | no | Adyen's `translations`, keyed by locale, for the card fields and the component's text. See [Translations](#translations). |
223
+ | `styles` | object | no | Adyen's `styles` for the card fields. See [Appearance](#appearance). |
224
+ | `disclaimerMessage` | `{ message, linkText, link }` | no | Adyen's `disclaimerMessage`: a line under the card fields, for instance the shopper's consent. See below. |
225
+ | `appearance` | object | no | The component's own colors, radius and font. See [Appearance](#appearance). |
226
+ | `onSuccess` | `({ card, resultCode }) => void` | yes | The shopper is done with a card. `resultCode` is Adyen's, for example `Authorised`, for a card saved in the form; a picked card has none. |
227
+ | `onRefused` | `({ resultCode }) => void` | no | The card check ended `Refused`, `Cancelled` or `Error`, Adyen's `resultCode`. The form says so and the shopper can try again. |
228
+ | `onError` | `({ type, message }) => void` | no | Something went wrong: the component could not load or continue, or Adyen reported an error and the form stays for another try. See [Errors](#errors). |
229
+ | `onReady` | `() => void` | no | Called when the shopper first has something to act on: the saved cards, or the card fields once Adyen says they are ready. Again on `changeLocale`. |
230
+
231
+ A missing required field, a `provetOrigin` that is not a Provet instance, a `clientId` that is not a Provet client id, a `locale` that is not a string, `translations` that are not an object of objects keyed by locale, or a container that already holds the form make `mount()` throw an error with code `config_invalid` before anything is shown or requested.
227
232
 
228
233
  `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
234
 
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.
235
+ Adyen asks for the shopper's consent before a card is stored for later payments, and for the shopper to be told how it will be charged ([Adyen](https://docs.adyen.com/online-payments/tokenization/create-tokens)). Say it on the page, or pass it as `disclaimerMessage`; `%{linkText}` in `message` becomes a link to `link`, which must be a full `https:` address or Adyen leaves the line out.
236
+
237
+ `clientId` must be the client the token was exchanged for, written as in the token's audience `client:<id>`: digits only. The component cannot check it against the token, because the client is only in Provet's records. It binds the unfinished session to the `auth` it was mounted with (Provet instance, tenant, client and department) and resumes it only for a mount with the same `auth`, so always pass the same client to both. When the page switches to another client, unmount and mount again with that client's token and id.
231
238
 
232
239
  ### `handle.unmount()`
233
240
 
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.
241
+ Removes everything the component added to the container. After it, no callback fires, except `onSuccess` for a card whose save was already under way, and `auth.refreshToken` is not called. A session the component was opening is kept, so mounting again for the same shopper resumes it instead of opening a second one.
242
+
243
+ Mounts for the same shopper on one page share one card session: a mount that starts while another is still opening the session waits for it. React StrictMode's mount, unmount and mount opens one session. Two forms on screen for one shopper show that same session, so mount the component once per shopper.
244
+
245
+ A container holds one form. Mounting into it again for the same shopper throws `config_invalid` and keeps the first form; mounting into it for another shopper stops the first form as well and throws. In React, an effect that awaits the token checks that it was not cleaned up before it calls `mount()`.
246
+
247
+ ### `handle.changeLocale(locale)`
235
248
 
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.
249
+ Set `locale` on the options object you passed to `mount()`, or call `changeLocale(locale)`, and the form starts again in that locale, which takes what the `locale` option takes. `mount()` turns that property into a setter until `unmount()`. A frozen or sealed object keeps its plain property, so call `changeLocale` there, and wherever you do not keep the options object. `translations` stay as given to `mount()`, so give the text for every language you switch to there.
250
+
251
+ ```js
252
+ const options = { auth, translations, onSuccess }
253
+ const handle = mount('#card', options)
254
+
255
+ options.locale = 'sv-SE' // or: handle.changeLocale('sv-SE')
256
+ ```
257
+
258
+ 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`.
259
+
260
+ 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.
237
261
 
238
262
  ### Tokens
239
263
 
@@ -242,19 +266,90 @@ The token lasts at most 10 minutes. When Provet answers a call with `401`:
242
266
  - 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
267
  - without it, the expiry is reported as `auth_error`.
244
268
 
269
+ `refreshToken` must return a token for the same client. It is not called after `unmount()`, and a token it returns after `unmount()` is not used.
270
+
245
271
  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
272
 
247
273
  ## Errors
248
274
 
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.
275
+ `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 session is still usable: the form stays with the `provetPay.notices.error` notice and the shopper can try again in place. The exception is Adyen's attempt limit, 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.
250
276
 
251
277
  | `type` | Meaning | What to do |
252
278
  | --------------- | -------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------- |
253
279
  | `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. |
280
+ | `session_error` | Provet or Adyen could not open or continue the card session: an unavailable service, a department without Provet Pay, and so on. | Offer to try again; log the message. |
281
+ | `technical` | Anything else, including an origin Adyen does not accept or a card setup that was cancelled. | Log the message; it helps support. |
282
+
283
+ 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.
284
+
285
+ ## Translations
286
+
287
+ 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.
288
+
289
+ **Choosing the language.** Pass one of Adyen's locales, for example `fi-FI`, `sv-SE` or `no-NO`. Without one, the component uses `en-GB` (`DEFAULT_LOCALE`) for its text and passes it to Adyen. Adyen takes the exact locale, else the first it has with the same two letters, else US English. Adyen ships no British English, so with `en-GB` its card fields read US English, with Adyen's keys from your `translations` for the English locale it settles on, if any. The component's text follows the same rule over the locales it has text for (the dictionaries it ships, and your `translations` entries that hold `provetPay.*` keys), with British English instead of US English. This version ships British English; other languages ship as they are translated. To change it after mounting, set `locale` on the options object or call [`changeLocale`](#handlechangelocalelocale).
290
+
291
+ **Adding or changing text.** `translations` is Adyen's custom translations: an object keyed by locale, each holding keys and their text. Adyen's keys change the card fields; the `provetPay.*` keys below change the component's text. A locale that neither Adyen nor the component ships works the same way, as Adyen documents: pass it as `locale` and give its text in `translations`. The defaults are exported to read or build on: `DEFAULT_LOCALE` (`'en-GB'`) and `DEFAULT_TRANSLATIONS`, the component's British English text, typed as a complete, read-only `PayCardTranslations`.
256
292
 
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.
293
+ ```js
294
+ // Your words for the default British English: no locale needed.
295
+ mount('#card', {
296
+ auth,
297
+ translations: {
298
+ 'en-GB': {
299
+ 'provetPay.cardSaved': 'Card stored',
300
+ 'payButton.saveDetails': 'Save card',
301
+ },
302
+ },
303
+ onSuccess,
304
+ })
305
+
306
+ // Swedish: Adyen ships it for the card fields; you give the component's text.
307
+ mount('#card', {
308
+ auth,
309
+ locale: 'sv-SE',
310
+ translations: {
311
+ 'sv-SE': {
312
+ 'provetPay.cardSaved': 'Kortet har sparats',
313
+ 'provetPay.savedCards.heading': 'Använd ett sparat kort',
314
+ },
315
+ },
316
+ onSuccess,
317
+ })
318
+ ```
319
+
320
+ As in Adyen, your text for a locale is used for the locale `locale` resolves to, over the component's own text for it, and anything left out comes from British English. Your text reaches the page as text, never as HTML. Placeholders are Adyen's `%{name}`. `provetPay.savedCards.choose` counts the cards as Adyen counts: `__1`, `__2` and so on for an exact number, `__plural` for any other number above one, and the key itself otherwise.
321
+
322
+ Adyen 6.40.1 shows its Brazilian Portuguese text for `pt-PT` and its Simplified Chinese for `zh-TW`, because it picks its own files by the first two letters; Adyen's keys for those locales in `translations` correct it.
323
+
324
+ The keys are part of the API: apart from the `provetPay.savedCards.remove*` keys below the table, none is renamed or removed without a breaking release. The TypeScript type `PayCardTranslations` lists them with their British English text.
325
+
326
+ | Key | British English |
327
+ | ---------------------------------------------------------------- | ----------------------------------------------------------------------------- |
328
+ | `provetPay.backToSavedCards` | Back to saved cards |
329
+ | `provetPay.loading` | Loading the card form (read by screen readers) |
330
+ | `provetPay.cardSaved` | Card saved |
331
+ | `provetPay.savedCards.heading` | Use a saved card |
332
+ | `provetPay.savedCards.choose` | Choose your saved card (one card) |
333
+ | `provetPay.savedCards.choose__plural` | Choose one of your %{count} saved cards |
334
+ | `provetPay.savedCards.list` | Saved cards (read by screen readers) |
335
+ | `provetPay.savedCards.addNew` | Add a new card |
336
+ | `provetPay.savedCards.noNumber` | Saved card (a card with no number on record) |
337
+ | `provetPay.savedCards.expiry` | (EXP: %{date}) |
338
+ | `provetPay.savedCards.remove` | Remove %{card} |
339
+ | `provetPay.savedCards.removeQuestion` | Remove this saved card? |
340
+ | `provetPay.savedCards.removeConfirm` | Remove |
341
+ | `provetPay.savedCards.removeCancel` | Cancel |
342
+ | `provetPay.notices.refused` | The card was declined. Try another card. |
343
+ | `provetPay.notices.cancelled` | The card check was cancelled. Try again. |
344
+ | `provetPay.notices.error` | Something went wrong while checking the card. Try again, or use another card. |
345
+ | `provetPay.errors.network` | Could not reach the server. Check your connection and try again. |
346
+ | `provetPay.errors.auth_error`, `provetPay.errors.auth_forbidden` | The card form is not available right now. Reload the page and try again. |
347
+ | `provetPay.errors.session_error` | The card form could not be opened. Try again later. |
348
+ | `provetPay.errors.attempts_exceeded` | This card form had too many attempts. Try again later, or use another card. |
349
+ | `provetPay.errors.cancelled` | The card setup was cancelled. |
350
+ | `provetPay.errors.config_invalid`, `provetPay.errors.technical` | Something went wrong while setting up the card. |
351
+
352
+ `provetPay.savedCards.remove`, `provetPay.savedCards.removeQuestion`, `provetPay.savedCards.removeConfirm` and `provetPay.savedCards.removeCancel` belong to removing a saved card, which this version does not offer yet; they may change before it does.
258
353
 
259
354
  ## Appearance
260
355
 
@@ -268,8 +363,8 @@ mount('#card', {
268
363
  onSuccess,
269
364
  appearance: {
270
365
  variables: { colorAccent: '#5b21b6', borderRadius: '8px' },
271
- secured: { base: { color: '#1f2733' } },
272
366
  },
367
+ styles: { base: { color: '#1f2733' } },
273
368
  })
274
369
  ```
275
370
 
@@ -281,14 +376,16 @@ mount('#card', {
281
376
  | `colorButton` | Adyen's pay button |
282
377
  | `colorText` | field labels and the text inside the card fields |
283
378
  | `colorBorder` | field outlines |
284
- | `colorSurface` | the component's own background |
379
+ | `colorSurface` | the saved-card dropdown and dialog backgrounds |
285
380
  | `colorError` | field error text and outline |
286
381
  | `borderRadius` | field corners |
287
382
  | `fontFamily` | the text inside the card fields |
288
383
 
289
- `secured` styles reach inside Adyen's card-field iframes. Those are cross-origin, so only concrete values (`'#1f2733'`, `'16px'`) work there, never `var(…)`.
384
+ `styles` is Adyen's option for the card fields, [as Adyen documents it](https://docs.adyen.com/payment-methods/cards/custom-card-integration#styling): CSS by field state (`base`, `error`, `validated`, `placeholder`). The fields are cross-origin iframes, so only concrete values (`'#1f2733'`, `'16px'`) work there, never `var(…)`.
385
+
386
+ `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 `styles` wins over both.
290
387
 
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.
388
+ The component sets ten of Adyen's `--adyen-sdk-*` properties on its own root, so page values for those ten do not reach the card fields: set them with `cssVariables`. The others still follow the page. Adyen's class names can still be overridden, with a selector more specific than Adyen's, because the component's stylesheet comes after the page's.
292
389
 
293
390
  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
391
 
@@ -298,7 +395,7 @@ If the page sets a Content Security Policy, allow what the component and Adyen l
298
395
 
299
396
  | Directive | Allow | Because |
300
397
  | ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
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 |
398
+ | `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 the non-English translations it ships, from that CDN |
302
399
  | `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
400
  | `form-action` | the card issuers' 3-D Secure pages | Adyen posts the 3-D Secure challenge to the issuer as a form |
304
401
  | `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 |
@@ -327,9 +424,9 @@ Saving the same card twice creates two Provet cards that share one Adyen token.
327
424
 
328
425
  ### 3-D Secure
329
426
 
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.
427
+ 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.
331
428
 
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.
429
+ 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`.
333
430
 
334
431
  ## Versioning
335
432