@paydock/client-sdk 1.145.0-beta → 1.147.0

package/README.md

@@ -194,8 +194,48 @@ widget.setRefId('id'); // your unique identifier to identify the data
 widget.setFormFields(['phone', 'email']); // add additional fields for form of widget
 
 widget.setSupportedCardIcons(['mastercard', 'visa']); // add icons of supported card types
+
+widget.setAllowedCardSchemes(['mastercard', 'visa']); // restrict which card schemes the card number field accepts
+```
+
+### Restricting accepted card schemes
+
+`setAllowedCardSchemes(schemes)` restricts which card schemes the card number field accepts, **without** changing
+which card icons the widget displays. Call it before `load()`.
+
+```javascript
+widget.setAllowedCardSchemes(['visa', 'mastercard']);
 ```
 
+Accepted identifiers — the schemes the widget can resolve from a card number:
+
+`amex`, `ausbc`, `diners`, `discover`, `eftpos`, `japcb`, `mastercard`, `solo`, `unionpay`, `visa`
+
+Behaviour:
+
+- **Not called, or an empty array** — every scheme is accepted. Existing integrations are unaffected.
+- **Case-insensitive**, and surrounding whitespace is ignored: `' Visa '` and `'MASTERCARD'` both work. Note that
+  `setSupportedCardIcons` matches case-**sensitively**; the two methods differ here.
+- **Unsupported identifiers are ignored with a `console.warn`** naming the value, and never throw. A list in which
+  every identifier is unsupported therefore applies **no restriction at all** — check the console if a restriction
+  seems to have no effect. The icon-only values `visa_white` and `eftpos_white` are not schemes and are rejected,
+  as are `laser` and `maestro`, which the widget can never resolve from a card number.
+- **Takes precedence over `setSupportedCardIcons`.** When a non-empty list is supplied here, it is the only list
+  used for validation, and the second argument of `setSupportedCardIcons` no longer affects validation. Icons keep
+  coming from `setSupportedCardIcons`, so a scheme can legitimately be shown as an icon and still be rejected —
+  make sure that is what you intend:
+
+  ```javascript
+  widget.setSupportedCardIcons(['visa', 'mastercard', 'amex'], true);
+  widget.setAllowedCardSchemes(['visa', 'mastercard']);
+  // three icons are displayed; an Amex card is rejected
+  ```
+
+- **Calling it again replaces the previous list** rather than merging with it.
+- A card of a rejected scheme shows `Card type not accepted.` on the card number field, the submit button is
+  disabled, and the submit handler refuses the card even if the button is re-enabled outside the widget. The same
+  message is shown for a card whose scheme cannot be resolved at all.
+
 This example shows how you can use a lot of other methods to settings your form
 
 ### Error handling
@@ -355,6 +395,7 @@ When handling errors, consider:
  var widget = new paydock.HtmlWidget('#widget', 'publicKey', 'gatewayId');
 
  widget.setSupportedCardIcons(['mastercard', 'visa']);
+ widget.setAllowedCardSchemes(['mastercard', 'visa']);
  widget.setFormFields(['phone', 'email']);
  widget.setRefId('custom-ref-id');
     widget.onFinishInsert('input[name="payment_source_token"]', 'payment_source');
@@ -400,6 +441,12 @@ When handling errors, consider:
 <dt><a href="#user-content-w_GENERIC_VALIDATORS">GENERIC_VALIDATORS</a> : <code>Record.&lt;string, string&gt;</code></dt>
 <dd><p>List of available generic form field validators and their definition</p>
 </dd>
+<dt><a href="#user-content-w_CARD_SCHEME">CARD_SCHEME</a></dt>
+<dd><p>Card schemes the widget is able to resolve from a card number, and therefore the only values
+<code>setAllowedCardSchemes</code> accepts. This is a separate vocabulary from SUPPORTED_CARD_TYPES, which drives the
+card icons: it omits the icon-only variants <code>visa_white</code> / <code>eftpos_white</code>, and the <code>laser</code> / <code>maestro</code>
+identifiers the widget can never resolve — allowing those would be configuration that can never match.</p>
+</dd>
 <dt><a href="#user-content-w_TRIGGER">TRIGGER</a> : <code>object</code></dt>
 <dd><p>List of available triggers</p>
 </dd>
@@ -786,6 +833,15 @@ List of available generic form field validators and their definition
 | --- | --- | --- | --- |
 | REQUIRED | <code>string</code> | <code>&quot;required&quot;</code> | Asserts the input or form field has a value defined truthy value |
 
+<a name="w_CARD_SCHEME" id="w_CARD_SCHEME" href="#user-content-w_CARD_SCHEME">&nbsp;</a>
+
+## CARD\_SCHEME
+Card schemes the widget is able to resolve from a card number, and therefore the only values
+`setAllowedCardSchemes` accepts. This is a separate vocabulary from SUPPORTED_CARD_TYPES, which drives the
+card icons: it omits the icon-only variants `visa_white` / `eftpos_white`, and the `laser` / `maestro`
+identifiers the widget can never resolve — allowing those would be configuration that can never match.
+
+**Kind**: global constant  
 <a name="w_TRIGGER" id="w_TRIGGER" href="#user-content-w_TRIGGER">&nbsp;</a>
 
 ## TRIGGER : <code>object</code>
@@ -958,6 +1014,12 @@ This example shows how you can use a lot of other methods to settings your form
 <dt><a href="#user-content-psw_PAYMENT_SOURCE_TYPE">PAYMENT_SOURCE_TYPE</a> : <code>object</code></dt>
 <dd><p>List of available payment source types</p>
 </dd>
+<dt><a href="#user-content-psw_CARD_SCHEME">CARD_SCHEME</a></dt>
+<dd><p>Card schemes the widget is able to resolve from a card number, and therefore the only values
+<code>setAllowedCardSchemes</code> accepts. This is a separate vocabulary from SUPPORTED_CARD_TYPES, which drives the
+card icons: it omits the icon-only variants <code>visa_white</code> / <code>eftpos_white</code>, and the <code>laser</code> / <code>maestro</code>
+identifiers the widget can never resolve — allowing those would be configuration that can never match.</p>
+</dd>
 </dl>
 
 ## Typedefs
@@ -1509,6 +1571,15 @@ List of available payment source types
 | BANK_ACCOUNT | <code>string</code> | <code>&quot;bank_account&quot;</code> | 
 | CHECKOUT | <code>string</code> | <code>&quot;checkout&quot;</code> | 
 
+<a name="psw_CARD_SCHEME" id="psw_CARD_SCHEME" href="#user-content-psw_CARD_SCHEME">&nbsp;</a>
+
+## CARD\_SCHEME
+Card schemes the widget is able to resolve from a card number, and therefore the only values
+`setAllowedCardSchemes` accepts. This is a separate vocabulary from SUPPORTED_CARD_TYPES, which drives the
+card icons: it omits the icon-only variants `visa_white` / `eftpos_white`, and the `laser` / `maestro`
+identifiers the widget can never resolve — allowing those would be configuration that can never match.
+
+**Kind**: global constant  
 <a name="psw_listener--PaymentSourceWidget" id="psw_listener--PaymentSourceWidget" href="#user-content-psw_listener--PaymentSourceWidget">&nbsp;</a>
 
 ## listener--PaymentSourceWidget : <code>function</code>
@@ -1670,6 +1741,12 @@ Then write only need 1 line of code in js to initialize widget
 <dl>
 <dt><a href="#user-content-cb_CHECKOUT_BUTTON_EVENT">CHECKOUT_BUTTON_EVENT</a> : <code>object</code></dt>
 <dd></dd>
+<dt><a href="#user-content-cb_CARD_SCHEME">CARD_SCHEME</a></dt>
+<dd><p>Card schemes the widget is able to resolve from a card number, and therefore the only values
+<code>setAllowedCardSchemes</code> accepts. This is a separate vocabulary from SUPPORTED_CARD_TYPES, which drives the
+card icons: it omits the icon-only variants <code>visa_white</code> / <code>eftpos_white</code>, and the <code>laser</code> / <code>maestro</code>
+identifiers the widget can never resolve — allowing those would be configuration that can never match.</p>
+</dd>
 </dl>
 
 ## Typedefs
@@ -2203,6 +2280,15 @@ button.turnOffBackdrop();
 | FINISH | <code>string</code> | <code>&quot;finish&quot;</code> | 
 | CLOSE | <code>string</code> | <code>&quot;close&quot;</code> | 
 
+<a name="cb_CARD_SCHEME" id="cb_CARD_SCHEME" href="#user-content-cb_CARD_SCHEME">&nbsp;</a>
+
+## CARD\_SCHEME
+Card schemes the widget is able to resolve from a card number, and therefore the only values
+`setAllowedCardSchemes` accepts. This is a separate vocabulary from SUPPORTED_CARD_TYPES, which drives the
+card icons: it omits the icon-only variants `visa_white` / `eftpos_white`, and the `laser` / `maestro`
+identifiers the widget can never resolve — allowing those would be configuration that can never match.
+
+**Kind**: global constant  
 <a name="cb_listener" id="cb_listener" href="#user-content-cb_listener">&nbsp;</a>
 
 ## listener : <code>function</code>
@@ -2459,7 +2545,13 @@ After you initialized the standalone 3ds charge via `v1/charges/standalone-3ds`
                 console.log(data);
             });
             canvas3ds.on("chargeAuthChallenge", function (data) {
-                console.log(data);
+                console.log(data); // keep your loader up — the challenge page is still loading
+            });
+            canvas3ds.on("chargeAuthChallengeLoaded", function (data) {
+                console.log(data.reason); // 'load' | 'timeout' — hide your loader, the challenge is visible
+            });
+            canvas3ds.on("chargeAuthChallengeCompleted", function (data) {
+                console.log(data.source); // 'poll' | 'callback' — shopper finished, cover the challenge with "Completing verification"
             });
             canvas3ds.on("chargeAuthDecoupled", function (data) {
                 console.log(data.result.description);
@@ -2482,10 +2574,26 @@ After you initialized the standalone 3ds charge via `v1/charges/standalone-3ds`
   - A `data.status` of `rejected` will be received when the authorization was rejected.
   - A `data.status` of `invalid_event` will be received for unhandled situations.
 - The `chargeAuthChallenge` event is sent before starting a challenge flow (i.e. opening an IFrame for the customer to complete a challenge with ther bank). Once the end customer performs the challenge, the Canvas3ds will be able to identify the challenge result and will either produce a `chargeAuthSuccess` or `chargeAuthReject` event.
+- The `chargeAuthChallengeLoaded` event (SDK **v1.147.0+**) is sent once per challenge, after `chargeAuthChallenge`, when the challenge IFrame has finished loading the bank's page (its first `load` event) — this is the moment the customer can actually see the challenge. `data.reason` is `load` for a real load, or `timeout` when no load was observed within 2.5 seconds: the event is emitted anyway so you never hold a loading indicator forever (a `load` arriving later is simply ignored). Hide your loader on this event either way; `data.reason` is only informational (e.g. analytics). Not sent for decoupled challenges (no challenge IFrame).
+- The `chargeAuthChallengeCompleted` event (SDK **v1.147.0+**) is sent once the customer has finished the challenge (or approved a decoupled authentication): the bank has delivered the final result to the 3DS server and the Canvas3ds is now obtaining the outcome. Whatever the bank or the 3DS server render inside the IFrame from here on is plumbing, not UX — cover the IFrame with your own "Completing verification" state and hold it until the terminal event. `data.source` tells you how the SDK learned about it: `poll` (the 3DS server's result monitor — the usual case, it flips before the IFrame has even left the bank's page) or `callback` (the callback message carrying the outcome arrived first; the terminal event follows immediately) — handle both the same way. Sent at most once per authentication, always before `chargeAuthSuccess` / `chargeAuthReject` / `error` and never after them. A wrong OTP or a further interactive step (e.g. a second OTP screen) does **not** send it — no result has been delivered yet — so no grace timer or reveal fallback is needed on your side. Also sent for decoupled challenges.
 - The `chargeAuthDecoupled` event is sent when the flow is a decoupled challenge, alongside a `data.result.description` field that you must show to the customer, indicating the method the user must use to authenticate. For example this may happen by having the cardholder authenticating directly with their banking app through biometrics. Once the end customer does this, the Canvas3ds will be able to recognize the challenge result is ready and will either produce a `chargeAuthSuccess` or `chargeAuthReject` event.
 - The `error` event is sent if an unexpected issue with the client library occurs. In such scenarios, you should consider the autentication process as interrupted:
   - When getting this event, you will get on `data.error` the full error object.
 
+### Recommended loading indicator pattern
+
+> Requires SDK **v1.147.0 or later** (`chargeAuthChallengeLoaded` / `chargeAuthChallengeCompleted`). On older versions the same effect needs a `MutationObserver` on the container plus `load` listeners on the challenge IFrame — see the Standalone 3DS UX guide in the playground for that legacy approach.
+
+The Canvas3ds renders nothing visible until a challenge is presented, and `chargeAuthChallenge` fires when the API responds — about 1–2 seconds before the bank's page actually paints inside the IFrame. Drive a single loading indicator from the events:
+
+1. Show the loader **before** you `POST /v1/charges/standalone-3ds` and keep it up through `canvas3ds.load()` (fingerprinting and processing are invisible).
+2. Keep it up on `chargeAuthChallenge` — the challenge IFrame is being injected but is still blank.
+3. Hide it on `chargeAuthChallengeLoaded` — the challenge is visible. `data.reason` tells you whether it was a real paint (`load`) or the 2.5 s safety fallback (`timeout`); either way, no further handling is needed.
+4. Cover the IFrame with a "Completing verification" indicator on `chargeAuthChallengeCompleted` — the customer finished the challenge and the SDK is obtaining the outcome — and hold it until the terminal event. No grace timer or reveal fallback is needed: a wrong OTP or a second interactive step does not fire this event.
+5. Finish on `chargeAuthSuccess` / `chargeAuthReject` / `error`.
+
+Decoupled challenges (`chargeAuthDecoupled`) never emit `chargeAuthChallengeLoaded` (there is no challenge IFrame) but do emit `chargeAuthChallengeCompleted` once the customer approved out-of-band: show a dedicated waiting state with `data.result.description` until then, and "Completing verification" until the terminal event. Frictionless flows go straight from `load()` to the terminal event.
+
 ### Events and Values
 
 | Event Value         | Type                | Description                                                    |
@@ -2493,6 +2601,8 @@ After you initialized the standalone 3ds charge via `v1/charges/standalone-3ds`
 | <code>chargeAuthSuccess</code> | <code>object</code> | Instance of [ChargeEventResponse](#cb_chargeEventResponse) |
 | <code>chargeAuthReject</code> | <code>object</code> | Instance of [ChargeEventResponse](#cb_chargeEventResponse) |
 | <code>chargeAuthChallenge</code> | <code>object</code> | Instance of [ChargeEventResponse](#cb_chargeEventResponse) |
+| <code>chargeAuthChallengeLoaded</code> | <code>object</code> | Instance of [ChallengeLoadedResponse](#cb_challengeLoadedResponse) |
+| <code>chargeAuthChallengeCompleted</code> | <code>object</code> | Instance of [ChallengeCompletedResponse](#cb_challengeCompletedResponse) |
 | <code>chargeAuthDecoupled</code> | <code>object</code> | Instance of [ChargeEventResponse](#cb_chargeEventResponse) |
 | <code>chargeAuthInfo</code> | <code>object</code> | Instance of [ChargeEventResponse](#cb_chargeEventResponse) |
 | <code>error</code> | <code>object</code> | Instance of [chargeError](#cb_chargeError) |
@@ -2510,6 +2620,24 @@ After you initialized the standalone 3ds charge via `v1/charges/standalone-3ds`
 | <code>info</code> | <code>string</code> | info field for `chargeAuthInfo` event |
 | <code>result.description</code> | <code>string</code> [Optional] | field that you must show to the customer, indicating the method the user must use to authenticate during the decoupled challenge flow. |
 
+<a name="cb_challengeLoadedResponse" id="cb_challengeLoadedResponse"></a>
+
+### ChallengeLoadedResponse
+
+| Param                           | Type                           | Description                                                                                        |
+| ------------------------------- | ------------------------------ | -------------------------------------------------------------------------------------------------- |
+| <code>charge_3ds_id</code> | <code>string</code> | Universal unique transaction identifier to identify the transaction |
+| <code>reason</code> | <code>string</code> | `load` — the challenge IFrame fired its first load event; `timeout` — no load within 2.5 s, emitted so a loader is never held forever (a later load is ignored) |
+
+<a name="cb_challengeCompletedResponse" id="cb_challengeCompletedResponse"></a>
+
+### ChallengeCompletedResponse
+
+| Param                           | Type                           | Description                                                                                        |
+| ------------------------------- | ------------------------------ | -------------------------------------------------------------------------------------------------- |
+| <code>charge_3ds_id</code> | <code>string</code> | Universal unique transaction identifier to identify the transaction |
+| <code>source</code> | <code>string</code> | `poll` — the 3DS server's result monitor reported that the bank delivered the result (the usual case); `callback` — the callback message carrying the outcome arrived first (the terminal event follows immediately). Informational only — handle both the same way |
+
 ### ChargeError
 
 <a name="cb_chargeError" id="cb_chargeError"></a>