Payment Services initialization

The Payment Services initializer provides configuration options for the backend endpoint and language definitions.

Version: 3.1.1

Configuration options

The following table describes the configuration options available for the Payment Services initializer:

Option	Type	Req?	Description
apiUrl	string	Yes	Adobe Commerce GraphQL endpoint URL (for example, https://example.com/graphql).
getCustomerToken	function	Yes	Provides authorization for GraphQL requests made on behalf of the shopper. For token-based auth, it must return a customer token (string) or null for guests. For session-based auth, it must be set to null.
storeViewCode	string	No	Adobe Commerce store view code used for GraphQL requests. If not set, the Store HTTP header is not included.
langDefinitions	object	No	Language definitions used for internationalization (i18n).

Default configuration

The initializer runs with these defaults when no configuration is provided:

import { initializers } from '@dropins/tools/initializer.js';
import { initialize } from '@dropins/storefront-payment-services';

// All configuration options are optional
await initializers.mountImmediately(initialize, {
  langDefinitions: {}, // Uses built-in English strings
  // Drop-in-specific defaults:
  // apiUrl: undefined // See configuration options above
  // getCustomerToken: undefined // See configuration options above
  // storeViewCode: undefined // See configuration options above
});

Language definitions

Override dictionary keys for localization or branding. The langDefinitions object maps locale keys to custom strings that override default text for the drop-in.

import { initializers } from '@dropins/tools/initializer.js';
import { initialize } from '@dropins/storefront-payment-services';

const customStrings = {
  "CreditCard": {
    "formFields": {
      "cvv": { "placeholder": "CVV*" },
      "expirationDate": { "placeholder": "MM/YY*" },
      "number": { "placeholder": "Card number*" }
    }
  },
};

const langDefinitions = {
  default: customStrings,
};

await initializers.mountImmediately(initialize, { langDefinitions });

Tip

For complete dictionary customization including all available keys and multi-language support, see the Payment Services Dictionary page.

Customizing data models

No customizable models are available for this drop-in.

Drop-in configuration

The Payment Services initializer provides options to configure the backend endpoint and language definitions.

import { fetchPlaceholders } from '../commerce.js';
import { getConfigValue } from '@dropins/tools/lib/aem/configs.js';
import { getCookie } from '@dropins/tools/lib.js';
import { initializers } from '@dropins/tools/initializer.js';

const initializeDropin = async () => {
  const labels = await fetchPlaceholders('placeholders/payment-services.json');
  const langDefinitions = {
    default: {
      ...labels,
    },
  };

  const coreEndpoint = await getConfigValue('commerce-core-endpoint');
  const getUserTokenCookie = () => getCookie('auth_dropin_user_token');

  return initializers.mountImmediately(initialize, {
    apiUrl: coreEndpoint,
    getCustomerToken: getUserTokenCookie,
    langDefinitions,
  });
};

await initializeDropin();

Note

Refer to the Configuration options table for detailed descriptions of each option.

Initialization is asynchronous

The Payment Services drop-in initializer is fully asynchronous. Even if mounted immediately, it initializes in the background and emits initialization updates via custom events.

Payment method availability

During asynchronous initialization, the Payment Services drop-in emits a series of events to indicate readiness across different locations. Each event includes a payload of { availablePaymentMethods: string[] }, listing the available payment method codes.

The following table contains the available event names and their descriptions:

Event name	Description
payment-services/initialized/checkout	Indicates the drop-in is initialized for the CHECKOUT location. The event.availablePaymentMethods property lists the payment methods available on the checkout page.
payment-services/initialized/product-detail	Indicates the drop-in is initialized for the PRODUCT_DETAIL location. The event.availablePaymentMethods property lists the payment methods available on the product detail page.

The following example demonstrates how to implement payment method availability event handlers for the checkout page.

import { PaymentMethodCode } from '@dropins/storefront-payment-services/api.js';
import { events } from '@dropins/tools/event-bus.js';

events.on('payment-services/initialized/checkout', ({ availablePaymentMethods }) => {
  if (availablePaymentMethods.contains(PaymentMethodCode.APPLE_PAY)) {
    console.log("Apple Pay available for checkout page.");
  }
  if (availablePaymentMethods.contains(PaymentMethodCode.CREDIT_CARD)) {
    console.log("Credit Card available for checkout page.");
  }
});