Standalone module

Payment features and capabilities

Explore comprehensive payment capabilities including Payment Only mode, payment methods, integration features, and processing enhancements.

Ask about this Page
Copy for LLM
View as Markdown

After completing this page, you should be able to:

  • Configure multiple shipping methods in Payment Only mode for flexible fulfillment scenarios.

  • Identify new payment methods available through Adyen including Venmo, Afterpay, and Clearpay for different markets.

  • Configure gift card connectors and implement gift card event handling using the Browser SDK.

  • Understand the requirements for combining gift cards with other payment methods for partial payments.

  • Use the merchantReference field to link payments with internal business systems for improved reconciliation.

  • Customize payment method appearance including names, descriptions, icons, and button text in the Merchant Center.

  • Configure URL communication settings appropriately for test and production environments.

  • Use the transactionId field to refund specific capture transactions in multi-capture payment scenarios.

2025 brought substantial evolution to Checkout's payment capabilities, from foundational mode enhancements through new payment methods to advanced integration and processing features. This page covers the complete spectrum of payment improvements that enable you to build flexible, robust checkout experiences.

Payment Only mode evolution

Payment Only mode underwent significant enhancements in 2025, evolving from a public beta feature to a production-ready solution.

Support for multiple Shipping Methods

In January 2025, Payment Only mode gained support for multiple Shipping Methods in public beta. This enhancement allows customers to select different shipping methods for different items or groups of items in their cart, enabling use cases like picking up some items in-store while having others delivered, offering express shipping for urgent items and standard shipping for others, and combining digital and physical products in a single order.

General availability

In February 2025, Payment Only mode achieved general availability status, signifying production-ready status with full enterprise support, stable API contracts, comprehensive documentation, and SLA coverage.

Payment methods and Connectors

The payment options available through Checkout expanded significantly in 2025, giving you more ways to meet your customers' payment preferences.

New payment methods via Adyen

Checkout enabled the addition of several popular payment methods via Adyen throughout the year:

  • Venmo arrived in June 2025, bringing mobile payment capabilities that resonate with US consumers. This mobile-first payment option provides a quick, familiar checkout experience for the many customers who already use Venmo for peer-to-peer payments.
  • Afterpay launched in July 2025, introducing buy-now-pay-later (BNPL) functionality that splits purchases into interest-free installments. This payment method appeals to budget-conscious shoppers and has been shown to help increase average order values by making larger purchases more accessible.
  • Clearpay was added in September 2025, bringing the same BNPL capabilities to UK and European markets. As Afterpay's localized brand for these regions, Clearpay provides the familiar installment payment experience with appropriate regional branding and market positioning.
Additional new payment methods were also released through Adyen during the year. The exact methods available to you depend on your geographic market and the specific terms of your Adyen contract.

Gift card Connectors

Gift card Connectors were introduced in March 2025 in public beta, enabling you to accept gift cards as a payment option in your checkout flow. The Connectors support several important capabilities: checking gift card balances in real-time, applying gift card value toward purchases, handling partial payments where a gift card covers part of the total with another payment method covering the remainder, and applying multiple gift cards to a single transaction when customers want to combine balances.

When implementing gift card functionality, keep in mind that gift card Payment Integrations should always be configured alongside other Payment Integrations. This setup ensures that when customers pay with a gift card that has insufficient balance to cover the full cart total, they can seamlessly select an alternative payment method to cover the difference—creating a smooth checkout experience even when gift card balances fall short.

To help you build responsive gift card experiences, Checkout introduced several gift card specific messages in April 2025. These messages allow you to subscribe to gift card events through the Browser SDK, following the same subscription pattern you'd use for other Checkout messages:
Gift card specific messagesjavascript
import { checkoutFlow } from '@commercetools/checkout-browser-sdk';

checkoutFlow({
  projectKey: '{projectKey}',
  region: '{region}',
  sessionId: '{sessionId}',
  onInfo: (message) => {
    switch (message.code) {
      case 'gift_card_balance_started':
        console.log('Gift card balance check started');
        break;
      case 'gift_card_balance_success':
        const { amount, isBalanceSufficient } = message.payload;
        console.log('Gift card balance:', amount, 'Sufficient:', isBalanceSufficient);
        break;
      case 'gift_card_redeem_success':
        console.log('Gift card redeemed successfully');
        break;
    }
  },
  onError: (message) => {
    if (message.code === 'gift_card_balance_error') {
      console.error('Gift card balance check failed');
    } else if (message.code === 'gift_card_redeem_error') {
      console.error('Gift card redemption failed');
    }
  }
});
For complete Message structure and all available gift card Messages, see the Message subscription and logging documentation and the Gift Card Messages documentation.

Payment integration features

Checkout received several enhancements throughout 2025 focused on giving you greater flexibility in how you integrate, customize, and manage payment functionality.

Merchant reference field

In January 2025, a merchantReference field was added to payment intent actions, providing a way to attach custom reference information directly to your payment service provider (PSP). This field is particularly useful for tracking internal order numbers or identifiers, linking invoice numbers to payments, associating payments with external systems, and including metadata that simplifies reconciliation processes.
The merchantReference field is available in the Payment Intent API across all payment actions. Here's an example of using it with a capture payment action:
{
  "action": "capturePayment",
  "amount": {
    "centAmount": 10000,
    "currencyCode": "EUR"
  },
  "merchantReference": "example-reference"
}

This capability is especially valuable for businesses that need to correlate Checkout payments with records stored in Enterprise Resource Planning (ERP) systems, accounting software, or other business applications. By attaching your own reference data at the payment level, you create a clear connection between the payment in Checkout and your internal business records, streamlining reconciliation and reporting workflows.

Payment Integration customization

In July 2025, payment integration customization was introduced in public beta for web component Payment Integrations. This feature allows you to customize how payment methods appear in your Checkout to better reflect your brand and locale preferences.

You can customize the following elements for each Payment Integration and localize them to support multiple languages:

  • Payment method names: adjust how payment methods are labeled to your customers.
  • Descriptions: provide additional context or instructions specific to your business.
  • Icons: use custom icons that align with your visual identity.
  • Checkout button text: customize the final action button text (for example, "Complete purchase", "Place order", or other variations).

Checkout supports two types of payment methods with different customization approaches:

  • Pre-defined payment methods, such as credit cards: they come with default settings that you can either use as-is or override in the Merchant Center. You have the flexibility to customize all fields or just a few, with defaults filling in the rest.

  • Custom payment methods: they are added through your Organization Connector or via third-party Connectors, and require full customization in the Merchant Center.

Note that some payment methods use their own branded buttons that cannot be customized. For example, PayPal, Apple Pay, and Google Pay maintain their distinctive branded buttons to ensure customers recognize these trusted payment options.

If you previously customized payment methods using the SDK, you should migrate your settings to the Checkout application in the Merchant Center, where you can now manage payment method appearance directly through the interface.

URL communication flexibility

In March 2025, Checkout introduced a toggle in Application settings that allows any URL to communicate with your Application. When this toggle is inactive, only URLs listed in the Specified origin URLs field can communicate with your Application.

This toggle is designed to simplify testing of your Application during development. It's recommended that you activate it only for test environments, and keep it deactivated in production to maintain proper origin URL restrictions for security purposes.

Payment processing enhancements

Transaction ID in refunds

In July 2025, a transactionId field was added to the Refund Payment action. This field enables you to specify exactly which transaction you're refunding, which is particularly useful when dealing with payments that have been captured in multiple parts.
With the transactionId field, you can refund individual capture transactions separately rather than being limited to full payment refunds. This granular control makes it easier to handle scenarios like partial returns or adjustments to specific order components. The field also simplifies tracking by creating a clear connection between each refund and its originating transaction, which streamlines reconciliation processes and improves accuracy in your accounting records.
When a payment involves multiple captures or transactions, the transactionId field ensures that refunds are applied to the intended transaction, preventing errors and confusion in your payment records:
{
  "action": "refundPayment",
  "amount": {
    "centAmount": 10000,
    "currencyCode": "EUR"
  },
  "transactionId": "example-transactionId",
  "merchantReference": "example-reference"
}
If you want to check the complete API details and usage, see the Refund Payment documentation.

Test your knowledge