@dintero/checkout-web-sdk 0.11.5 → 0.12.0

package/README.md

@@ -91,6 +91,13 @@ _The checkout sdk will add a polyfill for promises if the browser does not suppo
                     event.payment_product_type,
                 );
             },
+            onAddressCallback: function (event, checkout, callback) {
+                console.log("address callback to handle express session address updates", event.session);
+                callback({
+                    success: true,
+                    error: undefined,
+                });
+            },
             onValidateSession: function (event, checkout, callback) {
                 console.log("validating session", event.session);
                 callback({
@@ -161,6 +168,13 @@ const checkout = await embed({
             event.payment_product_type,
         );
     },
+    onAddressCallback: function (event: AddressCallback, checkout, callback) {
+        console.log("address callback to handle express session address updates", event.session);
+        callback({
+            success: true,
+            error: undefined,
+        });
+    },
     onValidateSession: function (event: ValidateSession, checkout, callback) {
         console.log("validating session", event.session);
         callback({
@@ -187,6 +201,53 @@ Resetting selection (so no option is selected in the checkout):
 checkout.setActivePaymentProductType();
 ```
 
+### Handling Checkout Express address updates using the onAddressCallback
+
+If the `onAddressCallback` is provided the checkout **will not perform the machine to machine address update callback** defined in the payment session
+object at `express.shipping_address_callback_url`. Instead the SDK runtime has to handle the address update flow.
+
+The `onAddressCallback` function is invoked when an end user submits their address details (the shipping and billing addresses) in an embedded Checkout Express session. The callback function is invoked with an updated session that is not yet persisted in the Dintero backend. The checkout will be locked and payment will be paused until the provided callback function is called, or `checkout.submitAddressCallbackResult` is called with the result.
+
+When `onAddressCallback` is invoked you will have to perform a [server-to-server session update](#perform-a-server-to-server-session-update) with shipping options or other details that have changed. Once the
+session has been updated you need to call the provided callback function with a result.
+
+When session has been updated successfully, return a successful result:
+
+```js
+{
+    success: true;
+}
+```
+
+If the session update failed, return the result with an error message:
+
+```js
+{
+   success: false,
+   error: "<reason for session update failure>"
+}
+```
+
+Example implementation:
+
+```
+onAddressCallback: function(event, checkout, callback) {
+     // Perform a server-to-server session update
+     getShippingOptionsForAddressAndUpdateSession(event.session).then(() => {
+        callback({
+            success: true,
+        });
+     }).catch((err) => {
+        callback({
+            success: false,
+            error: toErrorMessage(err), 
+        });
+     });
+},
+```
+
+> **Note:** When implementing the `onAddressCallback`, there is no need to manually lock the session and refresh it. The checkout will automatically lock the payment and refresh the session when the `callback` function is used to return a result.
+
 ### Updating an Checkout Express-session
 
 To update an existing Checkout Express-session, follow these steps:

package/dist/declarations/src/checkout.d.ts

@@ -10,7 +10,8 @@ export declare enum CheckoutEvents {
     SessionLocked = "SessionLocked",
     SessionLockFailed = "SessionLockFailed",
     ActivePaymentProductType = "ActivePaymentProductType",
-    ValidateSession = "ValidateSession"
+    ValidateSession = "ValidateSession",
+    AddressCallback = "AddressCallback"
 }
 export declare enum InternalCheckoutEvents {
     HeightChanged = "HeightChanged",
@@ -103,7 +104,17 @@ export interface SessionValidationCallback {
     success: boolean;
     clientValidationError?: string;
 }
+export type AddressCallback = {
+    type: CheckoutEvents.AddressCallback;
+    session: Session;
+    callback: (result: AddressCallbackResult) => void;
+};
+export interface AddressCallbackResult {
+    success: boolean;
+    error?: string;
+}
 export type WrappedValidateSession = Pick<ValidateSession, "type" | "session">;
+export type WrappedAddressCallback = Pick<AddressCallback, "type" | "session">;
 export type WrappedSessionLocked = Pick<SessionLocked, "type" | "pay_lock_id">;
 export type SessionPayment = SessionPaymentAuthorized | SessionPaymentOnHold;
 export type SessionPaymentError = {
@@ -111,4 +122,4 @@ export type SessionPaymentError = {
     error: string;
     href: string;
 };
-export type SessionEvent = SessionNotFound | SessionLoaded | SessionUpdated | SessionCancel | SessionPaymentOnHold | SessionPaymentAuthorized | SessionPaymentError | WrappedSessionLocked | SessionLockFailed | ActivePaymentProductType | WrappedValidateSession;
+export type SessionEvent = SessionNotFound | SessionLoaded | SessionUpdated | SessionCancel | SessionPaymentOnHold | SessionPaymentAuthorized | SessionPaymentError | WrappedSessionLocked | SessionLockFailed | ActivePaymentProductType | WrappedValidateSession | WrappedAddressCallback;

package/dist/declarations/src/index.d.ts

@@ -1,5 +1,5 @@
 import "native-promise-only";
-import { type ActivePaymentProductType, CheckoutEvents, InternalCheckoutEvents, type SessionCancel, type SessionEvent, type SessionLoaded, type SessionLocked, type SessionLockFailed, type SessionNotFound, type SessionPaymentAuthorized, type SessionPaymentError, type SessionPaymentOnHold, type SessionUpdated, type SessionValidationCallback, type ValidateSession } from "./checkout.js";
+import { type ActivePaymentProductType, type AddressCallback, type AddressCallbackResult, CheckoutEvents, InternalCheckoutEvents, type SessionCancel, type SessionEvent, type SessionLoaded, type SessionLocked, type SessionLockFailed, type SessionNotFound, type SessionPaymentAuthorized, type SessionPaymentError, type SessionPaymentOnHold, type SessionUpdated, type SessionValidationCallback, type ValidateSession } from "./checkout.js";
 import type { Session } from "./session.js";
 import { type SubscriptionHandler } from "./subscribe.js";
 export interface DinteroCheckoutInstance {
@@ -13,6 +13,7 @@ export interface DinteroCheckoutInstance {
     refreshSession: () => Promise<SessionEvent>;
     setActivePaymentProductType: (paymentProductType: string) => void;
     submitValidationResult: (result: SessionValidationCallback) => void;
+    submitAddressCallbackResult: (result: AddressCallbackResult) => void;
     options: InternalDinteroEmbedCheckoutOptions;
     handlers: ({
         handler: SubscriptionHandler;
@@ -46,6 +47,7 @@ export interface DinteroEmbedCheckoutOptions extends DinteroCheckoutOptions {
     onSessionLockFailed?: (event: SessionLockFailed, checkout: DinteroCheckoutInstance) => void;
     onActivePaymentType?: (event: ActivePaymentProductType, checkout: DinteroCheckoutInstance) => void;
     onValidateSession?: (event: ValidateSession, checkout: DinteroCheckoutInstance, callback: (result: SessionValidationCallback) => void) => void;
+    onAddressCallback?: (event: AddressCallback, checkout: DinteroCheckoutInstance, callback: (result: AddressCallbackResult) => void) => void;
 }
 interface InternalDinteroEmbedCheckoutOptions extends DinteroEmbedCheckoutOptions {
     innerContainer: HTMLDivElement;

package/dist/declarations/src/subscribe.d.ts

@@ -1,5 +1,5 @@
 import type { DinteroCheckoutInstance } from "./index.js";
-import type { CheckoutEvents, InternalCheckoutEvents, SessionEvent, SessionValidationCallback } from "./checkout.js";
+import type { AddressCallbackResult, CheckoutEvents, InternalCheckoutEvents, SessionEvent, SessionValidationCallback } from "./checkout.js";
 /**
  * Unsubscribe handler from event(s).
  */
@@ -26,6 +26,10 @@ export declare const postSessionLock: (iframe: HTMLIFrameElement, sid: string) =
  * Post the validation result to the checkout iframe
  */
 export declare const postValidationResult: (iframe: HTMLIFrameElement, sid: string, result: SessionValidationCallback) => void;
+/**
+ * Post the address call back result to the checkout iframe
+ */
+export declare const postAddressCallbackResult: (iframe: HTMLIFrameElement, sid: string, result: AddressCallbackResult) => void;
 /**
  * Post RefreshSession-event to the checkout iframe.
  */

package/dist/dintero-checkout-web-sdk.cjs.dev.js

@@ -6,7 +6,7 @@ require('native-promise-only');
 
 var pkg = {
 	name: "@dintero/checkout-web-sdk",
-	version: "0.11.5",
+	version: "0.12.0",
 	description: "Dintero Checkout SDK for web frontends",
 	main: "dist/dintero-checkout-web-sdk.cjs.js",
 	module: "dist/dintero-checkout-web-sdk.esm.js",
@@ -68,6 +68,7 @@ let CheckoutEvents = /*#__PURE__*/function (CheckoutEvents) {
   CheckoutEvents["SessionLockFailed"] = "SessionLockFailed";
   CheckoutEvents["ActivePaymentProductType"] = "ActivePaymentProductType";
   CheckoutEvents["ValidateSession"] = "ValidateSession";
+  CheckoutEvents["AddressCallback"] = "AddressCallback";
   return CheckoutEvents;
 }({});
 let InternalCheckoutEvents = /*#__PURE__*/function (InternalCheckoutEvents) {
@@ -153,6 +154,7 @@ const getSessionUrl = options => {
     language,
     ui,
     shouldCallValidateSession,
+    shouldCallAddressCallback,
     popOut,
     redirect
   } = options;
@@ -170,6 +172,9 @@ const getSessionUrl = options => {
   if (shouldCallValidateSession) {
     params.append("client_side_validation", "true");
   }
+  if (shouldCallAddressCallback) {
+    params.append("client_side_address_callback", "true");
+  }
   if (popOut) {
     params.append("role", "pop_out_launcher");
   }
@@ -860,6 +865,19 @@ const postValidationResult = (iframe, sid, result) => {
   }
 };
 
+/**
+ * Post the address call back result to the checkout iframe
+ */
+const postAddressCallbackResult = (iframe, sid, result) => {
+  if (iframe.contentWindow) {
+    iframe.contentWindow.postMessage({
+      type: "AddressCallbackResult",
+      sid,
+      ...result
+    }, "*");
+  }
+};
+
 /**
  * Post RefreshSession-event to the checkout iframe.
  */
@@ -1118,6 +1136,8 @@ const showPopOut = async (event, checkout) => {
     sid: checkout.options.sid,
     endpoint: checkout.options.endpoint,
     shouldCallValidateSession: Boolean(checkout.options.onValidateSession),
+    shouldCallAddressCallback: false,
+    // handled by embedded checkout not the pop out window
     language: event.language,
     onOpen: popOutWindow => createPopOutMessageHandler(popOutWindow, checkout),
     onClose: () => {
@@ -1159,6 +1179,7 @@ const createPopOutValidationCallback = (event, checkout) => {
         sid: checkout.options.sid,
         endpoint: checkout.options.endpoint,
         shouldCallValidateSession: false,
+        shouldCallAddressCallback: false,
         language: event.language
       });
     } else {
@@ -1291,6 +1312,7 @@ const embed = async options => {
     onSessionLockFailed,
     onActivePaymentType,
     onValidateSession,
+    onAddressCallback,
     popOut
   } = internalOptions;
   let checkout;
@@ -1308,6 +1330,7 @@ const embed = async options => {
     language,
     ui: options.ui || "inline",
     shouldCallValidateSession: onValidateSession !== undefined,
+    shouldCallAddressCallback: onAddressCallback !== undefined,
     popOut,
     // biome-ignore lint/suspicious/noPrototypeBuiltins: test
     ...(options.hasOwnProperty("hideTestMessage") && {
@@ -1400,6 +1423,10 @@ const embed = async options => {
     postValidationResult(iframe, sid, result);
     // For pop out we do validation when opening the pop out
   };
+  const submitAddressCallbackResult = result => {
+    postAddressCallbackResult(iframe, sid, result);
+    // For pop out we do validation when opening the pop out
+  };
 
   /**
    *  Internal result event message handler wrapper, to replace the content of the iframe with a success/or
@@ -1440,6 +1467,22 @@ const embed = async options => {
       }
     }
   };
+  const wrappedOnAddressCallback = (event, checkout) => {
+    if (onAddressCallback) {
+      try {
+        onAddressCallback({
+          ...event,
+          callback: submitAddressCallbackResult
+        }, checkout, submitAddressCallbackResult);
+      } catch (e) {
+        console.error(e);
+        submitAddressCallbackResult({
+          success: false,
+          error: "Address callback runtime error"
+        });
+      }
+    }
+  };
   const wrappedOnSessionLocked = (event, checkout) => {
     if (onSessionLocked) {
       onSessionLocked(event, checkout, refreshSession);
@@ -1496,6 +1539,9 @@ const embed = async options => {
   }, {
     handler: wrappedOnValidateSession,
     eventTypes: [CheckoutEvents.ValidateSession]
+  }, {
+    handler: wrappedOnAddressCallback,
+    eventTypes: [CheckoutEvents.AddressCallback]
   }, {
     handler: handleShowButton,
     eventTypes: [InternalCheckoutEvents.ShowPopOutButton]
@@ -1512,6 +1558,7 @@ const embed = async options => {
     refreshSession,
     setActivePaymentProductType,
     submitValidationResult,
+    submitAddressCallbackResult,
     options: internalOptions,
     handlers,
     session: undefined,
@@ -1554,6 +1601,7 @@ const redirect = options => {
     endpoint,
     language,
     shouldCallValidateSession: false,
+    shouldCallAddressCallback: false,
     redirect: true
   }));
 };

package/dist/dintero-checkout-web-sdk.cjs.prod.js

@@ -6,7 +6,7 @@ require('native-promise-only');
 
 var pkg = {
 	name: "@dintero/checkout-web-sdk",
-	version: "0.11.5",
+	version: "0.12.0",
 	description: "Dintero Checkout SDK for web frontends",
 	main: "dist/dintero-checkout-web-sdk.cjs.js",
 	module: "dist/dintero-checkout-web-sdk.esm.js",
@@ -68,6 +68,7 @@ let CheckoutEvents = /*#__PURE__*/function (CheckoutEvents) {
   CheckoutEvents["SessionLockFailed"] = "SessionLockFailed";
   CheckoutEvents["ActivePaymentProductType"] = "ActivePaymentProductType";
   CheckoutEvents["ValidateSession"] = "ValidateSession";
+  CheckoutEvents["AddressCallback"] = "AddressCallback";
   return CheckoutEvents;
 }({});
 let InternalCheckoutEvents = /*#__PURE__*/function (InternalCheckoutEvents) {
@@ -153,6 +154,7 @@ const getSessionUrl = options => {
     language,
     ui,
     shouldCallValidateSession,
+    shouldCallAddressCallback,
     popOut,
     redirect
   } = options;
@@ -170,6 +172,9 @@ const getSessionUrl = options => {
   if (shouldCallValidateSession) {
     params.append("client_side_validation", "true");
   }
+  if (shouldCallAddressCallback) {
+    params.append("client_side_address_callback", "true");
+  }
   if (popOut) {
     params.append("role", "pop_out_launcher");
   }
@@ -860,6 +865,19 @@ const postValidationResult = (iframe, sid, result) => {
   }
 };
 
+/**
+ * Post the address call back result to the checkout iframe
+ */
+const postAddressCallbackResult = (iframe, sid, result) => {
+  if (iframe.contentWindow) {
+    iframe.contentWindow.postMessage({
+      type: "AddressCallbackResult",
+      sid,
+      ...result
+    }, "*");
+  }
+};
+
 /**
  * Post RefreshSession-event to the checkout iframe.
  */
@@ -1118,6 +1136,8 @@ const showPopOut = async (event, checkout) => {
     sid: checkout.options.sid,
     endpoint: checkout.options.endpoint,
     shouldCallValidateSession: Boolean(checkout.options.onValidateSession),
+    shouldCallAddressCallback: false,
+    // handled by embedded checkout not the pop out window
     language: event.language,
     onOpen: popOutWindow => createPopOutMessageHandler(popOutWindow, checkout),
     onClose: () => {
@@ -1159,6 +1179,7 @@ const createPopOutValidationCallback = (event, checkout) => {
         sid: checkout.options.sid,
         endpoint: checkout.options.endpoint,
         shouldCallValidateSession: false,
+        shouldCallAddressCallback: false,
         language: event.language
       });
     } else {
@@ -1291,6 +1312,7 @@ const embed = async options => {
     onSessionLockFailed,
     onActivePaymentType,
     onValidateSession,
+    onAddressCallback,
     popOut
   } = internalOptions;
   let checkout;
@@ -1308,6 +1330,7 @@ const embed = async options => {
     language,
     ui: options.ui || "inline",
     shouldCallValidateSession: onValidateSession !== undefined,
+    shouldCallAddressCallback: onAddressCallback !== undefined,
     popOut,
     // biome-ignore lint/suspicious/noPrototypeBuiltins: test
     ...(options.hasOwnProperty("hideTestMessage") && {
@@ -1400,6 +1423,10 @@ const embed = async options => {
     postValidationResult(iframe, sid, result);
     // For pop out we do validation when opening the pop out
   };
+  const submitAddressCallbackResult = result => {
+    postAddressCallbackResult(iframe, sid, result);
+    // For pop out we do validation when opening the pop out
+  };
 
   /**
    *  Internal result event message handler wrapper, to replace the content of the iframe with a success/or
@@ -1440,6 +1467,22 @@ const embed = async options => {
       }
     }
   };
+  const wrappedOnAddressCallback = (event, checkout) => {
+    if (onAddressCallback) {
+      try {
+        onAddressCallback({
+          ...event,
+          callback: submitAddressCallbackResult
+        }, checkout, submitAddressCallbackResult);
+      } catch (e) {
+        console.error(e);
+        submitAddressCallbackResult({
+          success: false,
+          error: "Address callback runtime error"
+        });
+      }
+    }
+  };
   const wrappedOnSessionLocked = (event, checkout) => {
     if (onSessionLocked) {
       onSessionLocked(event, checkout, refreshSession);
@@ -1496,6 +1539,9 @@ const embed = async options => {
   }, {
     handler: wrappedOnValidateSession,
     eventTypes: [CheckoutEvents.ValidateSession]
+  }, {
+    handler: wrappedOnAddressCallback,
+    eventTypes: [CheckoutEvents.AddressCallback]
   }, {
     handler: handleShowButton,
     eventTypes: [InternalCheckoutEvents.ShowPopOutButton]
@@ -1512,6 +1558,7 @@ const embed = async options => {
     refreshSession,
     setActivePaymentProductType,
     submitValidationResult,
+    submitAddressCallbackResult,
     options: internalOptions,
     handlers,
     session: undefined,
@@ -1554,6 +1601,7 @@ const redirect = options => {
     endpoint,
     language,
     shouldCallValidateSession: false,
+    shouldCallAddressCallback: false,
     redirect: true
   }));
 };

package/dist/dintero-checkout-web-sdk.esm.js

@@ -2,7 +2,7 @@ import 'native-promise-only';
 
 var pkg = {
 	name: "@dintero/checkout-web-sdk",
-	version: "0.11.5",
+	version: "0.12.0",
 	description: "Dintero Checkout SDK for web frontends",
 	main: "dist/dintero-checkout-web-sdk.cjs.js",
 	module: "dist/dintero-checkout-web-sdk.esm.js",
@@ -64,6 +64,7 @@ let CheckoutEvents = /*#__PURE__*/function (CheckoutEvents) {
   CheckoutEvents["SessionLockFailed"] = "SessionLockFailed";
   CheckoutEvents["ActivePaymentProductType"] = "ActivePaymentProductType";
   CheckoutEvents["ValidateSession"] = "ValidateSession";
+  CheckoutEvents["AddressCallback"] = "AddressCallback";
   return CheckoutEvents;
 }({});
 let InternalCheckoutEvents = /*#__PURE__*/function (InternalCheckoutEvents) {
@@ -149,6 +150,7 @@ const getSessionUrl = options => {
     language,
     ui,
     shouldCallValidateSession,
+    shouldCallAddressCallback,
     popOut,
     redirect
   } = options;
@@ -166,6 +168,9 @@ const getSessionUrl = options => {
   if (shouldCallValidateSession) {
     params.append("client_side_validation", "true");
   }
+  if (shouldCallAddressCallback) {
+    params.append("client_side_address_callback", "true");
+  }
   if (popOut) {
     params.append("role", "pop_out_launcher");
   }
@@ -856,6 +861,19 @@ const postValidationResult = (iframe, sid, result) => {
   }
 };
 
+/**
+ * Post the address call back result to the checkout iframe
+ */
+const postAddressCallbackResult = (iframe, sid, result) => {
+  if (iframe.contentWindow) {
+    iframe.contentWindow.postMessage({
+      type: "AddressCallbackResult",
+      sid,
+      ...result
+    }, "*");
+  }
+};
+
 /**
  * Post RefreshSession-event to the checkout iframe.
  */
@@ -1114,6 +1132,8 @@ const showPopOut = async (event, checkout) => {
     sid: checkout.options.sid,
     endpoint: checkout.options.endpoint,
     shouldCallValidateSession: Boolean(checkout.options.onValidateSession),
+    shouldCallAddressCallback: false,
+    // handled by embedded checkout not the pop out window
     language: event.language,
     onOpen: popOutWindow => createPopOutMessageHandler(popOutWindow, checkout),
     onClose: () => {
@@ -1155,6 +1175,7 @@ const createPopOutValidationCallback = (event, checkout) => {
         sid: checkout.options.sid,
         endpoint: checkout.options.endpoint,
         shouldCallValidateSession: false,
+        shouldCallAddressCallback: false,
         language: event.language
       });
     } else {
@@ -1287,6 +1308,7 @@ const embed = async options => {
     onSessionLockFailed,
     onActivePaymentType,
     onValidateSession,
+    onAddressCallback,
     popOut
   } = internalOptions;
   let checkout;
@@ -1304,6 +1326,7 @@ const embed = async options => {
     language,
     ui: options.ui || "inline",
     shouldCallValidateSession: onValidateSession !== undefined,
+    shouldCallAddressCallback: onAddressCallback !== undefined,
     popOut,
     // biome-ignore lint/suspicious/noPrototypeBuiltins: test
     ...(options.hasOwnProperty("hideTestMessage") && {
@@ -1396,6 +1419,10 @@ const embed = async options => {
     postValidationResult(iframe, sid, result);
     // For pop out we do validation when opening the pop out
   };
+  const submitAddressCallbackResult = result => {
+    postAddressCallbackResult(iframe, sid, result);
+    // For pop out we do validation when opening the pop out
+  };
 
   /**
    *  Internal result event message handler wrapper, to replace the content of the iframe with a success/or
@@ -1436,6 +1463,22 @@ const embed = async options => {
       }
     }
   };
+  const wrappedOnAddressCallback = (event, checkout) => {
+    if (onAddressCallback) {
+      try {
+        onAddressCallback({
+          ...event,
+          callback: submitAddressCallbackResult
+        }, checkout, submitAddressCallbackResult);
+      } catch (e) {
+        console.error(e);
+        submitAddressCallbackResult({
+          success: false,
+          error: "Address callback runtime error"
+        });
+      }
+    }
+  };
   const wrappedOnSessionLocked = (event, checkout) => {
     if (onSessionLocked) {
       onSessionLocked(event, checkout, refreshSession);
@@ -1492,6 +1535,9 @@ const embed = async options => {
   }, {
     handler: wrappedOnValidateSession,
     eventTypes: [CheckoutEvents.ValidateSession]
+  }, {
+    handler: wrappedOnAddressCallback,
+    eventTypes: [CheckoutEvents.AddressCallback]
   }, {
     handler: handleShowButton,
     eventTypes: [InternalCheckoutEvents.ShowPopOutButton]
@@ -1508,6 +1554,7 @@ const embed = async options => {
     refreshSession,
     setActivePaymentProductType,
     submitValidationResult,
+    submitAddressCallbackResult,
     options: internalOptions,
     handlers,
     session: undefined,
@@ -1550,6 +1597,7 @@ const redirect = options => {
     endpoint,
     language,
     shouldCallValidateSession: false,
+    shouldCallAddressCallback: false,
     redirect: true
   }));
 };