Install and configure the Stripe Payment Connector from Commercetools

Install and configure the connector from the Connect marketplace in your Commercetools storefront.

Before installing the Stripe Payment Connector:

Identify the organization and project in your Commercetools instance where you want to install the connector.
Prepare to configure and install the connector directly from your Commercetools instance.

Install the Stripe Payment Connector

Select the Stripe Payment Connector in the Commercetools Connect Marketplace within your Commercetools intance.
Connector listing in Commercetools project view
Choose the required region, project(s) and organization to install the Connector.
Commercetools project configuration
Enter your configuration details and Environment information
Environment Variables and connector configuration
Create a webhook in the Stripe Dashboard with a test transaction URL and make sure to copy the webhook signing secret.
This test transaction URL auto updates through a post-deploy script of the Payment Connector with the correct URL.

Configure the Stripe Payment Connector

CTP_PROJECT_KEY: The key of the Commercetools composable commerce project.
CTP_SCOPE: The scope constrains the endpoints to which the Commercetools client has access, as well as the read and write access right to an endpoint.
CTP_AUTH_URL: The URL for authentication in the Commercetools platform. It’s used to generate an OAuth 2.0 token which is required in every API call to Commercetools composable commerce. The default value is: https://auth.europewest1.gcp.commercetools.com.
CTP_API_URL: The URL for the Commercetools composable commerce API. The default value is: https://api.europe-west1.gcp.commercetools.com.
CTP_SESSION_URL: The URL for session creation in the Commercetools platform. Connectors rely on the session created to be able to share information between enabler and processor. The default value is: https://session.europewest1.gcp.commercetools.com.
CTP_JWKS_URL: The URL which provides JSON Web Key Set.
CTP_JWT_ISSUER: The issuer inside JSON Web Token which is required in JWT validation process.
STRIPE_CAPTURE_METHOD: The Stripe capture method (manual or automatic). The default value is: automatic.
STRIPE_APPEARANCE_PAYMENT_ELEMENT: Stripe Elements support visual customization, which allows you to match your site’s design with the appearance option. This value defines the specific appearance of the Payment Element component.
STRIPE_APPEARANCE_EXPRESS_CHECKOUT: Stripe Elements supports visual customization, which allows you to match the design of your site with the appearance option. This value has the specific appearance of the Express Checkout Element component.
CTP_CLIENT_SECRET: The client secret of Commercetools composable commerce user account. It’s used in the Commercetools client to communicate with Commercetools composable commerce through the SDK.
CTP_CLIENT_ID: The client ID of your Commercetools composable commerce user account. It’s used in Commercetools client to communicate with Commercetools composable commerce through SDK.
STRIPE_SECRET_KEY: Stripe authenticates your API requests using your account’s API keys. It is highly recommended to create a restricted access key for this and not use the default API Secret key
STRIPE_WEBHOOK_ID: Stripe’s unique identifier for webhook endpoints.
STRIPE_WEBHOOK_SIGNING_SECRET: Stripe’s secret key to verify webhook signatures using the official libraries. This key is created in the Stripe Dashboard.

The payment connector creates two main links:

Payment Connector JS Enabler Component: The URL where the payment components are embedded (for example, https://assets-{{uuid}}.assets.uscentral1.gcp.preview.commercetools.app/connector-enabler.es.js)
Payment Connector Processor: The URL where all webhooks are sent and transformed into payment transactions in Commercetools (for example, https://service-{{uuid}}.uscentral1.gcp.preview.commercetools.app)

Extend the payment integration

If you want to build and extend the existing payment integration to meet your specific needs:

Use the connector codebase available on GitHub.
Deploy the connector locally.
Update the .env configuration in both the processor and enabler.

By choosing this path, you’re responsible for the deployment and configuration of the connector.

General settings

You can modify the capture mode of components generated by the Payment Connector Enabler in the Payment Connector configuration (manual or automatic).
The Payment Connector Enabler manages the payment components connected to the Payment Connector processor.
The Payment Connector processor creates the Payment Intent in Stripe with the respective metadata and converts webhook events into payment transactions in Commercetools.
You can modify the appearance of the Stripe Payment Element and Express Checkout Element components from the Payment Connector configuration.

Webhooks

Stripe uses webhooks to notify your application when an event occurs in your account. Webhooks are useful for updating payment transactions when a customer’s bank confirms or declines a payment, or when the payment is canceled or refunded.

We support the following webhooks:

charge.succeeded: If the payment hasn’t been captured, create a new payment in Commercetools. If the payment is made, add a transaction “Authorization:Success” to it
payment_intent.succeeded: There are two ways to handle this event:
- Automatic capture method: If paymentIntent.capture_method is automatic, create a new payment in Commercetools and then add a “Charge:Success” transaction to it.
- Manual capture method: If paymentIntent.capture_method is manual, add a “Charge:Success” transaction to the payment in Commercetools.
charge.refunded: If charge.captured is true, add a “Refund:Success” transaction to the payment in Commercetools.
payment_intent.canceled: Add a “CancelAuthorization:Success” transaction to the payment in Commercetools.
payment_intent.payment_failed: Logs the information in the connector app inside the processor logs.
payment_intent.requires_action: Logs the information in the connector app inside the processor logs.