Payment Connectors and Applications

Payment Connectors

A payment Connector manages the communication between the seller, Checkout, and the payment service provider (PSP). Checkout supports both Public Connectors and Organization Connectors (also called private Connectors) of type Payment Service Providers available in the Connect marketplace.

Public Connectors are available for all Composable Commerce projects, while Organization Connectors are Connectors that you can develop specifically for your Organization. To develop an Organization Connector as your payment Connector, you can use this payment integration template.

Payment Connectors determine which Payment Integration Types are available for each PSP.

Before creating and configuring your Applications, you must install at least one Connector from commercetools Connect because payment Connectors are required to set the Payment Integration Type and payment methods for the Application.

Payment Integration Types

Payment Integration Types determine how Checkout renders the payment methods on the Checkout page of a specific Application. Checkout supports two Payment Integration Types: web components and drop-in.

The Payment Integration Types available for an Application depend on the payment Connector. If both types are available, only one can be active at a time, but you can set both up and switch between them as needed.

Web components

With the web components Payment Integration Type, each payment method is rendered on the Checkout page through a dedicated UI component.

This Payment Integration Type gives you flexibility and control over the UI because you can set payment method predicates, use the Merchant Center to define the order payment methods appear on the page, and customize the labels and descriptions of the payment methods. Checkout supports specific payment methods with this Payment Integration Type.

Drop-in BETA

With the drop-in Payment Integration Type, payment methods are rendered on the Checkout page through a single pre-built UI element containing all methods.

With the drop-in type, the rendering of payment methods on the Checkout page totally depends on the PSP and on your PSP account settings. For example, you cannot use payment method predicates nor customize the labels and descriptions of the payment methods.

Supported PSPs, Payment Integration Types, and payment methods

The following PSPs have Public Connectors available in the Connect marketplace.

Each PSP provides specific Payment Integration Types that you can set for your Applications to make the related payment methods available to your customers.

If you want to use custom PSPs and payment methods, you must create and install Organization Connectors based on this payment integration template.

Sample payment Connector

For test purposes and proofs of concepts, you can use a sample payment Connector that supports credit card, invoice, and purchase order as a payment method. You can install the sample payment Connector from the Connect marketplace.

To simulate payments by credit card using the sample payment Connector, enter the following details in the checkout form.

• Card number:
  • Visa: 4111111111111111
  • Mastercard: 5555555555554444
  • American Express: 341925950237632
• Expiry date: any future date
• CVC/CVV: any three or four digit-number
• Name on card: any text

Applications

An Application lets you set a specific configuration for Checkout, such as country-specific or brand-specific checkout flows.

When creating an Application, you can configure some general settings, the user agreements, and the Payment Integrations.

Based on your business needs, you can create multiple Applications. For example, if you need different settings for different countries, you can create multiple Applications and set up user agreements, Payment Integrations, and other settings for each country.

Depending on the Checkout mode you are using, you can create two types of Applications:

• Complete Checkout: you can configure the general settings, activate the discount code functionality, add user agreements, and add payment methods.

• Payment Only BETA: you can configure only the general settings and add payment methods.

You can create Applications of different types for the same Project.

Payment Integrations

A Payment Integration represents an Application configuration that combines the payment Connector, the Payment Integration Type, and the payment method.

For example, you can set a Payment Integration for your Application to use the Adyen payment Connector, the web components Payment Integration Type, and the credit card, PayPal, and Google Pay payment methods.

You can set multiple Payment Integrations for an Application.

Create a Complete Checkout Application

1. In the Merchant Center main menu, select Checkout > Add application.

2. On the Add application page, click Add complete checkout.

3. On the Add application: Complete checkout page, follow these steps:

   1. In the General information section, do the following:

      • In Application name, enter a plain-text name for the Application.
      • In Application key, enter a unique identifier that contains 2-256 alphanumeric characters and special characters _-.
      • Optional: In Application description, enter a plain-text description for the Application.

   2. In the Application settings section, do the following:

      • In Logo URL, enter a valid URL of the logo that will be visible on your checkout page.

      • From Select countries, select the countries where the Application will be available.

      • In Origin URLs, enter the URLs of websites for which you want to use the Application. Only the provided URLs can use Checkout.

        URLs must match the following pattern /^(https?:\/\/)?(([a-zA-Z0-9-]+\.)+[a-zA-Z]{2,})\b(?::\d+)?(?!\/)$/i.
        For example, https://www.example.com or https://example.com:8080.

      • In Payment return URL, enter the URL to redirect customers to after they complete the payment.

      • To display the field for entering discount codes on your checkout page, keep the Activation of discount code function toggle in the activated position. Otherwise, deactivate it.

4. Click Save.

5. To add a user agreement, follow these steps:

   1. In the User agreement tab, click Add agreement and do the following:

      • In User agreement name, enter a plain-text name for the user agreement.
      • In User agreement text, enter the text for the user agreement that can include corresponding links (for example, terms and conditions).
      • From User agreement method, select if a mandatory checkbox should be displayed for the user agreement.

   2. Click Save. The order of user agreements in the list will be the same as displayed on your checkout page. To change the order, click Reorder, drag the agreements, and click Save.

   By default, user agreements are deactivated on creation. To activate the user agreement, click the Status toggle.

6. To add a Payment Integration, follow these steps:

   1. In the Payments tab, click Add payments and do the following:

      • From Payment connector, select the payment Connector that you installed from the Connect marketplace and that you want to use for the Payment Integration.

      • From Specification of the payments integration, select the Payment Integration Type you want to set up. If the selected payment Connector supports only one Payment Integration Type, the type will be preselected.

      • Depending on the Payment Integration Type, do the following:

        • If you selected Web components:
          • From Payment method, select the payment method that you want to activate.
          • In Payment method name, enter a name for the payment method. It will be displayed only in the Merchant Center.
          • Optional: In Payment method conditions via predicates BETA, enter the payment method predicate to determine the conditions for displaying the payment method. Leave the field empty to always display the payment method.
          • Optional: In Payment integration key BETA, enter a unique identifier that contains 2-256 alphanumeric characters and special characters _-. You need this key if you are using the Checkout Transactions API.
          • Click Save. A Payment integration ID BETA is generated automatically. You need this ID if you are using the Checkout Transactions API.
            Also, the first Payment Integration on the list will be the default Payment Integration on your checkout page. To change the order, click Manage order of payment methods (frontend), drag the payment methods into the desired order, and click Save.
        • If you selected Drop-in BETA:
          • In Drop-in integration name BETA, enter a name for the Payment Integration. It will be displayed only in the Merchant Center
          • Optional: In Payment integration key BETA, enter a unique identifier that contains between 2 and 256 alphanumeric characters and special characters _-. You need this key if you are using the Checkout Transactions API.
          • Click Save. A Payment integration ID BETA is generated automatically. You need this ID if you are using the Checkout Transactions API.
   By default, Payment Integrations are deactivated on creation. To activate the Payment Integration, click the Status toggle.

7. To activate the Application, click the Status toggle.

Create a Payment Only Application BETA

1. In the Merchant Center main menu, select Checkout > Add application.

2. On the Add application page, click Add payment only.

3. On the Add application: Payment only page, follow these steps:

   1. In the General information section, do the following:

      • In Application name, enter a plain-text name for the Application.
      • In Application key, enter a unique identifier that contains 2-256 alphanumeric characters and special characters _-.
      • Optional: In Application description, enter a plain-text description for the Application.

   2. In the Application settings section, do the following:

      • From Select countries, select the countries where the Application will be available.

      • In Origin URLs, enter the URLs of websites for which you want to use the Application. Only the provided URLs can use Checkout.

        URLs must match the following pattern /^(https?:\/\/)?(([a-zA-Z0-9-]+\.)+[a-zA-Z]{2,})\b(?::\d+)?(?!\/)$/i.
        For example, https://www.example.com or https://example.com:8080.

      • In Payment return URL, enter the URL to redirect customers to after they complete the payment.

4. Click Save.

5. To add a Payment Integration, follow these steps:

   1. In the Payments tab, click Add payments and do the following:

      • From Payment connector, select the payment Connector that you installed from the Connect marketplace and that you want to use for the Payment Integration.

      • From Specification of the payments integration, select the Payment Integration Type you want to set up. If the selected payment Connector supports only one Payment Integration Type, the type will be preselected.

      • Depending on the Payment Integration Type, do the following:

        • If you selected Web components:
          • From Payment method, select the payment method that you want to activate.
          • In Payment method name, enter a name for the payment method. It will be displayed only in the Merchant Center.
          • Optional: In Payment method conditions via predicates BETA, enter the payment method predicate to determine the conditions for displaying the payment method. Leave the field empty to always display the payment method.
          • Optional: In Payment integration key BETA, enter a unique identifier that contains 2-256 alphanumeric characters and special characters _-. You need this key if you are using the Checkout Transactions API.
          • Click Save. A Payment integration ID BETA is generated automatically. You need this ID if you are using the Checkout Transactions API.
            Also, the first Payment Integration on the list will be the default Payment Integration on your checkout page. To change the order, click Manage order of payment methods (frontend), drag the payment methods into the desired order, and click Save.
        • If you selected Drop-in BETA:
          • In Drop-in integration name BETA, enter a name for the Payment Integration. It will be displayed only in the Merchant Center
          • Optional: In Payment integration key BETA, enter a unique identifier that contains between 2 and 256 alphanumeric characters and special characters _-. You need this key if you are using the Checkout Transactions API.
          • Click Save. A Payment integration ID BETA is generated automatically. You need this ID if you are using the Checkout Transactions API.
   By default, Payment Integrations are deactivated on creation. To activate the Payment Integration, click the Status toggle.

6. To activate the Application, click the Status toggle.

Edit and delete an Application

To edit or delete an Application, select Checkout > Overview in the Merchant Center main menu. From the List of applications tab, you can manage Applications:

• To edit an Application, select it and edit the information on the settings page.
• To delete an Application, select it and click the Delete application icon on the settings page.