Documentation

Payment integration template

Elevate, May 20-22-2025, Miami Beach, Florida

Learn how to integrate a payments system in Composable Commerce.

Connect application templates are for development purposes. They require further customization before being used in production projects.

Composable Commerce allows integration with multiple Payment Service Providers (PSP) through Payments and Checkout.
Our payment integration template serves as a foundation for building and customizing a payment Connector based on your specific needs. To complete the integration, you only need to implement the final API calls to the selected PSP. The payment integration template follows best practices and is compatible with Checkout.

The payment integration template performs the following:

  • Communicates with the PSP to authorize, capture, cancel, and refund payments.
  • Communicates with Composable Commerce to keep payment transactions up to date.
  • Listens to payment events asynchronously and updates payment transactions accordingly.
  • Exposes frontend capabilities to safely capture payment information related to the selected payment method, ensuring compliance with data protection standards.
By aligning the payment connector with Checkout, we promote the decoupling of payments from other domains. This separation opens the door to other integration opportunities seamlessly, such as, Order Management Systems or Tax Calculation Systems.

Implementation

Creating an Order from a Cart and recalculating or updating Cart information not related to the payment is not in the scope of the payment integration template. The main reason for that is to align on Checkout principles to promote an ecosystem of Connectors that works interchangeably.

The two applications within the payment integration template are the enabler and processor. They can be hosted on Connect or on alternative platforms, and can be used together with Checkout or in custom frontend applications.

The following diagram represents the architecture using this payment integration template within commercetools.

Loading...

The frontend is integrated with the payment Connector to handle payment interactions initiated by customers. These interactions trigger payment operations, which the Connector then routes to the PSP.

During the checkout, and throughout the order fulfillment process, Checkout ensures that all actions are communicated to the payment connector based on business configurations. This approach keeps cart management and other operational domains independent, ensuring the payment connector is not directly responsible for cart-to-order conversion.

Enabler application

The enabler application delivers a frontend library created on top of the PSP-provided UI components (drop-in or web components) via HTTP static assets. This implementation provides a way for rendering payment methods based on Checkout customer configuration. The enabler application is also suitable for direct integration in custom frontend applications for initiating a payment through the processor application.

Whether used with Checkout or within a custom frontend, the enabler application ensures the safe handling of sensitive data, reducing Payment Card Industry (PCI) compliance obligations.

The current template implementation uses primary account number data to mock a payment method. It is not recommended to deal with sensitive data directly and rather rely on tokenization and encryption provided by the PSP.

Processor application

The processor application orchestrates payment operations with the PSP by handling initial payment interactions from users. It receives user commands to initiate payment transactions within commercetools Composable Commerce and listens for payment-related messages asynchronously to manage the lifecycle of each payment transaction in an eventual consistency model.

While initial payment interactions might typically come from the enabler application, other sources may initiate them using the Payment Intents API from Checkout. The processor application exposes additional API endpoints for initiating the capture, refund, and cancellation transactions, promoting this way, interoperability with other Checkout compatible connectors.

Best practices

Idempotency

Idempotency in payment operations ensures that making the same request multiple times has the same effect as making it once. When a customer submits a payment, various issues such as network latency, server errors, or user impatience can lead to multiple submissions of the same payment request. Idempotency ensures that only one transaction is processed, preventing multiple charges or inconsistent states.

Fault tolerance

During payment processing, errors are inevitable and will happen. Building fault tolerance into the integration process means that when errors occur, the system can recover without affecting the overall payment experience. It is crucial to identify all points of failure that could lead to an inconsistent state or unexpected conditions.

PCI compliance

Familiarize yourself with Payment Card Industry Data Security Standards (PCIDSS) and determine the compliance level your integration requires. You should implement practices to reduce the amount of sensitive data you handle, and use tokenization and encryption to protect card details, and leverage on the PSP to handle critical operations.

Validate incoming requests

Always authenticate and verify the source of incoming webhook requests. Use security tokens or signatures provided by your PSP to ensure that the incoming messages are legitimate. Your webhook endpoint must be secured with HTTPS.

Design for failure

Understand that inconsistencies will occur and design your system to handle them. Record details of transactions and errors. Logs should include timestamps, error messages, and transaction IDs (without storing sensitive data). This information is crucial for debugging and resolving issues.

Error handling

Implement robust error handling in your implementation to manage failures and comply with retry mechanisms from commercetools and the PSP. This is crucial for delivery guarantees in event processing for reporting success and failure.

Handling duplicates

In some cases it is possible that you receive the same webhook event twice, so make sure that your system is able to deal with duplicates.

Do not autocomplete values

When creating a form for payments, you should switch off the browser's autocomplete feature to prevent it from remembering credit card information. You can do this by including autocomplete="off" in your form or individual input fields.

Ensure fast webhook responses

Ensure your endpoint acknowledges incoming requests by returning a 2xx success status code immediately after persisting the result of the event to avoid timeouts on the PSP.

Retry outgoing requests

Implement retries for outgoing requests using an HTTP client. Ensure the client is configured with a retry mechanism that employs exponential backoff policies.

Testing

Beyond basic success cases, test your integration for various failure scenarios, such as declined transactions, network failures, and server errors. Ensure your system handles these without ending up with inconsistent data.

It is highly recommended to develop unit tests that ensure each part of your code is tested in isolation, allowing to verify its correctness, functionality, and reliability. Follow our guide for testing an event application locally.

Conclusion

This guide has outlined the architecture of our payment integration template and best practices. Integrating commercetools with PSPs requires careful consideration of idempotency, data consistency, fault tolerance, and resiliency. By using the payment integration template as a starting point, you can build a payments Connector which can effectively manage payment transactions, and ensure compliance with industry standards.

Remember that leveraging on commercetools to handle all payment transactions opens other integration possibilities, such as order fulfillment, or inventory management services in a totally decoupled way. Other integrations domains might rely on commercetools Payments subscriptions to proceed with other processes.