@paydock/client-sdk 1.144.1-beta → 1.147.0

package/slate.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');
@@ -743,7 +784,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);
@@ -766,10 +813,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                                                    |
@@ -777,6 +840,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) |
@@ -794,6 +859,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>
@@ -2147,6 +2230,106 @@ Bear in mind that you must set an environment before calling `button.load()`.
 button.setEnv('sandbox');
 ```
 
+### Checking availability before instantiation (static)
+
+`ApplePayOpenWalletButton.checkAvailability(options)` is a **static** method so you can decide
+whether to show an Apple Pay option — or which payment method to default to — **without
+instantiating the button** and waiting for the `onUnavailable` event.
+
+> **Apple Pay is no longer Safari-only.** Since iOS 16 (third-party mobile browsers) and the
+> iOS 18 / 2025 desktop rollout, Apple Pay also works in Chrome, Edge and Firefox — including
+> on Windows — via a **cross-device QR handoff**: the user scans a code and completes the
+> payment on their iPhone. Because the paying device is often *not* the browsing device, the
+> only authoritative availability signal is the async `checkAvailability()`.
+> `applePayCapabilities()` is what Apple recommends; `canMakePayments()` is just a coarse
+> local-device hint. See
+> [Apple — Checking for Apple Pay availability](https://developer.apple.com/documentation/applepayontheweb/checking-for-apple-pay-availability).
+
+#### `ApplePayOpenWalletButton.checkAvailability(options)`
+
+The single, authoritative, cross-browser-aware check. It resolves the merchant identifier,
+loads Apple's web SDK if needed, and queries `ApplePaySession.applePayCapabilities()`.
+
+You may supply the merchant context in either of two ways:
+
+```javascript
+// 1) Lightest path — no network — when you already know the Apple merchant identifier:
+const result = await paydock.ApplePayOpenWalletButton.checkAvailability({
+    merchant_id: 'merchant.com.example',
+});
+
+// 2) Resolve the merchant identifier from the service configuration (fetched & cached):
+const result = await paydock.ApplePayOpenWalletButton.checkAvailability({
+    public_key_or_access_token: publicKeyOrAccessToken,
+    service_id: serviceId,
+    env: 'sandbox',
+    // Optional — which device statuses count as "available".
+    // Defaults to ['credentials_available', 'credentials_status_unknown'].
+    apple_pay_capabilities: ['credentials_available', 'credentials_status_unknown'],
+});
+```
+
+**Result shape (`ApplePayAvailabilityResult`):**
+
+```javascript
+{
+    available: true,                  // verdict vs the allowed capability set
+    supported: true,                  // Apple Pay usable here AT ALL (incl. cross-device QR)
+    has_native_session: false,        // native same-device session present (canMakePayments)
+    payment_credential_status:        // OUTPUT — the device's reported status
+        'paymentCredentialStatusUnknown',
+    reason: undefined,                // set when not available, see below
+}
+```
+
+**Inferring the transport (Apple does not expose it directly):**
+- `available && has_native_session` ⇒ **native** Apple Pay sheet is likely (Safari on an Apple device).
+- `available && !has_native_session` ⇒ **cross-device / QR** handoff is likely (e.g. Chrome on desktop).
+
+`payment_credential_status` is the device's actual status:
+`'paymentCredentialsAvailable'`, `'paymentCredentialStatusUnknown'`,
+`'paymentCredentialsUnavailable'`, or `'applePayUnsupported'`. **Third-party / desktop
+browsers normally report `paymentCredentialStatusUnknown`** (Apple can't see the remote
+iPhone's cards until the user scans the QR), which is why the default allowed set includes it.
+
+The `apple_pay_capabilities` **input** maps to those statuses
+(`credentials_available` → `paymentCredentialsAvailable`,
+`credentials_status_unknown` → `paymentCredentialStatusUnknown`,
+`credentials_unavailable` → `paymentCredentialsUnavailable`) and decides which ones make
+`available` true. When omitted, **both** `paymentCredentialsAvailable` and
+`paymentCredentialStatusUnknown` count — narrow it to `['credentials_available']` only if you
+want to require a confirmed local card (this will hide the button in cross-browser/QR contexts).
+
+When `available` is `false`, `reason` is one of: `'unsupported_browser'`,
+`'missing_merchant_id'`, `'service_type_mismatch'`, `'config_fetch_failed'`,
+`'sdk_load_failed'`, `'query_failed'`, `'no_credentials'`, or `'no_native_session'`
+(only from the synchronous check below).
+
+```javascript
+const result = await paydock.ApplePayOpenWalletButton.checkAvailability({ merchant_id: merchantId });
+if (result.available) {
+    renderApplePayButton();
+} else {
+    console.log('Apple Pay unavailable:', result.reason, result.payment_credential_status);
+}
+```
+
+**Synchronous native-only fast check (`sync: true`).** Pass `{ sync: true }` for a cheap,
+network-free pre-check that resolves immediately — it runs only the native same-device check
+(`window.ApplePaySession` + `canMakePayments()`), with no merchant resolution, SDK load, or
+`applePayCapabilities()` query. In this mode `available` reflects the native session only and
+`payment_credential_status` is `undefined`. It is a Safari-oriented hint and is **not**
+authoritative for cross-browser / QR availability (which require the full async check above).
+
+```javascript
+const { has_native_session } = await paydock.ApplePayOpenWalletButton.checkAvailability({
+    sync: true,
+});
+if (has_native_session) {
+    // Native Apple Pay is ready on this device (Safari fast path).
+}
+```
+
 ### Full Apple Pay example
 
 ```html
@@ -2565,6 +2748,58 @@ The GooglePayOpenWalletButton constructor accepts the following parameters:
 
 > **Note:** Required meta fields (`amount`, `currency`, `country`) are validated automatically by the `GooglePayOpenWalletButton` class. You do not need to specify them manually.
 
+### Checking availability before instantiation (static)
+
+`GooglePayOpenWalletButton.checkAvailability(options)` is a **static** method that reports
+whether Google Pay can be used in the current context **without instantiating the button**.
+It loads the Google Pay JS SDK if needed and runs `PaymentsClient.isReadyToPay()`.
+
+Unlike Apple Pay, **all options are optional** — Google Pay's readiness check does not
+require a merchant identifier. Supplying `publicKeyOrAccessToken` + `serviceId` additionally
+validates that the service is a Google Pay service (and resolves the merchant id).
+
+```javascript
+// Simplest form — no merchant context needed:
+const result = await paydock.GooglePayOpenWalletButton.checkAvailability();
+
+// Or validate the service is a Google Pay service while checking:
+const result = await paydock.GooglePayOpenWalletButton.checkAvailability({
+    public_key_or_access_token: publicKeyOrAccessToken,
+    service_id: serviceId,
+    env: 'sandbox',
+});
+```
+
+**Result shape (`GooglePayAvailabilityResult`):**
+
+```javascript
+{
+    available: true,             // isReadyToPay().result — ready to pay in this context
+    supported: true,             // the Google Pay JS API is present and the query ran
+    payment_method_present: true, // OUTPUT — whether the buyer already has a usable card
+    reason: undefined,           // set when not available, see below
+}
+```
+
+> **Note:** the static check uses the **default** card configuration (standard auth methods
+> and card networks). A button instance configured with a custom `card_config` may produce a
+> different result.
+
+When `available` is `false`, `reason` is one of: `'unsupported_browser'`,
+`'service_type_mismatch'`, `'config_fetch_failed'`, `'sdk_load_failed'`, `'query_failed'`,
+`'no_payment_method'`, or `'api_not_loaded'` (only from the synchronous check below).
+
+**Synchronous fast check (`sync: true`).** Google Pay has no synchronous device/card
+capability API, so `{ sync: true }` only reports whether the Google Pay JS API is already
+present in the page — it does **not** run `isReadyToPay()`:
+
+```javascript
+const { available } = await paydock.GooglePayOpenWalletButton.checkAvailability({
+    sync: true,
+});
+// `available` here means "the Google Pay JS API script is loaded", not "ready to pay".
+```
+
 ### Full Google Pay Example
 
 ```html
@@ -2707,12 +2942,28 @@ Both `ApplePayOpenWalletButton` and `GooglePayOpenWalletButton` share the same e
 
 ### Checking for button availability
 
-If the customer's browser is not supported, or the customer does not have any card added to their wallet, the button will not load. In this case the callback onUnavailable() will be called. You can define the behavior of this function before loading the button.
+There are two ways to know whether a wallet is available:
+
+**1. After `load()` — the `onUnavailable()` callback.** If the customer's browser is not supported, or the customer does not have any card added to their wallet, the button will not load. In this case the callback onUnavailable() will be called. You can define the behavior of this function before loading the button.
 
 ```javascript
 button.onUnavailable(({ data }) => console.log("No wallet button available", data));
 ```
 
+**2. Before instantiation — the static `checkAvailability()` method.** Each button class exposes a static `checkAvailability(options)` that resolves availability **without instantiating the button**, so you can decide whether to render a wallet option (or which payment method to default to) up front. The options and result are wallet-specific — see [Apple Pay → Checking availability before instantiation](#checking-availability-before-instantiation-static) and [Google Pay → Checking availability before instantiation](#checking-availability-before-instantiation-static-1).
+
+```javascript
+// Apple Pay
+const apple = await paydock.ApplePayOpenWalletButton.checkAvailability({ merchant_id: merchantId });
+
+// Google Pay (merchant context optional)
+const google = await paydock.GooglePayOpenWalletButton.checkAvailability();
+
+if (apple.available || google.available) {
+    // Show a wallet payment option.
+}
+```
+
 ### Service type validation
 
 Each button validates that the service configuration matches its expected wallet type. If you use an Apple Pay service ID with `GooglePayOpenWalletButton` (or vice versa), an error will be emitted via `onError`:
@@ -2874,7 +3125,7 @@ A full description of the [ApplePayOpenWalletMeta](#ApplePayOpenWalletMeta) prop
 - `request_shipping?: boolean`: Enable shipping address collection
 - `shipping_options?: IApplePayShippingOption[]`: Array of shipping options
 - `show_billing_address?: boolean`: Show billing address fields
-- `apple_pay_capabilities?: string[]`: Device capabilities
+- `apple_pay_capabilities?: string[]`: Device credential statuses that make the button render. **Defaults to `['credentials_available', 'credentials_status_unknown']`**: `credentials_available` means the device has a confirmed Apple Pay card ready to use; `credentials_status_unknown` means a local card can't be confirmed but Apple Pay can still proceed (e.g. the cross-device QR flow used by Chrome, Edge and Firefox). Narrow to `['credentials_available']` to require a confirmed local card.
 - `merchant_capabilities?: string[]`: Merchant capabilities
 - `supported_networks?: string[]`: Supported payment networks
 - `required_billing_contact_fields?: string[]`: Required billing contact fields