Payment components overview

InStore Add-On
Ask about this Page
Copy for LLM
View as Markdown

Understand how payment types, payment processors, and payment options work together in commercetools InStore.

Payment components

InStore payment components build on each other: a payment type defines the payment category and workflow, a payment processor defines the integration with a third-party service, and a payment option combines them into the payment method that colleagues use at checkout.

Payment types

A payment type defines a category of payment that InStore supports. InStore supports payment types for cash, credit (bank card), pay on account, digital wallet, stored-value cards, and custom payments.

The payment type establishes:

  • The workflow for processing that type of payment.
  • Required and optional parameter definitions.
  • Business rules and constraints.
  • User interface requirements.

You do not create or customize payment types directly. Instead, you select one of the supported payment types when you configure a payment processor and related payment options. In that configuration, you define the business rules and constraints for how the payment type is used.

GiftCard payment type

The GiftCard (or stored value) payment type accepts prepaid funds that are loaded onto a card or in a digital account. Purchases made using the GiftCard type do not require a direct, real-time bank or PSP connection.

This payment type supports stored value payments such as:

  • Stored value via PED: value is carried on a physical card, such as a stored-value card, whose unique ID must be retrieved through a PED or magnetic card reader (MCR). The device communicates with an external platform that provides the unique account ID (and the balance, if this is not stored on the card itself).
  • Stored value via scan or enter: value is carried on a physical card, such as a stored-value card, gift receipt, or return voucher, whose unique ID is barcode-scanned or typed into InStore by the store associate. These cards may require a PIN, such as a scratch-off code.
  • Retrieved stored value: payment is made from a balance that you maintain. The account can include earned benefits, refund vouchers, loyalty benefits, and more. The account is managed completely outside of InStore and requires retailer integration to obtain this information.
You can combine different methods in your payment process steps. For example, you can use one method to retrieve the card or account number and a different method to retrieve its balance. For more information about the GiftCard type and accepting stored value payments, contact your commercetools representative.

Composable tender extension

InStore uses the Custom payment type to accommodate bespoke or non-standard payment methods through composable tender extension functionality. These methods include redeemed rebates and coupons, payments through DTMF (Dual-Tone Multi-Frequency), customer-saved cards in an online account, trade-ins, empty-container-collection credit, and other tenders that you define. InStore can load a custom module that you provide.
You must develop and deploy an external module to communicate with your custom payment processor. Development of this module is outside the scope of commercetools. Your external module must be mountable by the InStore_Shell. When a user selects the custom tender during checkout, InStore loads the module to communicate with the processing service. Your module controls capturing and processing the custom payment and provides InStore with results (success or cancel). After the module task is complete, InStore persists the payment to your commercetools project as usual.
To keep the module compatible with InStore_Shell, configure webpack module federation with the expected remote name, remote entry file, exposed component, and shared React dependencies.
Sample ModuleFederationPlugin configurationJavascript
new ModuleFederationPlugin({
  name: 'InStore_CustomPayment',
  filename: 'remoteEntry.js',
  remotes: {},
  exposes: {
    './Component': './src/App',
  },
  shared: {
    // Other shared dependencies
    react: {
      singleton: true,
    },
    'react-dom': {
      singleton: true,
    },
  },
});
When you create the payment processor, set integrationConfiguration.url to the remote entry file URL and set integrationConfiguration.module to the exposed module key, such as ./Component.
Feedback from your processing service does not pass through InStore, other than success or cancel.

When you implement a custom payment module, keep these constraints in mind:

  • You must accurately pre-define in your commercetools payment type any custom fields you intend to pass with your custom payments. InStore attempts to apply them to the commercetools payment record at the end of the payment. If InStore cannot match custom fields to the payment type, the payment fails.
  • Do not manage routes within your custom payment module. Doing so can cause unintended effects in the InStore core modules and the hosting Shell application.
You can customize text strings for any payment option in the Custom section of the Tenant.translations API.

Payment processors

Payment processors handle the connection details for third-party payment service providers (PSPs). You use the InStore API to create a connection to each PSP. Your definition must contain the following:

  • Integration specifications based on your PSP requirements and payment flow.
  • Connection requirements for the integration endpoints you configure, such as URLs and authentication methods.
For sample payloads and field descriptions, see Build InStore payment components. For custom payment endpoints, see Set up payment extensions.

Payment options

Payment options are the payment methods that colleagues see during checkout. You create payment options that combine a payment type with a payment processor and add business-specific configuration.

Each payment option tells InStore:

  • What kind of payment this is (payment type).
  • How to process it (payment processor).
  • What to display (button order, icons, labels).
  • What transaction rules to apply (refund eligibility and split tender availability).
For example, when you create a payment option, set allowSplit to true to let one type of Bankcard coexist with other payment types. Set allowSplit to false for another type of Bankcard if it must cover the full checkout amount.
To display the payment options on the checkout screen, assign them to a location and optionally to a workstation.
To configure payment processors and payment options, see Build payment components.