@paydock/client-sdk 1.126.0-beta → 1.127.1-beta

package/docs/api-widget.md

@@ -2539,4 +2539,5 @@ List of available triggers
 | REFRESH_CHECKOUT | <code>string</code> | <code>&quot;refresh_checkout&quot;</code> | 
 | UPDATE_FORM_VALUES | <code>string</code> | <code>&quot;update_form_values&quot;</code> | 
 | INIT_CHECKOUT | <code>string</code> | <code>&quot;init_checkout&quot;</code> | 
+| INJECT_CUSTOMER_DATA | <code>string</code> | <code>&quot;inject_customer_data&quot;</code> | 
 

package/docs/click-to-pay-examples.md

@@ -229,3 +229,112 @@ src.setStyles({
     font_family: 'Arial',
 });
 ```
+
+## Configurations for background loading and improved User Load times
+
+### hold_for_customer_data
+When set to `true`, this flag allows you to load the Click to Pay iframe in the background while collecting customer information. This improves the perceived performance by starting the iframe load process early.
+
+```javascript
+const clickToPay = new cba.ClickToPay("#checkoutIframe", SERVICE_ID, PUBLIC_KEY, {
+  hold_for_customer_data: true,
+  dpa_config: {
+    dpa_id: DPA_ID,
+    // ... other config
+  }
+});
+```
+
+### injectCustomerData(customer)
+Once you have collected the customer information, use this method to provide it to the Click to Pay iframe. This will trigger the checkout to continue.
+
+```javascript
+clickToPay.injectCustomerData({
+  email: "customer@example.com",
+  first_name: "John",
+  last_name: "Doe",
+  phone: "+61400123456"  // Include country code
+});
+```
+
+### Background Loading Example
+Here's a complete example showing how to implement background loading while collecting customer information:
+
+```javascript
+// 1. Initialize with hold_for_customer_data
+const clickToPay = new cba.ClickToPay("#checkoutIframe", SERVICE_ID, PUBLIC_KEY, {
+  hold_for_customer_data: true,
+  dpa_config: {
+    dpa_id: DPA_ID,
+    // ... other config
+  }
+});
+
+// Hide checkout and show form initially
+document.getElementById("checkoutIframe").style.display = 'none';
+document.getElementById("customerForm").style.display = 'block';
+document.getElementById("loader").style.display = 'none';
+
+// 2. Setup event handlers
+clickToPay.on('iframeLoaded', () => {
+  // Iframe is now loaded
+});
+
+clickToPay.on('checkoutReady', () => {
+  // Hide loader, show checkout
+  document.getElementById("loader").style.display = 'none';
+  document.getElementById("checkoutIframe").style.display = 'block';
+  clickToPay.showCheckout();
+});
+
+// 3. Start loading in background
+clickToPay.load();
+
+// 4. Handle form submission
+document.getElementById("submitButton").addEventListener("click", (e) => {
+  e.preventDefault();
+
+  const customer = {
+    email: document.getElementById("email").value.trim(),
+    first_name: document.getElementById("firstName").value.trim(),
+    last_name: document.getElementById("lastName").value.trim(),
+    phone: document.getElementById("phone").value.trim()
+  };
+
+  // Hide form, show loader
+  document.getElementById("customerForm").style.display = "none";
+  document.getElementById("loader").style.display = "flex";
+
+  try {
+    // Inject customer data to continue checkout
+    clickToPay.injectCustomerData(customer);
+  } catch (error) {
+    // Show form again on error
+    document.getElementById("customerForm").style.display = "block";
+    document.getElementById("loader").style.display = "none";
+    alert("An error occurred. Please try again.");
+  }
+});
+```
+
+#### HTML Structure
+Here's the required HTML structure for the background loading example:
+
+```html
+<!-- Click to Pay iframe container -->
+<div id="checkoutIframe"></div>
+
+<!-- Customer information form -->
+<form id="customerForm">
+  <input type="email" id="email" placeholder="Email" required>
+  <input type="text" id="firstName" placeholder="First Name" required>
+  <input type="text" id="lastName" placeholder="Last Name" required>
+  <input type="tel" id="phone" placeholder="Phone (with country code)" required>
+  <button type="submit" id="submitButton">Continue to Checkout</button>
+</form>
+
+<!-- Loading indicator -->
+<div id="loader" style="display: none;">
+  Loading...
+</div>
+```

package/docs/click-to-pay.md

@@ -53,7 +53,7 @@ Interface of data used for the Mastercard Checkout. For further information refe
 | [checkout_experience] | <code>string</code> | Checkout experience type, either 'WITHIN_CHECKOUT' or 'PAYMENT_SETTINGS'. |
 | [services] | <code>string</code> | Services offered, such as 'INLINE_CHECKOUT' or 'INLINE_INSTALLMENTS'. |
 | [dpa_transaction_options] | <code>object</code> | Object that stores options for creating a transaction with DPA. |
-| [dpa_transaction_options.dpa_locale] | <code>string</code> | DPA’s preferred locale, example en_US. |
+| [dpa_transaction_options.dpa_locale] | <code>string</code> | DPA's preferred locale, example en_US. |
 | [dpa_transaction_options.dpa_accepted_billing_countries] | <code>Array.&lt;string&gt;</code> | List of accepted billing countries for DPA in ISO 3166-1 alpha-2 format. |
 | [dpa_transaction_options.dpa_billing_preference] | <code>string</code> | Billing preferences for DPA, options are 'FULL', 'POSTAL_COUNTRY', 'NONE'. |
 | [dpa_transaction_options.payment_options] | <code>Array.&lt;object&gt;</code> | Payment options included in the transaction. |
@@ -78,6 +78,12 @@ Interface of data used for the Mastercard Checkout. For further information refe
 | [customer.phone.country_code] | <code>string</code> | Customer phone country code (example "1" for US). |
 | [customer.phone.phone] | <code>string</code> | Customer phone number. |
 | [unaccepted_card_type] | <code>string</code> | Used to block a specific card type. Options are 'CREDIT', 'DEBIT'. |
+| [dpa_config] | <code>object</code> | Raw DPA configuration object for performance optimization. Skips API call when provided. |
+| [dpa_config.dpa_id] | <code>string</code> | DPA identifier. |
+| [dpa_config.dpa_name] | <code>string</code> | DPA name. |
+| [dpa_config.dpa_supported_card_schemes] | <code>Array.&lt;string&gt;</code> | List of supported card schemes: 'MASTERCARD', 'VISA', 'AMEX', 'DISCOVER'. |
+| [dpa_config.mode] | <code>string</code> | DPA mode, either 'sandbox' or 'live'. |
+| [hold_for_customer_data] | <code>boolean</code> | Flag to hold initialization for customer data injection. Enables background initialization. |
 
 <a name="EventData" id="EventData" href="#EventData">&nbsp;</a>
 
@@ -152,6 +158,7 @@ Class ClickToPay include methods for interacting with the ClickToPay checkout an
 * [ClickToPay](#ClickToPay) ⇐ <code>SRC</code>
     * [new ClickToPay(iframe_selector, service_id, public_key_or_access_token, meta)](#new_ClickToPay_new)
     * [.load()](#ClickToPay+load)
+    * [.injectCustomerData(customerData)](#ClickToPay+injectCustomerData)
     * [.setStyles(fields)](#SRC+setStyles)
     * [.setEnv(env, [alias])](#SRC+setEnv)
     * [.getEnv()](#SRC+getEnv)
@@ -182,6 +189,29 @@ var mastercardSRC = new ClickToPay('#checkoutIframe', 'service_id', 'public_key'
 The final method after configuring the SRC to start the load process of Click To Pay checkout
 
 **Kind**: instance method of [<code>ClickToPay</code>](#ClickToPay)  
+<a name="ClickToPay+injectCustomerData" id="ClickToPay+injectCustomerData" href="#ClickToPay+injectCustomerData">&nbsp;</a>
+
+### clickToPay.injectCustomerData(customerData)
+Inject customer data after widget initialization via postMessage
+
+**Kind**: instance method of [<code>ClickToPay</code>](#ClickToPay)  
+**Throws**:
+
+- <code>Error</code> When customer data is invalid or widget is not ready
+
+
+| Param | Type | Description |
+| --- | --- | --- |
+| customerData | <code>Customer</code> | Customer data to inject |
+
+**Example**  
+```js
+widget.injectCustomerData({
+    email: 'user@example.com',
+    first_name: 'John',
+    last_name: 'Doe'
+});
+```
 <a name="SRC+setStyles" id="SRC+setStyles" href="#SRC+setStyles">&nbsp;</a>
 
 ### clickToPay.setStyles(fields)

package/package.json

@@ -104,7 +104,7 @@
     }
   },
   "name": "@paydock/client-sdk",
-  "version": "1.126.0-beta",
+  "version": "1.127.1-beta",
   "scripts": {
     "build:doc": "node docs/html/marked.js",
     "build:js": "rollup --config rollup.config.ts --configPlugin @rollup/plugin-typescript",

package/slate.md

@@ -2062,6 +2062,115 @@ src.setStyles({
 });
 ```
 
+## Configurations for background loading and improved User Load times
+
+### hold_for_customer_data
+When set to `true`, this flag allows you to load the Click to Pay iframe in the background while collecting customer information. This improves the perceived performance by starting the iframe load process early.
+
+```javascript
+const clickToPay = new cba.ClickToPay("#checkoutIframe", SERVICE_ID, PUBLIC_KEY, {
+  hold_for_customer_data: true,
+  dpa_config: {
+    dpa_id: DPA_ID,
+    // ... other config
+  }
+});
+```
+
+### injectCustomerData(customer)
+Once you have collected the customer information, use this method to provide it to the Click to Pay iframe. This will trigger the checkout to continue.
+
+```javascript
+clickToPay.injectCustomerData({
+  email: "customer@example.com",
+  first_name: "John",
+  last_name: "Doe",
+  phone: "+61400123456"  // Include country code
+});
+```
+
+### Background Loading Example
+Here's a complete example showing how to implement background loading while collecting customer information:
+
+```javascript
+// 1. Initialize with hold_for_customer_data
+const clickToPay = new cba.ClickToPay("#checkoutIframe", SERVICE_ID, PUBLIC_KEY, {
+  hold_for_customer_data: true,
+  dpa_config: {
+    dpa_id: DPA_ID,
+    // ... other config
+  }
+});
+
+// Hide checkout and show form initially
+document.getElementById("checkoutIframe").style.display = 'none';
+document.getElementById("customerForm").style.display = 'block';
+document.getElementById("loader").style.display = 'none';
+
+// 2. Setup event handlers
+clickToPay.on('iframeLoaded', () => {
+  // Iframe is now loaded
+});
+
+clickToPay.on('checkoutReady', () => {
+  // Hide loader, show checkout
+  document.getElementById("loader").style.display = 'none';
+  document.getElementById("checkoutIframe").style.display = 'block';
+  clickToPay.showCheckout();
+});
+
+// 3. Start loading in background
+clickToPay.load();
+
+// 4. Handle form submission
+document.getElementById("submitButton").addEventListener("click", (e) => {
+  e.preventDefault();
+
+  const customer = {
+    email: document.getElementById("email").value.trim(),
+    first_name: document.getElementById("firstName").value.trim(),
+    last_name: document.getElementById("lastName").value.trim(),
+    phone: document.getElementById("phone").value.trim()
+  };
+
+  // Hide form, show loader
+  document.getElementById("customerForm").style.display = "none";
+  document.getElementById("loader").style.display = "flex";
+
+  try {
+    // Inject customer data to continue checkout
+    clickToPay.injectCustomerData(customer);
+  } catch (error) {
+    // Show form again on error
+    document.getElementById("customerForm").style.display = "block";
+    document.getElementById("loader").style.display = "none";
+    alert("An error occurred. Please try again.");
+  }
+});
+```
+
+#### HTML Structure
+Here's the required HTML structure for the background loading example:
+
+```html
+<!-- Click to Pay iframe container -->
+<div id="checkoutIframe"></div>
+
+<!-- Customer information form -->
+<form id="customerForm">
+  <input type="email" id="email" placeholder="Email" required>
+  <input type="text" id="firstName" placeholder="First Name" required>
+  <input type="text" id="lastName" placeholder="Last Name" required>
+  <input type="tel" id="phone" placeholder="Phone (with country code)" required>
+  <button type="submit" id="submitButton">Continue to Checkout</button>
+</form>
+
+<!-- Loading indicator -->
+<div id="loader" style="display: none;">
+  Loading...
+</div>
+```
+
 # Fraud prevention
 
 The Fraud Prevention module allows you to add security layers to your payment workflows