fix: prefill APM fields by canonical key and parse E.164 phone numbers

Prefilling an APM form via `initialData` had two problems.

Values were matched only against the payment method's own parameter key, so
the documented `initialData.phone_number` silently did nothing whenever a
payment method named the field something else (for example `customerPhone`),
leaving merchants to discover each one's internal parameter names. `email`
and `phone_number` now also match on the parameter's type, so the canonical
keys prefill on every payment method. An exact parameter-key match still
wins, so a specific field can be targeted or a canonical value overridden.

A phone number passed as an E.164 string was dropped into the national
number input whole, with the dialing code set to the first entry in the
available list. That selected the wrong country, left `+CC` inside the
number box and submitted a malformed value. The string is now split on a
longest-prefix match against the available dialing codes, falling back to
the browser-locale default when the country isn't offered.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

Author: roshan-gorasia-cko

src/apm/types.ts

@@ -37,12 +37,25 @@ module ProcessOut {
 
     export type Container = string | Element
 
+    /**
+     * Values used to prefill the payment method's form fields.
+     *
+     * `email` and `phone_number` are canonical: they match the field by type, so
+     * they work whatever the gateway names its own parameter. Any gateway
+     * parameter key can also be passed directly, and takes precedence over the
+     * canonical key for that type.
+     */
     export interface InitialData {
       email: string,
-      phone_number: {
-        dialing_code: string,
-        value: string,
-      }
+      /**
+       * Either an E.164 string ("+48123123123") or the split form, with the
+       * country given as a dialing code ("+48").
+       */
+      phone_number: string | {
+        dialing_code?: string,
+        value?: string,
+      },
+      [key: string]: unknown,
     }
 }
 

src/apm/utils.ts

@@ -46,6 +46,107 @@ module ProcessOut {
     return (match || dialing_codes[0]).value;
   }
 
+  /**
+   * Canonical `initialData` keys and the parameter type each one prefills.
+   *
+   * Payment methods name their own parameters, so a phone field can arrive as
+   * `customerPhone` rather than `phone_number`. Matching on type as well as on
+   * the raw key lets the documented canonical keys prefill on every payment
+   * method, without the merchant having to know each one's parameter names.
+   */
+  const CANONICAL_PREFILL_KEYS: Array<{ key: string, type: string }> = [
+    { key: 'email', type: 'email' },
+    { key: 'phone_number', type: 'phone' },
+  ]
+
+  /**
+   * Find the value in `initialData` that should prefill the given parameter.
+   * An exact key match wins, so a merchant can always target one specific
+   * gateway parameter (or override a canonical key); otherwise we fall back to
+   * the canonical key for the parameter's type.
+   */
+  export function resolvePrefilledValue(
+    initialData: object | undefined,
+    param: { key: string, type: string },
+  ): unknown {
+    if (!initialData) {
+      return undefined;
+    }
+
+    const data = initialData as Record<string, unknown>;
+
+    if (data[param.key] !== undefined && data[param.key] !== null) {
+      return data[param.key];
+    }
+
+    for (let i = 0; i < CANONICAL_PREFILL_KEYS.length; i++) {
+      const canonical = CANONICAL_PREFILL_KEYS[i];
+      if (canonical.type === param.type && data[canonical.key]) {
+        return data[canonical.key];
+      }
+    }
+
+    return undefined;
+  }
+
+  /**
+   * Coerce a prefilled phone value into the `{ dialing_code, value }` shape the
+   * phone field renders.
+   *
+   * Accepts the object form and a bare E.164 string (`"+48123123123"`). The
+   * string is split on a longest-prefix match against the gateway's own dialing
+   * codes so the right country is selected and only the national number lands
+   * in the input — otherwise the whole string ends up in the number box and the
+   * submitted value is malformed.
+   */
+  export function normalizePhoneValue(
+    value: unknown,
+    dialing_codes: Array<{ region_code: string, value: string }>,
+  ): { dialing_code: string, value: string } {
+    const defaultDialingCode = getDefaultDialingCode(dialing_codes);
+
+    if (isPlainObject(value)) {
+      // `number` is the key the phone field emits on input, so accept it too:
+      // a value read back off a `field-change` event can be fed straight in.
+      const object = value as { dialing_code?: string, value?: string, number?: string };
+      return {
+        dialing_code: object.dialing_code || defaultDialingCode,
+        value: digitsOnly(object.value || object.number || ''),
+      };
+    }
+
+    if (typeof value !== 'string') {
+      return { dialing_code: defaultDialingCode, value: '' };
+    }
+
+    // Strip separators the docs allow around an E.164 number ("+48 123 123 123").
+    const compact = value.replace(/[^\d+]/g, '');
+
+    if (compact.charAt(0) !== '+') {
+      return { dialing_code: defaultDialingCode, value: digitsOnly(compact) };
+    }
+
+    // Longest prefix first, so "+1" doesn't win over "+1242".
+    const matches = (dialing_codes || [])
+      .filter(code => code.value && compact.indexOf(code.value) === 0)
+      .sort((a, b) => b.value.length - a.value.length);
+
+    if (matches.length === 0) {
+      // The gateway doesn't offer this country. Keep the digits so the merchant
+      // sees what was passed rather than silently dropping it.
+      return { dialing_code: defaultDialingCode, value: digitsOnly(compact) };
+    }
+
+    return {
+      dialing_code: matches[0].value,
+      value: digitsOnly(compact.substring(matches[0].value.length)),
+    };
+  }
+
+  function digitsOnly(value: string): string {
+    return value.replace(/\D/g, '');
+  }
+
   /**
    * Simple hash function for content comparison (djb2 algorithm)
    * @param str - String to hash

src/apm/views/NextSteps.ts

@@ -37,18 +37,16 @@ module ProcessOut {
 
     state.values = forms.reduce((acc, form) => {
       form.parameters.parameter_definitions.forEach(param => {
-        // Check for prefilled data from initialData
-        const initialData = ContextImpl.context.initialData;
-        const prefilledValue = initialData && initialData[param.key];
+        // Check for prefilled data from initialData, by gateway parameter key or
+        // by canonical key for the parameter type (email, phone_number).
+        const prefilledValue = resolvePrefilledValue(ContextImpl.context.initialData, param);
 
         // If we have prefilled data, use it and exit early
         if (prefilledValue) {
-          // Special handling for phone numbers - convert string to expected object format
-          if (param.type === 'phone' && typeof prefilledValue === 'string') {
-            acc[param.key] = {
-              dialing_code: param.dialing_codes[0].value,
-              value: prefilledValue,
-            };
+          // Phone accepts an E.164 string or an object; both need splitting into
+          // the { dialing_code, value } shape the field renders.
+          if (param.type === 'phone') {
+            acc[param.key] = normalizePhoneValue(prefilledValue, param.dialing_codes);
           } else {
             acc[param.key] = prefilledValue;
           }

test/apm/prefill.test.ts

@@ -0,0 +1,158 @@
+import { describe, expect, it } from "vitest"
+import { loadApmUtils, FakeNavigator } from "../support/loadNamespace"
+
+type DialingCode = { region_code: string; value: string }
+
+const CODES: DialingCode[] = [
+  { region_code: "PL", value: "+48" },
+  { region_code: "GB", value: "+44" },
+  { region_code: "US", value: "+1" },
+  { region_code: "BS", value: "+1242" },
+]
+
+function normalizePhoneValue(
+  value: unknown,
+  dialingCodes: DialingCode[] = CODES,
+  navigator: FakeNavigator = { language: "en-GB" },
+): { dialing_code: string; value: string } {
+  return loadApmUtils(navigator).normalizePhoneValue(value, dialingCodes)
+}
+
+function resolvePrefilledValue(
+  initialData: object | undefined,
+  param: { key: string; type: string },
+): unknown {
+  return loadApmUtils({}).resolvePrefilledValue(initialData, param)
+}
+
+describe("normalizePhoneValue", () => {
+  it("splits a bare E.164 string into dialing code and national number", () => {
+    expect(normalizePhoneValue("+48123123123")).toEqual({
+      dialing_code: "+48",
+      value: "123123123",
+    })
+  })
+
+  it("ignores separators in an E.164 string", () => {
+    expect(normalizePhoneValue("+44 7700 900123")).toEqual({
+      dialing_code: "+44",
+      value: "7700900123",
+    })
+    expect(normalizePhoneValue("+44 (7700) 900-123")).toEqual({
+      dialing_code: "+44",
+      value: "7700900123",
+    })
+  })
+
+  it("prefers the longest matching dialing code", () => {
+    expect(normalizePhoneValue("+1242570000")).toEqual({
+      dialing_code: "+1242",
+      value: "570000",
+    })
+    expect(normalizePhoneValue("+12025550123")).toEqual({
+      dialing_code: "+1",
+      value: "2025550123",
+    })
+  })
+
+  it("falls back to the locale default when the gateway has no matching code", () => {
+    expect(normalizePhoneValue("+33612345678")).toEqual({
+      dialing_code: "+44",
+      value: "33612345678",
+    })
+  })
+
+  it("uses the locale default for a national-format string", () => {
+    expect(normalizePhoneValue("07700900123")).toEqual({
+      dialing_code: "+44",
+      value: "07700900123",
+    })
+  })
+
+  it("passes through the object form", () => {
+    expect(
+      normalizePhoneValue({ dialing_code: "+48", value: "123123123" }),
+    ).toEqual({ dialing_code: "+48", value: "123123123" })
+  })
+
+  it("accepts the `number` key the phone field emits on input", () => {
+    expect(
+      normalizePhoneValue({ dialing_code: "+48", number: "123123123" }),
+    ).toEqual({ dialing_code: "+48", value: "123123123" })
+  })
+
+  it("fills in the locale default when the object omits the dialing code", () => {
+    expect(normalizePhoneValue({ value: "7700900123" })).toEqual({
+      dialing_code: "+44",
+      value: "7700900123",
+    })
+  })
+
+  it("returns an empty number for a non-string, non-object value", () => {
+    expect(normalizePhoneValue(undefined)).toEqual({
+      dialing_code: "+44",
+      value: "",
+    })
+    expect(normalizePhoneValue(42)).toEqual({ dialing_code: "+44", value: "" })
+  })
+})
+
+describe("resolvePrefilledValue", () => {
+  it("matches the gateway parameter key exactly", () => {
+    expect(
+      resolvePrefilledValue(
+        { customerPhone: "+48123123123" },
+        { key: "customerPhone", type: "phone" },
+      ),
+    ).toBe("+48123123123")
+  })
+
+  it("matches the canonical key by parameter type", () => {
+    expect(
+      resolvePrefilledValue(
+        { phone_number: "+48123123123" },
+        { key: "customerPhone", type: "phone" },
+      ),
+    ).toBe("+48123123123")
+
+    expect(
+      resolvePrefilledValue(
+        { email: "a@b.com" },
+        { key: "customerEmail", type: "email" },
+      ),
+    ).toBe("a@b.com")
+  })
+
+  it("prefers an exact key match over the canonical key", () => {
+    expect(
+      resolvePrefilledValue(
+        { phone_number: "+48123123123", customerPhone: "+441234567890" },
+        { key: "customerPhone", type: "phone" },
+      ),
+    ).toBe("+441234567890")
+  })
+
+  it("does not apply a canonical key to an unrelated parameter type", () => {
+    expect(
+      resolvePrefilledValue(
+        { phone_number: "+48123123123" },
+        { key: "documentNumber", type: "text" },
+      ),
+    ).toBeUndefined()
+  })
+
+  it("returns undefined when there is nothing to prefill", () => {
+    expect(
+      resolvePrefilledValue({}, { key: "customerPhone", type: "phone" }),
+    ).toBeUndefined()
+    expect(
+      resolvePrefilledValue(undefined, { key: "customerPhone", type: "phone" }),
+    ).toBeUndefined()
+  })
+
+  it("keeps falsy-but-present exact values distinguishable from absent ones", () => {
+    expect(
+      resolvePrefilledValue({ agreed: false }, { key: "agreed", type: "boolean" }),
+    ).toBe(false)
+  })
+})