@valuepay/react 1.0.0 → 2.1.0

package/dist/cjs/components/ValuePayButton.js

@@ -3,11 +3,15 @@
 var jsxRuntime = require('react/jsx-runtime');
 var useValuePay = require('../hooks/useValuePay.js');
 
-const ValuePayButton = ({ text, className, style, disabled, children, ...config }) => {
+const ValuePayButton = ({ text, className, style, containerStyle, containerClassName, disabled, children, ...config }) => {
     const { initialize, isReady, isProcessing } = useValuePay.useValuePay(config);
     const defaultText = `Pay \u20A6${config.amount.toLocaleString()} Now`;
     const buttonText = children || text || defaultText;
-    return (jsxRuntime.jsx("button", { type: "button", onClick: () => initialize(), disabled: disabled || !isReady || isProcessing, className: className, style: style, "aria-busy": isProcessing, "aria-label": typeof buttonText === "string" ? buttonText : "Pay Now", children: isProcessing ? "Processing..." : buttonText }));
+    const button = (jsxRuntime.jsx("button", { type: "button", onClick: () => initialize(), disabled: disabled || !isReady || isProcessing, className: className, style: style, "aria-busy": isProcessing, "aria-label": typeof buttonText === "string" ? buttonText : "Pay Now", children: isProcessing ? "Processing..." : buttonText }));
+    if (containerStyle || containerClassName) {
+        return (jsxRuntime.jsx("div", { style: containerStyle, className: containerClassName, "data-testid": "valuepay-button-container", children: button }));
+    }
+    return button;
 };
 
 exports.ValuePayButton = ValuePayButton;

package/dist/cjs/components/ValuePayButton.js.map

@@ -1 +1 @@
-{"version":3,"file":"ValuePayButton.js","sources":["../../../../src/components/ValuePayButton.tsx"],"sourcesContent":["import React from \"react\";\nimport { useValuePay } from \"../hooks/useValuePay\";\nimport type { ValuePayButtonProps } from \"../types\";\n\nexport const ValuePayButton: React.FC<ValuePayButtonProps> = ({\n  text,\n  className,\n  style,\n  disabled,\n  children,\n  ...config\n}) => {\n  const { initialize, isReady, isProcessing } = useValuePay(config);\n\n  const defaultText = `Pay \\u20A6${config.amount.toLocaleString()} Now`;\n  const buttonText = children || text || defaultText;\n\n  return (\n    <button\n      type=\"button\"\n      onClick={() => initialize()}\n      disabled={disabled || !isReady || isProcessing}\n      className={className}\n      style={style}\n      aria-busy={isProcessing}\n      aria-label={typeof buttonText === \"string\" ? buttonText : \"Pay Now\"}\n    >\n      {isProcessing ? \"Processing...\" : buttonText}\n    </button>\n  );\n};\n"],"names":["useValuePay","_jsx"],"mappings":";;;;;MAIa,cAAc,GAAkC,CAAC,EAC5D,IAAI,EACJ,SAAS,EACT,KAAK,EACL,QAAQ,EACR,QAAQ,EACR,GAAG,MAAM,EACV,KAAI;AACH,IAAA,MAAM,EAAE,UAAU,EAAE,OAAO,EAAE,YAAY,EAAE,GAAGA,uBAAW,CAAC,MAAM,CAAC;IAEjE,MAAM,WAAW,GAAG,CAAA,UAAA,EAAa,MAAM,CAAC,MAAM,CAAC,cAAc,EAAE,CAAA,IAAA,CAAM;AACrE,IAAA,MAAM,UAAU,GAAG,QAAQ,IAAI,IAAI,IAAI,WAAW;IAElD,QACEC,cAAA,CAAA,QAAA,EAAA,EACE,IAAI,EAAC,QAAQ,EACb,OAAO,EAAE,MAAM,UAAU,EAAE,EAC3B,QAAQ,EAAE,QAAQ,IAAI,CAAC,OAAO,IAAI,YAAY,EAC9C,SAAS,EAAE,SAAS,EACpB,KAAK,EAAE,KAAK,EAAA,WAAA,EACD,YAAY,EAAA,YAAA,EACX,OAAO,UAAU,KAAK,QAAQ,GAAG,UAAU,GAAG,SAAS,EAAA,QAAA,EAElE,YAAY,GAAG,eAAe,GAAG,UAAU,EAAA,CACrC;AAEb;;;;"}
+{"version":3,"file":"ValuePayButton.js","sources":["../../../../src/components/ValuePayButton.tsx"],"sourcesContent":["import React from \"react\";\r\nimport { useValuePay } from \"../hooks/useValuePay\";\r\nimport type { ValuePayButtonProps } from \"../types\";\r\n\r\nexport const ValuePayButton: React.FC<ValuePayButtonProps> = ({\r\n  text,\r\n  className,\r\n  style,\r\n  containerStyle,\r\n  containerClassName,\r\n  disabled,\r\n  children,\r\n  ...config\r\n}) => {\r\n  const { initialize, isReady, isProcessing } = useValuePay(config);\r\n\r\n  const defaultText = `Pay \\u20A6${config.amount.toLocaleString()} Now`;\r\n  const buttonText = children || text || defaultText;\r\n\r\n  const button = (\r\n    <button\r\n      type=\"button\"\r\n      onClick={() => initialize()}\r\n      disabled={disabled || !isReady || isProcessing}\r\n      className={className}\r\n      style={style}\r\n      aria-busy={isProcessing}\r\n      aria-label={typeof buttonText === \"string\" ? buttonText : \"Pay Now\"}\r\n    >\r\n      {isProcessing ? \"Processing...\" : buttonText}\r\n    </button>\r\n  );\r\n\r\n  if (containerStyle || containerClassName) {\r\n    return (\r\n      <div style={containerStyle} className={containerClassName} data-testid=\"valuepay-button-container\">\r\n        {button}\r\n      </div>\r\n    );\r\n  }\r\n\r\n  return button;\r\n};\r\n"],"names":["useValuePay","_jsx"],"mappings":";;;;;AAIO,MAAM,cAAc,GAAkC,CAAC,EAC5D,IAAI,EACJ,SAAS,EACT,KAAK,EACL,cAAc,EACd,kBAAkB,EAClB,QAAQ,EACR,QAAQ,EACR,GAAG,MAAM,EACV,KAAI;AACH,IAAA,MAAM,EAAE,UAAU,EAAE,OAAO,EAAE,YAAY,EAAE,GAAGA,uBAAW,CAAC,MAAM,CAAC;IAEjE,MAAM,WAAW,GAAG,CAAA,UAAA,EAAa,MAAM,CAAC,MAAM,CAAC,cAAc,EAAE,CAAA,IAAA,CAAM;AACrE,IAAA,MAAM,UAAU,GAAG,QAAQ,IAAI,IAAI,IAAI,WAAW;IAElD,MAAM,MAAM,IACVC,cAAA,CAAA,QAAA,EAAA,EACE,IAAI,EAAC,QAAQ,EACb,OAAO,EAAE,MAAM,UAAU,EAAE,EAC3B,QAAQ,EAAE,QAAQ,IAAI,CAAC,OAAO,IAAI,YAAY,EAC9C,SAAS,EAAE,SAAS,EACpB,KAAK,EAAE,KAAK,EAAA,WAAA,EACD,YAAY,EAAA,YAAA,EACX,OAAO,UAAU,KAAK,QAAQ,GAAG,UAAU,GAAG,SAAS,EAAA,QAAA,EAElE,YAAY,GAAG,eAAe,GAAG,UAAU,EAAA,CACrC,CACV;AAED,IAAA,IAAI,cAAc,IAAI,kBAAkB,EAAE;AACxC,QAAA,QACEA,cAAA,CAAA,KAAA,EAAA,EAAK,KAAK,EAAE,cAAc,EAAE,SAAS,EAAE,kBAAkB,iBAAc,2BAA2B,EAAA,QAAA,EAC/F,MAAM,EAAA,CACH;IAEV;AAEA,IAAA,OAAO,MAAM;AACf;;;;"}

package/dist/cjs/hooks/useValuePay.js

@@ -5,6 +5,32 @@ var useScript = require('./useScript.js');
 var helpers = require('../utils/helpers.js');
 var constants = require('../utils/constants.js');
 
+/**
+ * Checks whether any callback function is provided in the config,
+ * using case-insensitive detection to handle both SDK-style (onCallback)
+ * and raw checkout-style (oncallback) casing.
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+function hasCallback(cfg, ...names) {
+    return names.some((name) => typeof cfg[name] === "function" || typeof cfg[name.toLowerCase()] === "function");
+}
+/**
+ * Returns true if the config has ANY callback defined (case-insensitive).
+ * When true, callbacks take precedence and redirectUrl is ignored.
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+function hasAnyCallback(cfg) {
+    return hasCallback(cfg, "onSuccess", "onCallback", "onCancelled", "onClose", "onError");
+}
+/**
+ * Redirects the browser to the given URL with ref and status query params.
+ */
+function redirectTo(redirectUrl, ref, status) {
+    const url = new URL(redirectUrl);
+    url.searchParams.set("ref", ref);
+    url.searchParams.set("status", status);
+    window.location.href = url.toString();
+}
 const useValuePay = (config) => {
     const scriptUrl = config.scriptUrl || constants.DEFAULT_SCRIPT_URL;
     const isReady = useScript.useScript(scriptUrl);
@@ -23,24 +49,33 @@ const useValuePay = (config) => {
         setIsProcessing(true);
         const normalized = helpers.normalizeConfig(cfg, overrides);
         const ref = normalized.transactionRef;
+        const useRedirect = !hasAnyCallback(cfg) && !!cfg.redirectUrl;
         window.ValuepayCheckout({
             ...normalized,
             // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            onsuccess: (response) => {
+                var _a;
+                const res = helpers.normalizeResponse(response, ref, cfg);
+                setIsProcessing(false);
+                if (useRedirect) {
+                    redirectTo(cfg.redirectUrl, res.ref, res.status);
+                    return;
+                }
+                if (res.status !== "SUCCESS" && res.status !== "COMPLETED") {
+                    res.status = "SUCCESS";
+                }
+                (_a = cfg.onSuccess) === null || _a === void 0 ? void 0 : _a.call(cfg, res);
+            },
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
             oncallback: (response) => {
-                var _a, _b;
+                var _a;
                 const res = helpers.normalizeResponse(response, ref, cfg);
                 setIsProcessing(false);
-                if (cfg.redirectUrl) {
-                    const url = new URL(cfg.redirectUrl);
-                    url.searchParams.set("ref", res.ref);
-                    url.searchParams.set("status", res.status);
-                    window.location.href = url.toString();
+                if (useRedirect) {
+                    redirectTo(cfg.redirectUrl, res.ref, res.status);
                     return;
                 }
                 (_a = cfg.onCallback) === null || _a === void 0 ? void 0 : _a.call(cfg, res);
-                if (res.status === "SUCCESS" || res.status === "COMPLETED") {
-                    (_b = cfg.onSuccess) === null || _b === void 0 ? void 0 : _b.call(cfg, res);
-                }
             },
             // eslint-disable-next-line @typescript-eslint/no-explicit-any
             onCancelled: (response) => {
@@ -48,11 +83,8 @@ const useValuePay = (config) => {
                 const res = helpers.normalizeResponse(response, ref, cfg);
                 res.status = "CANCELLED";
                 setIsProcessing(false);
-                if (cfg.redirectUrl) {
-                    const url = new URL(cfg.redirectUrl);
-                    url.searchParams.set("ref", res.ref);
-                    url.searchParams.set("status", "CANCELLED");
-                    window.location.href = url.toString();
+                if (useRedirect) {
+                    redirectTo(cfg.redirectUrl, res.ref, "CANCELLED");
                     return;
                 }
                 (_a = cfg.onCancelled) === null || _a === void 0 ? void 0 : _a.call(cfg, res);
@@ -70,11 +102,8 @@ const useValuePay = (config) => {
                 var _a;
                 const res = helpers.normalizeResponse(response, ref, cfg);
                 setIsProcessing(false);
-                if (cfg.redirectUrl) {
-                    const url = new URL(cfg.redirectUrl);
-                    url.searchParams.set("ref", res.ref);
-                    url.searchParams.set("status", "CLOSED");
-                    window.location.href = url.toString();
+                if (useRedirect) {
+                    redirectTo(cfg.redirectUrl, res.ref, "CLOSED");
                     return;
                 }
                 (_a = cfg.onClose) === null || _a === void 0 ? void 0 : _a.call(cfg, res);

package/dist/cjs/hooks/useValuePay.js.map

@@ -1 +1 @@
-{"version":3,"file":"useValuePay.js","sources":["../../../../src/hooks/useValuePay.ts"],"sourcesContent":["import { useCallback, useState, useRef } from \"react\";\nimport { useScript } from \"./useScript\";\nimport { normalizeConfig, normalizeResponse } from \"../utils/helpers\";\nimport { DEFAULT_SCRIPT_URL } from \"../utils/constants\";\nimport type { ValuePayConfig, UseValuePayReturn } from \"../types\";\n\nexport const useValuePay = (config: ValuePayConfig): UseValuePayReturn => {\n  const scriptUrl = config.scriptUrl || DEFAULT_SCRIPT_URL;\n  const isReady = useScript(scriptUrl);\n  const [isProcessing, setIsProcessing] = useState(false);\n  const configRef = useRef(config);\n  configRef.current = config;\n\n  const initialize = useCallback(\n    (overrides?: Partial<ValuePayConfig>) => {\n      const cfg = configRef.current;\n\n      if (typeof window === \"undefined\" || !window.ValuepayCheckout) {\n        cfg.onError?.(new Error(\"ValuePay script not loaded. Ensure the script URL is accessible.\"));\n        return;\n      }\n\n      if (isProcessing) return;\n\n      setIsProcessing(true);\n\n      const normalized = normalizeConfig(cfg, overrides);\n      const ref = normalized.transactionRef;\n\n      window.ValuepayCheckout({\n        ...normalized,\n\n        // eslint-disable-next-line @typescript-eslint/no-explicit-any\n        oncallback: (response: any) => {\n          const res = normalizeResponse(response, ref, cfg);\n          setIsProcessing(false);\n\n          if (cfg.redirectUrl) {\n            const url = new URL(cfg.redirectUrl);\n            url.searchParams.set(\"ref\", res.ref);\n            url.searchParams.set(\"status\", res.status);\n            window.location.href = url.toString();\n            return;\n          }\n\n          cfg.onCallback?.(res);\n\n          if (res.status === \"SUCCESS\" || res.status === \"COMPLETED\") {\n            cfg.onSuccess?.(res);\n          }\n        },\n\n        // eslint-disable-next-line @typescript-eslint/no-explicit-any\n        onCancelled: (response: any) => {\n          const res = normalizeResponse(response, ref, cfg);\n          res.status = \"CANCELLED\";\n          setIsProcessing(false);\n\n          if (cfg.redirectUrl) {\n            const url = new URL(cfg.redirectUrl);\n            url.searchParams.set(\"ref\", res.ref);\n            url.searchParams.set(\"status\", \"CANCELLED\");\n            window.location.href = url.toString();\n            return;\n          }\n\n          cfg.onCancelled?.(res);\n        },\n\n        // eslint-disable-next-line @typescript-eslint/no-explicit-any\n        onAborted: (response: any) => {\n          const res = normalizeResponse(response, ref, cfg);\n          res.status = \"CANCELLED\";\n          setIsProcessing(false);\n          cfg.onCancelled?.(res);\n        },\n\n        // eslint-disable-next-line @typescript-eslint/no-explicit-any\n        onClosed: (response: any) => {\n          const res = normalizeResponse(response, ref, cfg);\n          setIsProcessing(false);\n\n          if (cfg.redirectUrl) {\n            const url = new URL(cfg.redirectUrl);\n            url.searchParams.set(\"ref\", res.ref);\n            url.searchParams.set(\"status\", \"CLOSED\");\n            window.location.href = url.toString();\n            return;\n          }\n\n          cfg.onClose?.(res);\n        },\n      });\n    },\n    // eslint-disable-next-line react-hooks/exhaustive-deps\n    [isReady, isProcessing],\n  );\n\n  return { initialize, isReady, isProcessing };\n};\n"],"names":["DEFAULT_SCRIPT_URL","useScript","useState","useRef","useCallback","normalizeConfig","normalizeResponse"],"mappings":"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"}
+{"version":3,"file":"useValuePay.js","sources":["../../../../src/hooks/useValuePay.ts"],"sourcesContent":["import { useCallback, useState, useRef } from \"react\";\r\nimport { useScript } from \"./useScript\";\r\nimport { normalizeConfig, normalizeResponse } from \"../utils/helpers\";\r\nimport { DEFAULT_SCRIPT_URL } from \"../utils/constants\";\r\nimport type { ValuePayConfig, UseValuePayReturn } from \"../types\";\r\n\r\n/**\r\n * Checks whether any callback function is provided in the config,\r\n * using case-insensitive detection to handle both SDK-style (onCallback)\r\n * and raw checkout-style (oncallback) casing.\r\n */\r\n// eslint-disable-next-line @typescript-eslint/no-explicit-any\r\nfunction hasCallback(cfg: any, ...names: string[]): boolean {\r\n  return names.some(\r\n    (name) => typeof cfg[name] === \"function\" || typeof cfg[name.toLowerCase()] === \"function\",\r\n  );\r\n}\r\n\r\n/**\r\n * Returns true if the config has ANY callback defined (case-insensitive).\r\n * When true, callbacks take precedence and redirectUrl is ignored.\r\n */\r\n// eslint-disable-next-line @typescript-eslint/no-explicit-any\r\nfunction hasAnyCallback(cfg: any): boolean {\r\n  return hasCallback(cfg, \"onSuccess\", \"onCallback\", \"onCancelled\", \"onClose\", \"onError\");\r\n}\r\n\r\n/**\r\n * Redirects the browser to the given URL with ref and status query params.\r\n */\r\nfunction redirectTo(redirectUrl: string, ref: string, status: string) {\r\n  const url = new URL(redirectUrl);\r\n  url.searchParams.set(\"ref\", ref);\r\n  url.searchParams.set(\"status\", status);\r\n  window.location.href = url.toString();\r\n}\r\n\r\nexport const useValuePay = (config: ValuePayConfig): UseValuePayReturn => {\r\n  const scriptUrl = config.scriptUrl || DEFAULT_SCRIPT_URL;\r\n  const isReady = useScript(scriptUrl);\r\n  const [isProcessing, setIsProcessing] = useState(false);\r\n  const configRef = useRef(config);\r\n  configRef.current = config;\r\n\r\n  const initialize = useCallback(\r\n    (overrides?: Partial<ValuePayConfig>) => {\r\n      const cfg = configRef.current;\r\n\r\n      if (typeof window === \"undefined\" || !window.ValuepayCheckout) {\r\n        cfg.onError?.(\r\n          new Error(\"ValuePay script not loaded. Ensure the script URL is accessible.\"),\r\n        );\r\n        return;\r\n      }\r\n\r\n      if (isProcessing) return;\r\n\r\n      setIsProcessing(true);\r\n\r\n      const normalized = normalizeConfig(cfg, overrides);\r\n      const ref = normalized.transactionRef;\r\n      const useRedirect = !hasAnyCallback(cfg) && !!cfg.redirectUrl;\r\n\r\n      window.ValuepayCheckout({\r\n        ...normalized,\r\n\r\n        // eslint-disable-next-line @typescript-eslint/no-explicit-any\r\n        onsuccess: (response: any) => {\r\n          const res = normalizeResponse(response, ref, cfg);\r\n          setIsProcessing(false);\r\n\r\n          if (useRedirect) {\r\n            redirectTo(cfg.redirectUrl!, res.ref, res.status);\r\n            return;\r\n          }\r\n\r\n          if (res.status !== \"SUCCESS\" && res.status !== \"COMPLETED\") {\r\n            res.status = \"SUCCESS\";\r\n          }\r\n          cfg.onSuccess?.(res);\r\n        },\r\n\r\n        // eslint-disable-next-line @typescript-eslint/no-explicit-any\r\n        oncallback: (response: any) => {\r\n          const res = normalizeResponse(response, ref, cfg);\r\n          setIsProcessing(false);\r\n\r\n          if (useRedirect) {\r\n            redirectTo(cfg.redirectUrl!, res.ref, res.status);\r\n            return;\r\n          }\r\n\r\n          cfg.onCallback?.(res);\r\n        },\r\n\r\n        // eslint-disable-next-line @typescript-eslint/no-explicit-any\r\n        onCancelled: (response: any) => {\r\n          const res = normalizeResponse(response, ref, cfg);\r\n          res.status = \"CANCELLED\";\r\n          setIsProcessing(false);\r\n\r\n          if (useRedirect) {\r\n            redirectTo(cfg.redirectUrl!, res.ref, \"CANCELLED\");\r\n            return;\r\n          }\r\n\r\n          cfg.onCancelled?.(res);\r\n        },\r\n\r\n        // eslint-disable-next-line @typescript-eslint/no-explicit-any\r\n        onAborted: (response: any) => {\r\n          const res = normalizeResponse(response, ref, cfg);\r\n          res.status = \"CANCELLED\";\r\n          setIsProcessing(false);\r\n          cfg.onCancelled?.(res);\r\n        },\r\n\r\n        // eslint-disable-next-line @typescript-eslint/no-explicit-any\r\n        onClosed: (response: any) => {\r\n          const res = normalizeResponse(response, ref, cfg);\r\n          setIsProcessing(false);\r\n\r\n          if (useRedirect) {\r\n            redirectTo(cfg.redirectUrl!, res.ref, \"CLOSED\");\r\n            return;\r\n          }\r\n\r\n          cfg.onClose?.(res);\r\n        },\r\n      });\r\n    },\r\n    // eslint-disable-next-line react-hooks/exhaustive-deps\r\n    [isReady, isProcessing],\r\n  );\r\n\r\n  return { initialize, isReady, isProcessing };\r\n};\r\n"],"names":["DEFAULT_SCRIPT_URL","useScript","useState","useRef","useCallback","normalizeConfig","normalizeResponse"],"mappings":"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"}

package/dist/cjs/index.js

@@ -12,5 +12,6 @@ exports.ValuePayButton = ValuePayButton.ValuePayButton;
 exports.ValuePayProvider = ValuePayProvider.ValuePayProvider;
 exports.useValuePay = useValuePay.useValuePay;
 exports.useScript = useScript.useScript;
+exports.ensureRefPrefix = helpers.ensureRefPrefix;
 exports.generateTransactionRef = helpers.generateTransactionRef;
 //# sourceMappingURL=index.js.map

package/dist/cjs/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sources":[],"sourcesContent":[],"names":[],"mappings":";;;;;;;;;;;;;;"}
+{"version":3,"file":"index.js","sources":[],"sourcesContent":[],"names":[],"mappings":";;;;;;;;;;;;;;;"}

package/dist/cjs/utils/helpers.js

@@ -13,12 +13,22 @@ const generateTransactionRef = (length = 20) => {
     }
     return result;
 };
+/**
+ * Ensure the transaction reference always carries the VPS_TX_ prefix.
+ * If the merchant supplies their own ref, the prefix is prepended (unless already present).
+ * If omitted, a fully random reference is generated.
+ */
+const ensureRefPrefix = (ref) => {
+    return ref.startsWith(constants.TRANSACTION_REF_PREFIX) ? ref : `${constants.TRANSACTION_REF_PREFIX}${ref}`;
+};
 /**
  * Normalize the SDK config into the shape expected by window.ValuepayCheckout.
  */
 const normalizeConfig = (config, overrides) => {
     const merged = { ...config, ...overrides };
-    const ref = merged.transactionRef || generateTransactionRef();
+    const ref = merged.transactionRef
+        ? ensureRefPrefix(merged.transactionRef)
+        : generateTransactionRef();
     return {
         public_key: merged.publicKey,
         transactionRef: ref,
@@ -61,6 +71,7 @@ const normalizeResponse = (raw, ref, config) => {
     };
 };
 
+exports.ensureRefPrefix = ensureRefPrefix;
 exports.generateTransactionRef = generateTransactionRef;
 exports.normalizeConfig = normalizeConfig;
 exports.normalizeResponse = normalizeResponse;

package/dist/cjs/utils/helpers.js.map

@@ -1 +1 @@
-{"version":3,"file":"helpers.js","sources":["../../../../src/utils/helpers.ts"],"sourcesContent":["import type { ValuePayConfig, ValuePayResponse } from \"../types\";\nimport { DEFAULT_CURRENCY, DEFAULT_CHANNELS, TRANSACTION_REF_PREFIX } from \"./constants\";\n\n/**\n * Generate a unique transaction reference.\n */\nexport const generateTransactionRef = (length: number = 20): string => {\n  const chars = \"ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789\";\n  let result = TRANSACTION_REF_PREFIX;\n  for (let i = 0; i < length; i++) {\n    result += chars.charAt(Math.floor(Math.random() * chars.length));\n  }\n  return result;\n};\n\n/**\n * Normalize the SDK config into the shape expected by window.ValuepayCheckout.\n */\nexport const normalizeConfig = (config: ValuePayConfig, overrides?: Partial<ValuePayConfig>) => {\n  const merged = { ...config, ...overrides };\n  const ref = merged.transactionRef || generateTransactionRef();\n\n  return {\n    public_key: merged.publicKey,\n    transactionRef: ref,\n    amount: merged.amount,\n    currency: merged.currency || DEFAULT_CURRENCY,\n    channels: merged.channels || DEFAULT_CHANNELS,\n    type: \"default\",\n    redirect_url: merged.redirectUrl,\n    metaData: merged.metaData,\n    customer: {\n      email: merged.customer.email,\n      fullName: merged.customer.fullName,\n      phone: merged.customer.phone,\n    },\n    customisedCheckout: merged.customization\n      ? {\n          title: merged.customization.title,\n          description: merged.customization.description,\n          logoLink: merged.customization.logoUrl,\n        }\n      : undefined,\n  };\n};\n\n/**\n * Normalize the raw ValuePay response into our SDK response shape.\n */\n// eslint-disable-next-line @typescript-eslint/no-explicit-any\nexport const normalizeResponse = (raw: any, ref: string, config: ValuePayConfig): ValuePayResponse => {\n  return {\n    ref: raw?.ref || raw?.reference || raw?.tx_ref || ref,\n    transactionRef: raw?.transactionRef || ref,\n    status: raw?.status || raw?.validation?.status || \"PENDING\",\n    amount: config.amount,\n    currency: config.currency || DEFAULT_CURRENCY,\n    customer: config.customer,\n    paymentMethod: raw?.paymentMethod,\n    validation: raw?.validation,\n    raw,\n  };\n};\n"],"names":["TRANSACTION_REF_PREFIX","DEFAULT_CURRENCY","DEFAULT_CHANNELS"],"mappings":"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"}
+{"version":3,"file":"helpers.js","sources":["../../../../src/utils/helpers.ts"],"sourcesContent":["import type { ValuePayConfig, ValuePayResponse } from \"../types\";\r\nimport { DEFAULT_CURRENCY, DEFAULT_CHANNELS, TRANSACTION_REF_PREFIX } from \"./constants\";\r\n\r\n/**\r\n * Generate a unique transaction reference.\r\n */\r\nexport const generateTransactionRef = (length: number = 20): string => {\r\n  const chars = \"ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789\";\r\n  let result = TRANSACTION_REF_PREFIX;\r\n  for (let i = 0; i < length; i++) {\r\n    result += chars.charAt(Math.floor(Math.random() * chars.length));\r\n  }\r\n  return result;\r\n};\r\n\r\n/**\r\n * Ensure the transaction reference always carries the VPS_TX_ prefix.\r\n * If the merchant supplies their own ref, the prefix is prepended (unless already present).\r\n * If omitted, a fully random reference is generated.\r\n */\r\nexport const ensureRefPrefix = (ref: string): string => {\r\n  return ref.startsWith(TRANSACTION_REF_PREFIX) ? ref : `${TRANSACTION_REF_PREFIX}${ref}`;\r\n};\r\n\r\n/**\r\n * Normalize the SDK config into the shape expected by window.ValuepayCheckout.\r\n */\r\nexport const normalizeConfig = (config: ValuePayConfig, overrides?: Partial<ValuePayConfig>) => {\r\n  const merged = { ...config, ...overrides };\r\n  const ref = merged.transactionRef\r\n    ? ensureRefPrefix(merged.transactionRef)\r\n    : generateTransactionRef();\r\n\r\n  return {\r\n    public_key: merged.publicKey,\r\n    transactionRef: ref,\r\n    amount: merged.amount,\r\n    currency: merged.currency || DEFAULT_CURRENCY,\r\n    channels: merged.channels || DEFAULT_CHANNELS,\r\n    type: \"default\",\r\n    redirect_url: merged.redirectUrl,\r\n    metaData: merged.metaData,\r\n    customer: {\r\n      email: merged.customer.email,\r\n      fullName: merged.customer.fullName,\r\n      phone: merged.customer.phone,\r\n    },\r\n    customisedCheckout: merged.customization\r\n      ? {\r\n          title: merged.customization.title,\r\n          description: merged.customization.description,\r\n          logoLink: merged.customization.logoUrl,\r\n        }\r\n      : undefined,\r\n  };\r\n};\r\n\r\n/**\r\n * Normalize the raw ValuePay response into our SDK response shape.\r\n */\r\n// eslint-disable-next-line @typescript-eslint/no-explicit-any\r\nexport const normalizeResponse = (raw: any, ref: string, config: ValuePayConfig): ValuePayResponse => {\r\n  return {\r\n    ref: raw?.ref || raw?.reference || raw?.tx_ref || ref,\r\n    transactionRef: raw?.transactionRef || ref,\r\n    status: raw?.status || raw?.validation?.status || \"PENDING\",\r\n    amount: config.amount,\r\n    currency: config.currency || DEFAULT_CURRENCY,\r\n    customer: config.customer,\r\n    paymentMethod: raw?.paymentMethod,\r\n    validation: raw?.validation,\r\n    raw,\r\n  };\r\n};\r\n"],"names":["TRANSACTION_REF_PREFIX","DEFAULT_CURRENCY","DEFAULT_CHANNELS"],"mappings":"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"}

package/dist/esm/components/ValuePayButton.js

@@ -1,11 +1,15 @@
 import { jsx } from 'react/jsx-runtime';
 import { useValuePay } from '../hooks/useValuePay.js';
 
-const ValuePayButton = ({ text, className, style, disabled, children, ...config }) => {
+const ValuePayButton = ({ text, className, style, containerStyle, containerClassName, disabled, children, ...config }) => {
     const { initialize, isReady, isProcessing } = useValuePay(config);
     const defaultText = `Pay \u20A6${config.amount.toLocaleString()} Now`;
     const buttonText = children || text || defaultText;
-    return (jsx("button", { type: "button", onClick: () => initialize(), disabled: disabled || !isReady || isProcessing, className: className, style: style, "aria-busy": isProcessing, "aria-label": typeof buttonText === "string" ? buttonText : "Pay Now", children: isProcessing ? "Processing..." : buttonText }));
+    const button = (jsx("button", { type: "button", onClick: () => initialize(), disabled: disabled || !isReady || isProcessing, className: className, style: style, "aria-busy": isProcessing, "aria-label": typeof buttonText === "string" ? buttonText : "Pay Now", children: isProcessing ? "Processing..." : buttonText }));
+    if (containerStyle || containerClassName) {
+        return (jsx("div", { style: containerStyle, className: containerClassName, "data-testid": "valuepay-button-container", children: button }));
+    }
+    return button;
 };
 
 export { ValuePayButton };

package/dist/esm/components/ValuePayButton.js.map

@@ -1 +1 @@
-{"version":3,"file":"ValuePayButton.js","sources":["../../../../src/components/ValuePayButton.tsx"],"sourcesContent":["import React from \"react\";\nimport { useValuePay } from \"../hooks/useValuePay\";\nimport type { ValuePayButtonProps } from \"../types\";\n\nexport const ValuePayButton: React.FC<ValuePayButtonProps> = ({\n  text,\n  className,\n  style,\n  disabled,\n  children,\n  ...config\n}) => {\n  const { initialize, isReady, isProcessing } = useValuePay(config);\n\n  const defaultText = `Pay \\u20A6${config.amount.toLocaleString()} Now`;\n  const buttonText = children || text || defaultText;\n\n  return (\n    <button\n      type=\"button\"\n      onClick={() => initialize()}\n      disabled={disabled || !isReady || isProcessing}\n      className={className}\n      style={style}\n      aria-busy={isProcessing}\n      aria-label={typeof buttonText === \"string\" ? buttonText : \"Pay Now\"}\n    >\n      {isProcessing ? \"Processing...\" : buttonText}\n    </button>\n  );\n};\n"],"names":["_jsx"],"mappings":";;;MAIa,cAAc,GAAkC,CAAC,EAC5D,IAAI,EACJ,SAAS,EACT,KAAK,EACL,QAAQ,EACR,QAAQ,EACR,GAAG,MAAM,EACV,KAAI;AACH,IAAA,MAAM,EAAE,UAAU,EAAE,OAAO,EAAE,YAAY,EAAE,GAAG,WAAW,CAAC,MAAM,CAAC;IAEjE,MAAM,WAAW,GAAG,CAAA,UAAA,EAAa,MAAM,CAAC,MAAM,CAAC,cAAc,EAAE,CAAA,IAAA,CAAM;AACrE,IAAA,MAAM,UAAU,GAAG,QAAQ,IAAI,IAAI,IAAI,WAAW;IAElD,QACEA,GAAA,CAAA,QAAA,EAAA,EACE,IAAI,EAAC,QAAQ,EACb,OAAO,EAAE,MAAM,UAAU,EAAE,EAC3B,QAAQ,EAAE,QAAQ,IAAI,CAAC,OAAO,IAAI,YAAY,EAC9C,SAAS,EAAE,SAAS,EACpB,KAAK,EAAE,KAAK,EAAA,WAAA,EACD,YAAY,EAAA,YAAA,EACX,OAAO,UAAU,KAAK,QAAQ,GAAG,UAAU,GAAG,SAAS,EAAA,QAAA,EAElE,YAAY,GAAG,eAAe,GAAG,UAAU,EAAA,CACrC;AAEb;;;;"}
+{"version":3,"file":"ValuePayButton.js","sources":["../../../../src/components/ValuePayButton.tsx"],"sourcesContent":["import React from \"react\";\r\nimport { useValuePay } from \"../hooks/useValuePay\";\r\nimport type { ValuePayButtonProps } from \"../types\";\r\n\r\nexport const ValuePayButton: React.FC<ValuePayButtonProps> = ({\r\n  text,\r\n  className,\r\n  style,\r\n  containerStyle,\r\n  containerClassName,\r\n  disabled,\r\n  children,\r\n  ...config\r\n}) => {\r\n  const { initialize, isReady, isProcessing } = useValuePay(config);\r\n\r\n  const defaultText = `Pay \\u20A6${config.amount.toLocaleString()} Now`;\r\n  const buttonText = children || text || defaultText;\r\n\r\n  const button = (\r\n    <button\r\n      type=\"button\"\r\n      onClick={() => initialize()}\r\n      disabled={disabled || !isReady || isProcessing}\r\n      className={className}\r\n      style={style}\r\n      aria-busy={isProcessing}\r\n      aria-label={typeof buttonText === \"string\" ? buttonText : \"Pay Now\"}\r\n    >\r\n      {isProcessing ? \"Processing...\" : buttonText}\r\n    </button>\r\n  );\r\n\r\n  if (containerStyle || containerClassName) {\r\n    return (\r\n      <div style={containerStyle} className={containerClassName} data-testid=\"valuepay-button-container\">\r\n        {button}\r\n      </div>\r\n    );\r\n  }\r\n\r\n  return button;\r\n};\r\n"],"names":["_jsx"],"mappings":";;;AAIO,MAAM,cAAc,GAAkC,CAAC,EAC5D,IAAI,EACJ,SAAS,EACT,KAAK,EACL,cAAc,EACd,kBAAkB,EAClB,QAAQ,EACR,QAAQ,EACR,GAAG,MAAM,EACV,KAAI;AACH,IAAA,MAAM,EAAE,UAAU,EAAE,OAAO,EAAE,YAAY,EAAE,GAAG,WAAW,CAAC,MAAM,CAAC;IAEjE,MAAM,WAAW,GAAG,CAAA,UAAA,EAAa,MAAM,CAAC,MAAM,CAAC,cAAc,EAAE,CAAA,IAAA,CAAM;AACrE,IAAA,MAAM,UAAU,GAAG,QAAQ,IAAI,IAAI,IAAI,WAAW;IAElD,MAAM,MAAM,IACVA,GAAA,CAAA,QAAA,EAAA,EACE,IAAI,EAAC,QAAQ,EACb,OAAO,EAAE,MAAM,UAAU,EAAE,EAC3B,QAAQ,EAAE,QAAQ,IAAI,CAAC,OAAO,IAAI,YAAY,EAC9C,SAAS,EAAE,SAAS,EACpB,KAAK,EAAE,KAAK,EAAA,WAAA,EACD,YAAY,EAAA,YAAA,EACX,OAAO,UAAU,KAAK,QAAQ,GAAG,UAAU,GAAG,SAAS,EAAA,QAAA,EAElE,YAAY,GAAG,eAAe,GAAG,UAAU,EAAA,CACrC,CACV;AAED,IAAA,IAAI,cAAc,IAAI,kBAAkB,EAAE;AACxC,QAAA,QACEA,GAAA,CAAA,KAAA,EAAA,EAAK,KAAK,EAAE,cAAc,EAAE,SAAS,EAAE,kBAAkB,iBAAc,2BAA2B,EAAA,QAAA,EAC/F,MAAM,EAAA,CACH;IAEV;AAEA,IAAA,OAAO,MAAM;AACf;;;;"}

package/dist/esm/hooks/useValuePay.js

@@ -3,6 +3,32 @@ import { useScript } from './useScript.js';
 import { normalizeConfig, normalizeResponse } from '../utils/helpers.js';
 import { DEFAULT_SCRIPT_URL } from '../utils/constants.js';
 
+/**
+ * Checks whether any callback function is provided in the config,
+ * using case-insensitive detection to handle both SDK-style (onCallback)
+ * and raw checkout-style (oncallback) casing.
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+function hasCallback(cfg, ...names) {
+    return names.some((name) => typeof cfg[name] === "function" || typeof cfg[name.toLowerCase()] === "function");
+}
+/**
+ * Returns true if the config has ANY callback defined (case-insensitive).
+ * When true, callbacks take precedence and redirectUrl is ignored.
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+function hasAnyCallback(cfg) {
+    return hasCallback(cfg, "onSuccess", "onCallback", "onCancelled", "onClose", "onError");
+}
+/**
+ * Redirects the browser to the given URL with ref and status query params.
+ */
+function redirectTo(redirectUrl, ref, status) {
+    const url = new URL(redirectUrl);
+    url.searchParams.set("ref", ref);
+    url.searchParams.set("status", status);
+    window.location.href = url.toString();
+}
 const useValuePay = (config) => {
     const scriptUrl = config.scriptUrl || DEFAULT_SCRIPT_URL;
     const isReady = useScript(scriptUrl);
@@ -21,24 +47,33 @@ const useValuePay = (config) => {
         setIsProcessing(true);
         const normalized = normalizeConfig(cfg, overrides);
         const ref = normalized.transactionRef;
+        const useRedirect = !hasAnyCallback(cfg) && !!cfg.redirectUrl;
         window.ValuepayCheckout({
             ...normalized,
             // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            onsuccess: (response) => {
+                var _a;
+                const res = normalizeResponse(response, ref, cfg);
+                setIsProcessing(false);
+                if (useRedirect) {
+                    redirectTo(cfg.redirectUrl, res.ref, res.status);
+                    return;
+                }
+                if (res.status !== "SUCCESS" && res.status !== "COMPLETED") {
+                    res.status = "SUCCESS";
+                }
+                (_a = cfg.onSuccess) === null || _a === void 0 ? void 0 : _a.call(cfg, res);
+            },
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
             oncallback: (response) => {
-                var _a, _b;
+                var _a;
                 const res = normalizeResponse(response, ref, cfg);
                 setIsProcessing(false);
-                if (cfg.redirectUrl) {
-                    const url = new URL(cfg.redirectUrl);
-                    url.searchParams.set("ref", res.ref);
-                    url.searchParams.set("status", res.status);
-                    window.location.href = url.toString();
+                if (useRedirect) {
+                    redirectTo(cfg.redirectUrl, res.ref, res.status);
                     return;
                 }
                 (_a = cfg.onCallback) === null || _a === void 0 ? void 0 : _a.call(cfg, res);
-                if (res.status === "SUCCESS" || res.status === "COMPLETED") {
-                    (_b = cfg.onSuccess) === null || _b === void 0 ? void 0 : _b.call(cfg, res);
-                }
             },
             // eslint-disable-next-line @typescript-eslint/no-explicit-any
             onCancelled: (response) => {
@@ -46,11 +81,8 @@ const useValuePay = (config) => {
                 const res = normalizeResponse(response, ref, cfg);
                 res.status = "CANCELLED";
                 setIsProcessing(false);
-                if (cfg.redirectUrl) {
-                    const url = new URL(cfg.redirectUrl);
-                    url.searchParams.set("ref", res.ref);
-                    url.searchParams.set("status", "CANCELLED");
-                    window.location.href = url.toString();
+                if (useRedirect) {
+                    redirectTo(cfg.redirectUrl, res.ref, "CANCELLED");
                     return;
                 }
                 (_a = cfg.onCancelled) === null || _a === void 0 ? void 0 : _a.call(cfg, res);
@@ -68,11 +100,8 @@ const useValuePay = (config) => {
                 var _a;
                 const res = normalizeResponse(response, ref, cfg);
                 setIsProcessing(false);
-                if (cfg.redirectUrl) {
-                    const url = new URL(cfg.redirectUrl);
-                    url.searchParams.set("ref", res.ref);
-                    url.searchParams.set("status", "CLOSED");
-                    window.location.href = url.toString();
+                if (useRedirect) {
+                    redirectTo(cfg.redirectUrl, res.ref, "CLOSED");
                     return;
                 }
                 (_a = cfg.onClose) === null || _a === void 0 ? void 0 : _a.call(cfg, res);

package/dist/esm/hooks/useValuePay.js.map

@@ -1 +1 @@
-{"version":3,"file":"useValuePay.js","sources":["../../../../src/hooks/useValuePay.ts"],"sourcesContent":["import { useCallback, useState, useRef } from \"react\";\nimport { useScript } from \"./useScript\";\nimport { normalizeConfig, normalizeResponse } from \"../utils/helpers\";\nimport { DEFAULT_SCRIPT_URL } from \"../utils/constants\";\nimport type { ValuePayConfig, UseValuePayReturn } from \"../types\";\n\nexport const useValuePay = (config: ValuePayConfig): UseValuePayReturn => {\n  const scriptUrl = config.scriptUrl || DEFAULT_SCRIPT_URL;\n  const isReady = useScript(scriptUrl);\n  const [isProcessing, setIsProcessing] = useState(false);\n  const configRef = useRef(config);\n  configRef.current = config;\n\n  const initialize = useCallback(\n    (overrides?: Partial<ValuePayConfig>) => {\n      const cfg = configRef.current;\n\n      if (typeof window === \"undefined\" || !window.ValuepayCheckout) {\n        cfg.onError?.(new Error(\"ValuePay script not loaded. Ensure the script URL is accessible.\"));\n        return;\n      }\n\n      if (isProcessing) return;\n\n      setIsProcessing(true);\n\n      const normalized = normalizeConfig(cfg, overrides);\n      const ref = normalized.transactionRef;\n\n      window.ValuepayCheckout({\n        ...normalized,\n\n        // eslint-disable-next-line @typescript-eslint/no-explicit-any\n        oncallback: (response: any) => {\n          const res = normalizeResponse(response, ref, cfg);\n          setIsProcessing(false);\n\n          if (cfg.redirectUrl) {\n            const url = new URL(cfg.redirectUrl);\n            url.searchParams.set(\"ref\", res.ref);\n            url.searchParams.set(\"status\", res.status);\n            window.location.href = url.toString();\n            return;\n          }\n\n          cfg.onCallback?.(res);\n\n          if (res.status === \"SUCCESS\" || res.status === \"COMPLETED\") {\n            cfg.onSuccess?.(res);\n          }\n        },\n\n        // eslint-disable-next-line @typescript-eslint/no-explicit-any\n        onCancelled: (response: any) => {\n          const res = normalizeResponse(response, ref, cfg);\n          res.status = \"CANCELLED\";\n          setIsProcessing(false);\n\n          if (cfg.redirectUrl) {\n            const url = new URL(cfg.redirectUrl);\n            url.searchParams.set(\"ref\", res.ref);\n            url.searchParams.set(\"status\", \"CANCELLED\");\n            window.location.href = url.toString();\n            return;\n          }\n\n          cfg.onCancelled?.(res);\n        },\n\n        // eslint-disable-next-line @typescript-eslint/no-explicit-any\n        onAborted: (response: any) => {\n          const res = normalizeResponse(response, ref, cfg);\n          res.status = \"CANCELLED\";\n          setIsProcessing(false);\n          cfg.onCancelled?.(res);\n        },\n\n        // eslint-disable-next-line @typescript-eslint/no-explicit-any\n        onClosed: (response: any) => {\n          const res = normalizeResponse(response, ref, cfg);\n          setIsProcessing(false);\n\n          if (cfg.redirectUrl) {\n            const url = new URL(cfg.redirectUrl);\n            url.searchParams.set(\"ref\", res.ref);\n            url.searchParams.set(\"status\", \"CLOSED\");\n            window.location.href = url.toString();\n            return;\n          }\n\n          cfg.onClose?.(res);\n        },\n      });\n    },\n    // eslint-disable-next-line react-hooks/exhaustive-deps\n    [isReady, isProcessing],\n  );\n\n  return { initialize, isReady, isProcessing };\n};\n"],"names":[],"mappings":"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"}
+{"version":3,"file":"useValuePay.js","sources":["../../../../src/hooks/useValuePay.ts"],"sourcesContent":["import { useCallback, useState, useRef } from \"react\";\r\nimport { useScript } from \"./useScript\";\r\nimport { normalizeConfig, normalizeResponse } from \"../utils/helpers\";\r\nimport { DEFAULT_SCRIPT_URL } from \"../utils/constants\";\r\nimport type { ValuePayConfig, UseValuePayReturn } from \"../types\";\r\n\r\n/**\r\n * Checks whether any callback function is provided in the config,\r\n * using case-insensitive detection to handle both SDK-style (onCallback)\r\n * and raw checkout-style (oncallback) casing.\r\n */\r\n// eslint-disable-next-line @typescript-eslint/no-explicit-any\r\nfunction hasCallback(cfg: any, ...names: string[]): boolean {\r\n  return names.some(\r\n    (name) => typeof cfg[name] === \"function\" || typeof cfg[name.toLowerCase()] === \"function\",\r\n  );\r\n}\r\n\r\n/**\r\n * Returns true if the config has ANY callback defined (case-insensitive).\r\n * When true, callbacks take precedence and redirectUrl is ignored.\r\n */\r\n// eslint-disable-next-line @typescript-eslint/no-explicit-any\r\nfunction hasAnyCallback(cfg: any): boolean {\r\n  return hasCallback(cfg, \"onSuccess\", \"onCallback\", \"onCancelled\", \"onClose\", \"onError\");\r\n}\r\n\r\n/**\r\n * Redirects the browser to the given URL with ref and status query params.\r\n */\r\nfunction redirectTo(redirectUrl: string, ref: string, status: string) {\r\n  const url = new URL(redirectUrl);\r\n  url.searchParams.set(\"ref\", ref);\r\n  url.searchParams.set(\"status\", status);\r\n  window.location.href = url.toString();\r\n}\r\n\r\nexport const useValuePay = (config: ValuePayConfig): UseValuePayReturn => {\r\n  const scriptUrl = config.scriptUrl || DEFAULT_SCRIPT_URL;\r\n  const isReady = useScript(scriptUrl);\r\n  const [isProcessing, setIsProcessing] = useState(false);\r\n  const configRef = useRef(config);\r\n  configRef.current = config;\r\n\r\n  const initialize = useCallback(\r\n    (overrides?: Partial<ValuePayConfig>) => {\r\n      const cfg = configRef.current;\r\n\r\n      if (typeof window === \"undefined\" || !window.ValuepayCheckout) {\r\n        cfg.onError?.(\r\n          new Error(\"ValuePay script not loaded. Ensure the script URL is accessible.\"),\r\n        );\r\n        return;\r\n      }\r\n\r\n      if (isProcessing) return;\r\n\r\n      setIsProcessing(true);\r\n\r\n      const normalized = normalizeConfig(cfg, overrides);\r\n      const ref = normalized.transactionRef;\r\n      const useRedirect = !hasAnyCallback(cfg) && !!cfg.redirectUrl;\r\n\r\n      window.ValuepayCheckout({\r\n        ...normalized,\r\n\r\n        // eslint-disable-next-line @typescript-eslint/no-explicit-any\r\n        onsuccess: (response: any) => {\r\n          const res = normalizeResponse(response, ref, cfg);\r\n          setIsProcessing(false);\r\n\r\n          if (useRedirect) {\r\n            redirectTo(cfg.redirectUrl!, res.ref, res.status);\r\n            return;\r\n          }\r\n\r\n          if (res.status !== \"SUCCESS\" && res.status !== \"COMPLETED\") {\r\n            res.status = \"SUCCESS\";\r\n          }\r\n          cfg.onSuccess?.(res);\r\n        },\r\n\r\n        // eslint-disable-next-line @typescript-eslint/no-explicit-any\r\n        oncallback: (response: any) => {\r\n          const res = normalizeResponse(response, ref, cfg);\r\n          setIsProcessing(false);\r\n\r\n          if (useRedirect) {\r\n            redirectTo(cfg.redirectUrl!, res.ref, res.status);\r\n            return;\r\n          }\r\n\r\n          cfg.onCallback?.(res);\r\n        },\r\n\r\n        // eslint-disable-next-line @typescript-eslint/no-explicit-any\r\n        onCancelled: (response: any) => {\r\n          const res = normalizeResponse(response, ref, cfg);\r\n          res.status = \"CANCELLED\";\r\n          setIsProcessing(false);\r\n\r\n          if (useRedirect) {\r\n            redirectTo(cfg.redirectUrl!, res.ref, \"CANCELLED\");\r\n            return;\r\n          }\r\n\r\n          cfg.onCancelled?.(res);\r\n        },\r\n\r\n        // eslint-disable-next-line @typescript-eslint/no-explicit-any\r\n        onAborted: (response: any) => {\r\n          const res = normalizeResponse(response, ref, cfg);\r\n          res.status = \"CANCELLED\";\r\n          setIsProcessing(false);\r\n          cfg.onCancelled?.(res);\r\n        },\r\n\r\n        // eslint-disable-next-line @typescript-eslint/no-explicit-any\r\n        onClosed: (response: any) => {\r\n          const res = normalizeResponse(response, ref, cfg);\r\n          setIsProcessing(false);\r\n\r\n          if (useRedirect) {\r\n            redirectTo(cfg.redirectUrl!, res.ref, \"CLOSED\");\r\n            return;\r\n          }\r\n\r\n          cfg.onClose?.(res);\r\n        },\r\n      });\r\n    },\r\n    // eslint-disable-next-line react-hooks/exhaustive-deps\r\n    [isReady, isProcessing],\r\n  );\r\n\r\n  return { initialize, isReady, isProcessing };\r\n};\r\n"],"names":[],"mappings":"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"}

package/dist/esm/index.js

@@ -2,5 +2,5 @@ export { ValuePayButton } from './components/ValuePayButton.js';
 export { ValuePayProvider } from './components/ValuePayProvider.js';
 export { useValuePay } from './hooks/useValuePay.js';
 export { useScript } from './hooks/useScript.js';
-export { generateTransactionRef } from './utils/helpers.js';
+export { ensureRefPrefix, generateTransactionRef } from './utils/helpers.js';
 //# sourceMappingURL=index.js.map

package/dist/esm/utils/helpers.js

@@ -11,12 +11,22 @@ const generateTransactionRef = (length = 20) => {
     }
     return result;
 };
+/**
+ * Ensure the transaction reference always carries the VPS_TX_ prefix.
+ * If the merchant supplies their own ref, the prefix is prepended (unless already present).
+ * If omitted, a fully random reference is generated.
+ */
+const ensureRefPrefix = (ref) => {
+    return ref.startsWith(TRANSACTION_REF_PREFIX) ? ref : `${TRANSACTION_REF_PREFIX}${ref}`;
+};
 /**
  * Normalize the SDK config into the shape expected by window.ValuepayCheckout.
  */
 const normalizeConfig = (config, overrides) => {
     const merged = { ...config, ...overrides };
-    const ref = merged.transactionRef || generateTransactionRef();
+    const ref = merged.transactionRef
+        ? ensureRefPrefix(merged.transactionRef)
+        : generateTransactionRef();
     return {
         public_key: merged.publicKey,
         transactionRef: ref,
@@ -59,5 +69,5 @@ const normalizeResponse = (raw, ref, config) => {
     };
 };
 
-export { generateTransactionRef, normalizeConfig, normalizeResponse };
+export { ensureRefPrefix, generateTransactionRef, normalizeConfig, normalizeResponse };
 //# sourceMappingURL=helpers.js.map

package/dist/esm/utils/helpers.js.map

@@ -1 +1 @@
-{"version":3,"file":"helpers.js","sources":["../../../../src/utils/helpers.ts"],"sourcesContent":["import type { ValuePayConfig, ValuePayResponse } from \"../types\";\nimport { DEFAULT_CURRENCY, DEFAULT_CHANNELS, TRANSACTION_REF_PREFIX } from \"./constants\";\n\n/**\n * Generate a unique transaction reference.\n */\nexport const generateTransactionRef = (length: number = 20): string => {\n  const chars = \"ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789\";\n  let result = TRANSACTION_REF_PREFIX;\n  for (let i = 0; i < length; i++) {\n    result += chars.charAt(Math.floor(Math.random() * chars.length));\n  }\n  return result;\n};\n\n/**\n * Normalize the SDK config into the shape expected by window.ValuepayCheckout.\n */\nexport const normalizeConfig = (config: ValuePayConfig, overrides?: Partial<ValuePayConfig>) => {\n  const merged = { ...config, ...overrides };\n  const ref = merged.transactionRef || generateTransactionRef();\n\n  return {\n    public_key: merged.publicKey,\n    transactionRef: ref,\n    amount: merged.amount,\n    currency: merged.currency || DEFAULT_CURRENCY,\n    channels: merged.channels || DEFAULT_CHANNELS,\n    type: \"default\",\n    redirect_url: merged.redirectUrl,\n    metaData: merged.metaData,\n    customer: {\n      email: merged.customer.email,\n      fullName: merged.customer.fullName,\n      phone: merged.customer.phone,\n    },\n    customisedCheckout: merged.customization\n      ? {\n          title: merged.customization.title,\n          description: merged.customization.description,\n          logoLink: merged.customization.logoUrl,\n        }\n      : undefined,\n  };\n};\n\n/**\n * Normalize the raw ValuePay response into our SDK response shape.\n */\n// eslint-disable-next-line @typescript-eslint/no-explicit-any\nexport const normalizeResponse = (raw: any, ref: string, config: ValuePayConfig): ValuePayResponse => {\n  return {\n    ref: raw?.ref || raw?.reference || raw?.tx_ref || ref,\n    transactionRef: raw?.transactionRef || ref,\n    status: raw?.status || raw?.validation?.status || \"PENDING\",\n    amount: config.amount,\n    currency: config.currency || DEFAULT_CURRENCY,\n    customer: config.customer,\n    paymentMethod: raw?.paymentMethod,\n    validation: raw?.validation,\n    raw,\n  };\n};\n"],"names":[],"mappings":"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"}
+{"version":3,"file":"helpers.js","sources":["../../../../src/utils/helpers.ts"],"sourcesContent":["import type { ValuePayConfig, ValuePayResponse } from \"../types\";\r\nimport { DEFAULT_CURRENCY, DEFAULT_CHANNELS, TRANSACTION_REF_PREFIX } from \"./constants\";\r\n\r\n/**\r\n * Generate a unique transaction reference.\r\n */\r\nexport const generateTransactionRef = (length: number = 20): string => {\r\n  const chars = \"ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789\";\r\n  let result = TRANSACTION_REF_PREFIX;\r\n  for (let i = 0; i < length; i++) {\r\n    result += chars.charAt(Math.floor(Math.random() * chars.length));\r\n  }\r\n  return result;\r\n};\r\n\r\n/**\r\n * Ensure the transaction reference always carries the VPS_TX_ prefix.\r\n * If the merchant supplies their own ref, the prefix is prepended (unless already present).\r\n * If omitted, a fully random reference is generated.\r\n */\r\nexport const ensureRefPrefix = (ref: string): string => {\r\n  return ref.startsWith(TRANSACTION_REF_PREFIX) ? ref : `${TRANSACTION_REF_PREFIX}${ref}`;\r\n};\r\n\r\n/**\r\n * Normalize the SDK config into the shape expected by window.ValuepayCheckout.\r\n */\r\nexport const normalizeConfig = (config: ValuePayConfig, overrides?: Partial<ValuePayConfig>) => {\r\n  const merged = { ...config, ...overrides };\r\n  const ref = merged.transactionRef\r\n    ? ensureRefPrefix(merged.transactionRef)\r\n    : generateTransactionRef();\r\n\r\n  return {\r\n    public_key: merged.publicKey,\r\n    transactionRef: ref,\r\n    amount: merged.amount,\r\n    currency: merged.currency || DEFAULT_CURRENCY,\r\n    channels: merged.channels || DEFAULT_CHANNELS,\r\n    type: \"default\",\r\n    redirect_url: merged.redirectUrl,\r\n    metaData: merged.metaData,\r\n    customer: {\r\n      email: merged.customer.email,\r\n      fullName: merged.customer.fullName,\r\n      phone: merged.customer.phone,\r\n    },\r\n    customisedCheckout: merged.customization\r\n      ? {\r\n          title: merged.customization.title,\r\n          description: merged.customization.description,\r\n          logoLink: merged.customization.logoUrl,\r\n        }\r\n      : undefined,\r\n  };\r\n};\r\n\r\n/**\r\n * Normalize the raw ValuePay response into our SDK response shape.\r\n */\r\n// eslint-disable-next-line @typescript-eslint/no-explicit-any\r\nexport const normalizeResponse = (raw: any, ref: string, config: ValuePayConfig): ValuePayResponse => {\r\n  return {\r\n    ref: raw?.ref || raw?.reference || raw?.tx_ref || ref,\r\n    transactionRef: raw?.transactionRef || ref,\r\n    status: raw?.status || raw?.validation?.status || \"PENDING\",\r\n    amount: config.amount,\r\n    currency: config.currency || DEFAULT_CURRENCY,\r\n    customer: config.customer,\r\n    paymentMethod: raw?.paymentMethod,\r\n    validation: raw?.validation,\r\n    raw,\r\n  };\r\n};\r\n"],"names":[],"mappings":"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"}

package/dist/types/index.d.ts

@@ -2,5 +2,5 @@ export { ValuePayButton } from "./components/ValuePayButton";
 export { ValuePayProvider } from "./components/ValuePayProvider";
 export { useValuePay } from "./hooks/useValuePay";
 export { useScript } from "./hooks/useScript";
-export { generateTransactionRef } from "./utils/helpers";
+export { generateTransactionRef, ensureRefPrefix } from "./utils/helpers";
 export type { ValuePayConfig, ValuePayResponse, ValuePayStatus, ValuePayCustomer, ValuePayCustomization, PaymentChannel, UseValuePayReturn, ValuePayButtonProps, ValuePayProviderProps, ValuePayProviderRef, } from "./types";

package/dist/types/types/index.d.ts

@@ -30,14 +30,21 @@ export interface ValuePayConfig {
     customer: ValuePayCustomer;
     currency?: string;
     channels?: PaymentChannel[];
+    /** Optional custom transaction reference. The VPS_TX_ prefix is auto-prepended if missing. Auto-generated when omitted. */
     transactionRef?: string;
+    /** Optional redirect URL after payment. Only used as a fallback when no callbacks (onSuccess, onCallback, onCancelled, onClose, onError) are provided. Callbacks always take precedence. */
     redirectUrl?: string;
     metaData?: Record<string, unknown>;
     customization?: ValuePayCustomization;
+    /** Called on successful payment. Use this OR `onCallback` — not both. When provided, this is passed as `onsuccess` to the checkout and only fires for successful transactions. */
     onSuccess?: (response: ValuePayResponse) => void;
+    /** Called when the user closes the checkout modal. */
     onClose?: (response: ValuePayResponse) => void;
+    /** Called when the user explicitly cancels the payment. */
     onCancelled?: (response: ValuePayResponse) => void;
+    /** General-purpose callback for ALL payment events (success, failure, etc.). Use this OR `onSuccess` — not both. When provided, this is passed as `oncallback` to the checkout and fires for every event. */
     onCallback?: (response: ValuePayResponse) => void;
+    /** Called on SDK-level errors (script load failure, etc.). */
     onError?: (error: Error) => void;
     scriptUrl?: string;
 }
@@ -52,10 +59,14 @@ export interface UseValuePayReturn {
 export interface ValuePayButtonProps extends ValuePayConfig {
     /** Button text override. Default: "Pay ₦{amount}" */
     text?: string;
-    /** Additional CSS class names */
+    /** Additional CSS class names for the button element */
     className?: string;
-    /** Additional inline styles */
+    /** Inline styles applied to the button element (text color, font, padding, etc.) */
     style?: CSSProperties;
+    /** Inline styles applied to the outer container div (width, height, margin, borders, radius, background, etc.) */
+    containerStyle?: CSSProperties;
+    /** Additional CSS class names for the outer container div */
+    containerClassName?: string;
     /** Disable the button */
     disabled?: boolean;
     /** Custom children override the default button text */

package/dist/types/utils/helpers.d.ts

@@ -3,6 +3,12 @@ import type { ValuePayConfig, ValuePayResponse } from "../types";
  * Generate a unique transaction reference.
  */
 export declare const generateTransactionRef: (length?: number) => string;
+/**
+ * Ensure the transaction reference always carries the VPS_TX_ prefix.
+ * If the merchant supplies their own ref, the prefix is prepended (unless already present).
+ * If omitted, a fully random reference is generated.
+ */
+export declare const ensureRefPrefix: (ref: string) => string;
 /**
  * Normalize the SDK config into the shape expected by window.ValuepayCheckout.
  */

package/package.json

@@ -1,13 +1,18 @@
 {
   "name": "@valuepay/react",
-  "version": "1.0.0",
+  "version": "2.1.0",
   "description": "Official React SDK for ValuePay payment gateway",
   "author": "Value Payment Solutions Limited",
   "license": "MIT",
   "main": "dist/cjs/index.js",
   "module": "dist/esm/index.js",
   "types": "dist/types/index.d.ts",
-  "files": ["dist", "README.md", "LICENSE", "CHANGELOG.md"],
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md"
+  ],
   "exports": {
     ".": {
       "import": "./dist/esm/index.js",