npm - @paydock/client-sdk - Versions diffs - 1.128.2 → 1.131.0 - Mend

@paydock/client-sdk 1.128.2 → 1.131.0

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.

Files changed (246) hide show

package/README.md CHANGED Viewed

@@ -3628,6 +3628,7 @@ List of available event's name in the wallet button lifecycle
 | PAYMENT_SUCCESSFUL | <code>string</code> | <code>&quot;paymentSuccessful&quot;</code> |
 | PAYMENT_ERROR | <code>string</code> | <code>&quot;paymentError&quot;</code> |
 | ON_CLICK | <code>string</code> | <code>&quot;onClick&quot;</code> |
+| LOADED | <code>string</code> | <code>&quot;onWalletLoaded&quot;</code> |
 ## Express Wallet Buttons
@@ -3737,6 +3738,534 @@ A full description of the meta parameters for [ApplePayWalletButtonExpress](#App
 </html>
 ```
+### Apple Pay Wallet Button Express with Shipping
+A full description of the meta parameters for [ApplePayWalletButtonExpress](#ApplePayWalletButtonExpress) meta parameters can be found [here](#ApplePayWalletMeta). Below you will find a fully working html example.
+```html
+<html>
+<head>
+    <title>Apple Pay Express test page</title>
+    <style>
+        #inputModal {
+            display: none;
+            position: fixed;
+            left: 0;
+            top: 0;
+            width: 100%;
+            height: 100%;
+            background-color: rgba(0,0,0,0.5);
+            z-index: 1000;
+        }
+        #inputBox {
+            position: absolute;
+            left: 50%;
+            top: 50%;
+            transform: translate(-50%, -50%);
+            padding: 20px;
+            background: white;
+            border-radius: 5px;
+            box-shadow: 2px 2px 10px rgba(0,0,0,0.5);
+        }
+    </style>
+</head>
+<body>
+    <table id='paymentTable'>
+        <tr>
+            <td>Environment:</td>
+            <td>
+                <select id="environment" name="environment">
+                    <option value="sandbox">Sandbox</option>
+                    <option value="local">Local</option>
+                </select>
+            </td>
+        </tr>
+        <tr>
+            <td>Access Token / Public Key:</td>
+            <td><input type="text" name="access" id="access" /></td>
+        </tr>
+        <tr>
+            <td>Secret Key:</td>
+            <td><input type="text" name="secretKey" id="secretKey" /></td>
+        </tr>
+        <tr>
+            <td>Gateway Id:</td>
+            <td><input type="text" name="gateway" id="gateway" /></td>
+        </tr>
+        <tr>
+            <td>Wallet Charge - for apple pay we need to add it here because the apple pay popup does not allow us to
+                inject it there but it will be used only on click. So is optional, if not provided it simulates an error
+                when creating B2B wallet charge on click:</td>
+            <td><input type="text" name="token" id="token" /></td>
+        </tr>
+        <tr>
+            <td>Charge id - Used to update the charge with the shipping data/shipping options</td>
+            <td><input type="text" name="chargeId" id="chargeId" /></td>
+        </tr>
+        <tr>
+            <td>Meta:</td>
+            <td><textarea id="meta" name="meta" rows="4" cols="50"></textarea></td>
+        </tr>
+    </table>
+    <div id="button">
+        <input type="submit" name="event" value="Send" class="button" onclick="return loadButtons()" />
+    </div>
+    <div id="widget"></div>
+</body>
+<script src="https://widget.paydock.com/sdk/latest/widget.umd.min.js"></script>
+<script type=text/javascript>
+    // Environment enum with API URLs
+    const ENVIRONMENTS = {
+        PRODUCTION: {
+            name: 'production',
+            apiUrl: 'https://api.paydock.com'
+        },
+        SANDBOX: {
+            name: 'sandbox',
+            apiUrl: 'https://api-sandox.paydock.com'
+        }
+    };
+    // Function to get API URL based on selected environment
+    function getApiUrl(environmentName) {
+        const env = Object.values(ENVIRONMENTS).find(env => env.name === environmentName);
+        return env ? env.apiUrl : ENVIRONMENTS.SANDBOX.apiUrl;
+    }
+    // Function to get current base URL from selected environment
+    function getBaseUrl() {
+        const selectedEnvironment = document.getElementById("environment").value;
+        return getApiUrl(selectedEnvironment);
+    }
+    async function updateCharge(secretKey, chargeId, updateData) {
+        try {
+            const baseUrl = getBaseUrl();
+            const response = await fetch(`${baseUrl}/v1/charges/wallet/${chargeId}`, {
+                method: 'PUT',
+                headers: {
+                    'x-user-secret-key': secretKey,
+                    'Content-Type': 'application/json',
+                },
+                body: JSON.stringify(updateData),
+            });
+            const data = await response.json();
+            console.log('Update charge response:', data);
+            return data;
+        } catch (error) {
+            console.error('Error updating charge:', error);
+        }
+    };
+    const shippingOptions = [
+            {
+                label: "Test 1",
+                detail: "This is a test 1 shipping methods",
+                amount: 10,
+                id: "randomId1",
+                date_components_range: {
+                    start_date_components: {
+                        years: 0,
+                        months: 0,
+                        days: 5,
+                        hours: 0,
+                    },
+                    end_date_components: {
+                        years: 0,
+                        months: 0,
+                        days: 10,
+                        hours: 0,
+                    }
+                }
+            },
+            {
+                label: "Test 2",
+                detail: "This is a test 2 shipping methods",
+                amount: 14,
+                id: "randomId2",
+                date_components_range: {
+                    start_date_components: {
+                        years: 0,
+                        months: 0,
+                        days: 6,
+                        hours: 0,
+                    },
+                    end_date_components: {
+                        years: 0,
+                        months: 0,
+                        days: 12,
+                        hours: 0,
+                    },
+                },
+            },
+        ];
+    function loadButtons() {
+        const secretKey = document.getElementById("secretKey").value;
+        if (!secretKey) {
+            alert("Please enter the secret key.");
+            return false;
+        }
+        let button = new paydock.ApplePayWalletButtonExpress(
+            "#widget",
+            document.getElementById("access").value,
+            document.getElementById("gateway").value,
+            JSON.parse(document.getElementById("meta").value),
+        );
+        button.setEnv(document.getElementById("environment").value);
+        let charge_id;
+        button.onClick(async (data) => {
+            const { token, chargeId } = await getUserInput();
+            charge_id = chargeId;
+            return token;
+        });
+        const amount = JSON.parse(document.getElementById('meta').value).amount;
+        button.onUnavailable(function() {
+            console.log("Button unavailable");
+        });
+        button.onError(function(error) {
+            console.log("On Error Callback", error);
+        });
+        button.onPaymentSuccessful(function(data) {
+            console.log("Payment successful");
+            console.log(data);
+        });
+        button.onPaymentError(function(err) {
+            console.log("Payment error");
+            console.log(err);
+        });
+        button.onPaymentInReview(function(data) {
+            console.log("The payment is on fraud review");
+            console.log(data);
+        });
+        button.onCheckoutClose(() => {
+            console.log("Checkout closed");
+        });
+        button.onShippingAddressChange(async function(data) {
+            console.log("Shipping address has been updated", data);
+            const defaultOption = shippingOptions[0];
+            const updateData = {
+                shipping: {
+                    ...data.data,
+                    amount: defaultOption.amount,
+                    method: defaultOption.id,
+                    options: shippingOptions,
+                },
+                amount: amount + defaultOption.amount
+            };
+            const res = await updateCharge(secretKey, charge_id, updateData);
+            return { token: res.resource.data.token };
+        });
+        button.onShippingOptionsChange(async function(data) {
+            console.log("Shipping options have been updated", JSON.stringify(data, null, 2));
+            const updateData = {
+                shipping: {
+                    method: data.data.shipping_option_id,
+                    amount: data.data.amount,
+                },
+                amount: amount + Number(data.data.amount)
+            };
+            const res = await updateCharge(secretKey, charge_id, updateData);
+            return { token: res.resource.data.token };
+        });
+        button.load()
+        document.getElementById("paymentTable").style.display = "none";
+        document.getElementById("button").style.display = "none";
+        return true;
+    }
+    function getUserInput(message) {
+        return new Promise((resolve, reject) => {
+            console.log("Simulating B2B call to generate token...");
+            setTimeout(() => {
+                const token = document.getElementById("token").value;
+                const chargeId = document.getElementById("chargeId").value;
+                if (token && chargeId)
+                    return resolve({ token, chargeId });
+                return reject("No token or Charge Id provided");
+            }, 2000);
+        });
+    }
+    document.addEventListener('DOMContentLoaded', () => {
+        // Function to get the value of a query parameter by name
+        function getQueryParam(name) {
+            const urlParams = new URLSearchParams(window.location.search);
+            return urlParams.get(name);
+        }
+        // Function to set input values from URL parameters
+        function setInputValues() {
+            const meta = {
+                apple_pay_capabilities: ['credentials_available', 'credentials_status_unknown', 'credentials_unavailable'],
+                amount_label: 'TOTAL',
+                country: 'AU',
+                currency: 'AUD',
+                amount: 10,
+                shipping_editing_mode: 'available', // available, store_pickup
+                required_shipping_contact_fields: [
+                    'postalAddress',
+                    'name',
+                    'phone',
+                    'email',
+                ],
+                shipping: {
+                    amount: 5,
+                    address_line1: "Address Line 1",
+                    address_city: "Test Locality",
+                    address_state: "NSW",
+                    address_country: "Australia",
+                    address_country_code: "AU",
+                    address_postcode: "3000",
+                    contact: {
+                        phone: "+61400245562",
+                        email: "qa.notifications+appleid@paydock.com",
+                        first_name: "QA",
+                        last_name: "QA",
+                    },
+                    options: shippingOptions,
+                },
+                // merchant_capabilities: ['supports3DS', 'supportsEMV', 'supportsCredit', 'supportsDebit'],
+                // supported_networks: ['visa', 'masterCard', 'amex', 'chinaUnionPay', 'discover', 'interac', 'jcb', 'privateLabel'],
+                // required_billing_contact_fields: ['email', 'name', 'phone', 'postalAddress', 'phoneticName'],
+                // required_shipping_contact_fields: ['email', 'phone' /*, 'name', 'postalAddress', 'phoneticName'*/],
+                // supported_countries: [],
+                // style: {
+                //     button_type: 'continue',
+                //     button_style: 'white',
+                // },
+            };
+            document.getElementById('meta').value = JSON.stringify(meta, null, 2);
+        }
+        setInputValues();
+    });
+</script>
+</html>
+```
+When supporting shipping, the method `onShippingAddressChange` and `onShippingOptionsChange` are required to update the shipping address and options.
+```javascript
+button.onShippingAddressChange(async function(data) {
+    console.log("Shipping address has been updated", data);
+    const updateData = {
+        shipping: {
+            ...data.data,
+            amount: defaultOption.amount,
+            method: defaultOption.id,
+            options: shippingOptions,
+        },
+        amount: amount + defaultOption.amount
+    };
+    const res = await updateCharge(secretKey, charge_id, updateData);
+    return { token: res.resource.data.token };
+});
+button.onShippingOptionsChange(async function(data) {
+    console.log("Shipping options have been updated", data);
+    const updateData = {
+        shipping: {
+            method: data.data.shipping_option_id,
+            amount: data.data.amount,
+        },
+        amount: amount + Number(data.data.amount)
+    };
+    const res = await updateCharge(secretKey, charge_id, updateData);
+    return { token: res.resource.data.token };
+});
+```
+The `updateCharge` method is a custom method to update the charge with the shipping data/shipping options. It is not part of the Paydock SDK and it should use the Paydock's public API to update the charge from the merchant's server.
+### Supported Cases
+#### Injected Shipping Address, non-editable by the customer
+This is the case where the shipping address is injected by the merchant and is not editable by the customer. The customer can only select the shipping option.
+The required meta parameters for this case are:
+- shipping_editing_mode: 'store_pickup'
+- required_shipping_contact_fields: ['postalAddress'] <-- At least one of the fields is required so the shipping address is shown at Apple Pay.
+```javascript
+meta: {
+    apple_pay_capabilities: ['credentials_available', 'credentials_status_unknown', 'credentials_unavailable'],
+    amount_label: 'TOTAL',
+    country: 'AU',
+    currency: 'AUD',
+    amount: 10,
+    shipping_editing_mode: 'store_pickup',
+    required_shipping_contact_fields: [
+        'postalAddress', // At least one of the fields is required so the shipping address is shown at Apple Pay.
+        'name',
+        'phone',
+        'email',
+    ],
+    shipping: {
+        amount: 5,
+        address_line1: "Address Line 1",
+        address_city: "Test Locality",
+        address_state: "NSW",
+        address_country: "Australia",
+        address_country_code: "AU",
+        address_postcode: "3000",
+        contact: {
+            phone: "+61400245562",
+            email: "qa.notifications+appleid@paydock.com",
+            first_name: "QA",
+            last_name: "QA",
+        },
+        options: [
+            {
+                label: "Test 1",
+                detail: "This is a test 1 shipping methods",
+                amount: 10,
+                id: "randomId1",
+                date_components_range: {
+                    start_date_components: {
+                        years: 0,
+                        months: 0,
+                        days: 5,
+                        hours: 0,
+                    },
+                    end_date_components: {
+                        years: 0,
+                        months: 0,
+                        days: 10,
+                        hours: 0,
+                    }
+                }
+            }
+        ],
+    },
+}
+```
+This is the case where the shipping address is injected by the merchant and is editable by the customer. The customer can edit the shipping address and select the shipping option.
+The required meta parameters for this case are:
+- shipping_editing_mode: 'available'
+- required_shipping_contact_fields: ['postalAddress'] <-- At least one of the fields is required so the shipping address is shown at Apple Pay.
+```javascript
+meta: {
+    apple_pay_capabilities: ['credentials_available', 'credentials_status_unknown', 'credentials_unavailable'],
+    amount_label: 'TOTAL',
+    country: 'AU',
+    currency: 'AUD',
+    amount: 10,
+    shipping_editing_mode: 'available',
+    required_shipping_contact_fields: [
+        'postalAddress', // At least one of the fields is required so the shipping address is shown at Apple Pay.
+        'name',
+        'phone',
+        'email',
+    ],
+    shipping: {
+        amount: 5,
+        address_line1: "Address Line 1",
+        address_city: "Test Locality",
+        address_state: "NSW",
+        address_country: "Australia",
+        address_country_code: "AU",
+        address_postcode: "3000",
+        contact: {
+            phone: "+61400245562",
+            email: "qa.notifications+appleid@paydock.com",
+            first_name: "QA",
+            last_name: "QA",
+        },
+        options: [
+            {
+                label: "Test 1",
+                detail: "This is a test 1 shipping methods",
+                amount: 10,
+                id: "randomId1",
+                date_components_range: {
+                    start_date_components: {
+                        years: 0,
+                        months: 0,
+                        days: 5,
+                        hours: 0,
+                    },
+                    end_date_components: {
+                        years: 0,
+                        months: 0,
+                        days: 10,
+                        hours: 0,
+                    }
+                }
+            }
+        ],
+    },
+}
+```
+#### Shipping address editable by the customer
+This is the case where the shipping address is not injected by the merchant and is editable by the customer. The customer can edit the shipping address and select the shipping option.
+The required meta parameters for this case are:
+- shipping_editing_mode: 'available'
+- required_shipping_contact_fields: ['postalAddress'] <-- At least one of the fields is required so the shipping address is shown at Apple Pay.
+```javascript
+meta: {
+    apple_pay_capabilities: ['credentials_available', 'credentials_status_unknown', 'credentials_unavailable'],
+    amount_label: 'TOTAL',
+    country: 'AU',
+    currency: 'AUD',
+    amount: 10,
+    shipping_editing_mode: 'available',
+    required_shipping_contact_fields: [
+        'postalAddress', // At least one of the fields is required so the shipping address is shown at Apple Pay.
+        'name',
+        'phone',
+        'email',
+    ],
+}
+```
+When the the customer selects an address, the `onShippingAddressChange` method is called with the shipping address data. If the merchant wants to update the charge with the shipping address, it should update the charge using Paydock's public API Update Charge method with the shipping address data.
+It can include the shipping options in the update data, that will be used to show the shipping options in the Apple Pay popup.
+```javascript
+button.onShippingAddressChange(async function(data) {
+    console.log("Shipping address has been updated", data);
+    const updateData = {
+        shipping: {
+            ...data.data,
+            amount: defaultOption.amount,
+            method: defaultOption.id,
+            options: shippingOptions,
+        },
+        amount: amount + defaultOption.amount
+    };
+});
+```
 ### Paypal Wallet Button Express
 A full description of the meta parameters for [PaypalWalletButtonExpress](#PaypalWalletButtonExpress) meta parameters can be found [here](#PaypalWalletMeta). Below you will find a fully working html example.