Payment components overview

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, gift cards (including stored value), 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 gift 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 gift 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.

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.