Integrate a payment service provider

This guide covers that template-based direct Connector path: you deploy a payment Connector, wire it into your own storefront, and own the backend around it. On this path the Connector creates and maintains the Payment, and your backend owns three things the template leaves to you:

• the Checkout Session that authenticates the browser to the Connector
• the conversion of the Cart into an Order
• the capture, cancellation, and refund operations that follow the Order

Define the payment requirements

Each decision maps to a configuration value or an architectural choice later in this guide. Document the following before selecting or configuring a Connector:

• Provider and Connector: identify the PSP, the Connector and its version, and whether it is already deployed. Record the processor and enabler URLs if it is.
• Region and Project: the Session, Auth, and API hosts are Region-specific, and a Connector default usually points at one Region.
• Capture mode: decide whether to charge immediately or to authorize now and capture later at fulfillment. Confirm which modes the Connector and provider account support.
• Saved payment methods: decide whether returning shoppers can reuse a stored method. Check the Connector contract for Customer and Cart requirements. Stored methods bind to a Customer, so decide how the Cart carries one; an anonymous Cart stores nothing and the shopper sees no error.
• Partial refunds and split captures: decide whether the business needs partial refunds or multiple captures. Confirm support in both the Connector version and the provider account.
• Payment interface name: decide how the Payment identifies the Connector, so that reconciliation and back-office tooling can select the right Payments.
• Payment methods and layout: list the methods to offer, and choose between a single drop-in element and individual components.
• Billing address collection: decide whether the payment UI collects the billing address or your own checkout does, so that one of the two always supplies the addresses Order creation needs.
• Storefront origins and return URL: list every browser origin that calls the Connector, and the absolute URL the shopper returns to after paying.
• Settlement: determine how the Connector records final payment state and whether your Order gate must wait for a provider webhook.
• Gift cards and store credit: decide whether a gift card Payment Integration will be configured alongside this one, because it changes the Checkout Application configuration.
• Anything else: capture constraints that no fixed list asks about, such as PCI scope, strong customer authentication, purchase-order numbers, subscriptions, marketplace split payments, surcharging, custom fraud scoring, or provider metadata requirements. Record each as its own requirement, because these are the ones most likely to decide whether configuration is enough.

Confirm this list with the business before deriving any configuration. Flag every unusual requirement explicitly, because each one can move the decision in the next section from configure to fork or build.

Choose an integration path

Two decisions happen here, in order. First decide whether commercetools should run the checkout for you. Then, if it should not, decide how much of a Connector you have to build.

Decide between Checkout and a direct Connector integration

Four paths lead to a paid Order, and they differ in who owns the Payment, how payment starts, and which API performs post-purchase operations. Choose one path deliberately.

Choose the template-based direct Connector path, described in the rest of this guide, when you need full control over the checkout experience and over the moment an Order is created, and you accept owning the Session, the Order, and the post-purchase operations.

Choose a Connector path

Check the live Connector landscape at the start of the implementation, and record the Connector key, version, and the date you checked it. Supported providers, payment methods, and capabilities change between Connector versions, so a list written into a document goes stale.

Determine the current state from three sources:

• the supported PSPs, Payment Integration Types, and payment methods table, which lists the Public Connectors that commercetools builds
• the Connect marketplace in the Merchant Center, which also lists Connectors built by providers and other third parties
• the Search Connectors endpoint, which lists published production Connectors. Verify Project access and deployment eligibility separately.

A marketplace listing does not prove that an integration is a deployable Connect Connector. Confirm that a candidate has a Connector definition before treating it as an installable option. If a promising option turns out to be a partner or software-as-a-service integration instead, it falls outside this guide.

Compare each candidate against your requirements on the following dimensions:

• the provider itself
• the payment methods you need
• the integration type, meaning a drop-in element or individual components
• the capture, refund, and stored-method capabilities
• Region and currency coverage
• every unusual requirement you recorded

Then choose the first path that fits:

1. Install and configure a Public Connector when its published contract covers the requirements.
2. Check whether configuration closes an apparent gap before changing code. Use the selected Connector version and provider account documentation to verify each capability.
3. Fork an open-source Connector when the provider has one and configuration genuinely cannot provide the behavior. Add only the missing capability and deploy the result as an Organization Connector. Forking keeps the processor contract, the Session authentication, and the Payment ownership model that already work.
4. Build from the payment integration template when no Connector exists for the provider.

commercetools connect validate

Configure the Connector

Configuration is what makes a Connector behave the way the requirements describe, and most values have a default that decides behavior for you. Set every behavior-changing value deliberately, and record a short reason for each so a wrong assumption is visible.

Configuration that changes payment behavior

Configuration that fails only at runtime

Validate behavior-changing runtime values before the first test payment. Exact keys and failure responses depend on the Connector version.

• Region hosts: confirm that every configured host matches the Project Region. A host left at a default from another Region fails at authentication or Session creation, not at deployment.
• Return URL: use the URL format required by the Connector contract and test the complete redirect flow. Connectors built from the template parse this value in the browser, so a value without a scheme throws in the enabler and the shopper never returns from the provider.
• Allowed origins: configure the storefront origins required by the Connector and verify browser access. An origin that is missing, or that differs by scheme or port, makes the processor reject the browser with a cross-origin error while the same request succeeds from a server.
• Webhook configuration: follow the Connector and provider requirements for endpoint registration and event verification. Serve the endpoint over HTTPS, and verify the provider signature before the processor changes any state.

API Client scopes

Three separate clients are involved, and conflating them is the usual cause of authorization failures.

• The deployment client authenticates the Connect CLI or the Merchant Center action that creates the deployment. It needs the Connector and deployment scopes. If the Connector generates its own runtime credentials, this client also needs manage_api_clients:{projectKey}, which manage_project:{projectKey} does not include. Without it, deployment fails with an access-denied error.
• The Connector runtime client is what the deployed processor uses to call commercetools. Read the Connector definition for its required scopes instead of assuming a fixed list.
• Your own backend client creates Sessions and Orders. It needs at least manage_sessions:{projectKey} to create a Checkout Session, view_payments:{projectKey} to confirm the Payment succeeded, and manage_orders:{projectKey} to create the Order.

Webhook registration after the first deployment

When a Connector requires a deployed processor URL before provider webhook registration, use this sequence:

1. Follow the Connector contract for any bootstrap configuration needed for the initial deployment.
2. Read the processor URL from the deployment.
3. Register the webhook endpoint at the provider and select the events required by the payment flow.
4. Update the deployment with the verified webhook configuration.

Select webhook events from the provider and Connector documentation rather than using a fixed list from another integration. Verify each event that moves a Transaction or opens the Order gate. For production, decide separately how to handle the provider's dispute and chargeback events. They arrive long after the Order exists and do not fit the Order gate, so confirm whether the deployed Connector records them on the Payment before assuming a Transaction appears.

Read the processor and enabler URLs from configuration in both your storefront and your backend rather than hardcoding them. A redeploy keeps the URLs of an existing deployment, but a deployment you delete and recreate gets new ones, and every hardcoded copy then points at a dead endpoint.

For an initial deployment, configure every application required by the Connector definition. A redeploy can update a subset of existing application configurations; omitted values remain unchanged.

Implement the payment flow

Your backend, the Connector, and the provider each own part of the flow. The sections below follow one payment from Session creation to refund.

Prove the deployed Connector first

Before wiring the Connector into the storefront, drive it once from a disposable harness: create a Session, load the enabler, submit a provider test card, and confirm the resulting Payment in commercetools. A failed payment looks the same whether the cause is the Connector, its configuration, or your storefront, and this step rules out the first two before the third exists.

A harness can take shortcuts that production must not, such as a throwaway Cart or hardcoded configuration. Keep it out of every deployed environment and discard it once the real flow works.

Create the Checkout Session on your backend

Complete these steps in one backend endpoint:

1. Verify that the Cart belongs to the caller. Fetch the Cart and compare its customerId or anonymousId against the authenticated user before trusting a Cart identifier from the client.
2. Confirm that the Cart is ready for the selected Connector and payment method. A processor built from the template compares the amount already paid against the Cart total, so a Cart with a zero total is refused as already paid rather than accepted as a free Order.
3. Create the Session using the canonical request in Create Checkout Sessions.
4. Set the Session metadata required by the deployed Connector contract. When the metadata does not identify the processor the Session is for, the processor rejects an otherwise valid, freshly created Session with a 401 reporting that the Session is not active. Check this first when a new Session fails immediately.

The request and response use different Cart paths. Follow the canonical Session representation rather than reusing the request shape in response-handling code.

Create the Session when the shopper reaches the payment step.

Render the payment UI

Pass the shopper's locale to the enabler instead of hardcoding one, so that the provider renders its components and its error messages in the language the rest of the storefront uses.

The browser authenticates to the processor with the Session, not with an OAuth token. If you call a processor route directly, send the Session header that the Connector documents; a bearer token does not authenticate you to the processor.

Create the Order after payment

Confirm four preconditions before creating the Order:

1. The Cart has a shipping address, which Create Order from Cart requires for every TaxMode. It also carries the Shipping Method and any further addresses your process requires, and paymentInfo.payments contains the Payment that the Connector linked.
2. The Payment holds the expected Charge or Authorization Transaction in state Success, and its amount covers the amount your flow requires before Order creation. A Pending Transaction has not completed. A Failure Transaction is unrecoverable, but the provider outcome determines whether it represents a shopper decline or another failure.
3. You are using the current Cart version.
4. Your business validations, such as stock and minimum order value, pass.

On this path the processor creates and maintains the Payment, so your backend must not create Payment objects of its own. A backend that also creates one leaves the Cart referencing more than one Payment for a single attempt, which breaks amount reconciliation and the Order gate that reads the Transaction state.

Reconcile with the PSP webhook

Do not make Order creation depend on the shopper keeping the return page open. Consume Payment Transaction state-change Messages, or run a reconciliation job, to retry the same idempotent Order-creation operation on the server. Alert when the server-side retry policy is exhausted.

Capture, cancel, and refund

Keep these operations idempotent using the mechanism defined by the Connector and provider so that a retried capture cannot charge twice.

Provider identifier requirements vary. Confirm which authorization or capture identifier the Connector requires for refunds, and retain the required identifier in your reconciliation data. When a refund passes the authorization identifier to a provider that refunds against the capture, the call fails with a not-found error even though the payment plainly succeeded.

For reconciliation with finance or enterprise resource planning systems, pass your own reference on the operation, and target a specific capture when refunding a Payment that has more than one.

Test the integration

Two suites cover different risks, and the fast one comes first.

Cover the backend decisions with unit tests that mock the outbound boundary, which is the processor, the Sessions API, the commercetools API, and the provider. Assert what your code decided to do, and keep your own orchestration unmocked. These tests need no deployment and no secrets, so they can run on every commit. Cover at least the following:

• Session creation: an owned, payment-ready Cart yields a Session. A Cart belonging to another user yields no Session. A Cart with a zero total yields no Session. The browser response contains the values required by the Connector and no credentials.
• Order creation: an authorized Cart produces exactly one Order and sets cartState to Ordered. A Pending or Failure Transaction produces none, and a Failure surfaces the decline rather than a generic server error. A duplicate-field or invalid-operation response returns an existing Order only after a successful orderNumber lookup. The Cart version comes from a fresh read.
• Post-purchase operations: capture, cancellation, and refund reach the Connector operation routes, and the Checkout Payment Intents API stays untouched. Retrying an operation does not duplicate a successful money movement.
• Webhook handling: a redelivered event changes nothing the second time, provider-required verification runs before any state change, and a verified success event opens the Order-creation gate that was closed.

Then add one full-flow test against a real deployment with provider test cards. Drive it from Session creation through payment, Order creation, capture, and refund, and assert the commercetools state after each step so that a failure identifies which stage failed. Poll for asynchronous settlement rather than sleeping, and skip the test with an explicit message when the deployment configuration is absent, because a silent pass on a missing secret is the same as having no test. Run it after deployments rather than on every commit.

Follow the provider testing documentation when automating payment fields. Use a browser driver when the provider UI requires browser-level interaction. Otherwise, automate up to the mounted payment element or exercise the Order-creation path through a provider-supported test API.

Verify and operate the integration

Verify the complete flow in a non-production Project against a provider test account, using provider test cards rather than real ones.

Verify the integration in this order:

1. Verify configuration: confirm that the Region hosts, return URL, and allowed origins match the storefront, that the webhook configuration is complete, and that secrets appear only in secured configuration.
2. Verify the Session: create a Session from an owned, payment-ready Cart and confirm that the response to the browser contains no credentials. Confirm the processor accepts it.
3. Verify the payment: complete a test-card payment. Confirm that cart.paymentInfo.payments references the expected Payment attempts, that the selected Payment identifies the Connector as documented, and that successful Charge or Authorization Transactions cover the required amount. Confirm that a single attempt produced a single Payment, because a second Payment for one attempt means something other than the processor created it. Confirm that interfaceId and interfaceInteractions hold the provider references you need later, because a dispute or a finance query is answered from that record.
4. Verify the Order: confirm that exactly one Order exists, that cartState is Ordered, and that repeating the request with the same orderNumber returns the same Order rather than creating another.
5. Verify settlement: for an asynchronous provider, confirm that the Transaction moves from Pending to Success after the webhook, and that Order creation was blocked until it did.
6. Verify redelivery: replay the same webhook event and confirm that the Payment is unchanged and no second Transaction appears.
7. Verify the reverse lifecycle: cancel an authorization before capture and confirm a CancelAuthorization Transaction. Then on a separate payment, capture, refund, and confirm the Charge and Refund Transactions with the expected amounts. Include a partial refund if the business needs one.
8. Verify a decline: pay with a card that the provider declines, and confirm that no Order is created and that the shopper sees the decline rather than a generic error.

Diagnose common failures