Integrate a gift card system

The rule also constrains the Connector you build. A redeem operation must never reject a card because its balance is lower than the Cart total. Redeeming less than the total is the expected case, and the other Payment Integration collects the remainder. A Connector that treats a short balance as an error removes the behavior the fallback exists to provide.

This guide owns the integration decision and the Connector build. The reference material lives in the Checkout documentation, and this guide links to it rather than repeating it:

• the gift card Connector contract
• the gift card Messages
• rendering and Message handling in the Browser SDK
• the Payment Intents API

Before you begin, make sure you have the following:

• a commercetools Project
• access to Connect
• a Checkout Application that already has at least one working Payment Integration
• credentials for a gift card system test environment
• a backend route that creates the Checkout Sessions these flows depend on, as described in Installing Checkout

Define the gift card requirements

Each decision below becomes a configuration value, a Connector capability check, or a Checkout Application setting. Document them before you select or configure a Connector.

• Gift card system: identify the system, the account environment, the credentials, and the balance and redemption operations it exposes.
• Currency scope: record every currency the storefront sells in. This is the first of two decisions that break checkout when you get them wrong. For the reason, see Scope the deployment to a currency.
• Fallback Payment Integration: name the other Payment Integration that collects the remainder, and confirm that it's deployed and configured on the same Checkout Application. This is the second decision that breaks checkout when you get it wrong, and it's the rule stated at the top of this guide.
• Card presentation: decide whether the shopper enters a code alone or a code and a PIN, and what validation the storefront applies before the code reaches the Connector.
• Partial redemption and multiple cards: decide whether one Cart can carry several cards, and whether a card can be redeemed for less than its balance.
• Expiry and zero balances: decide what the shopper sees for an expired card and for a card with no remaining value. Both are valid card states, not errors in the integration.
• Post-order operations: decide whether a refund returns value to the original card, and whether a failed Order requires a full reversal. Your answers determine which operations the Connector must support.
• Region, Project, and Stores: record these, along with any multi-Store or business-to-business requirements.
• Anything else: record constraints that no fixed list asks about, such as a card that's also a loyalty instrument, breakage reporting, a card issued by a franchise partner, or a balance shared with a point-of-sale system. Each of these can move the decision in the next section from configure to build.

Confirm this list with the business before you derive any configuration. A requirement recorded late in this domain usually changes the Connector rather than a setting.

Choose an integration path

Check the live Connector catalog

GET https://connect.{region}.commercetools.com/connectors/search?integrationTypes=giftcard&private=false

Assess the available options

Three options exist, and they differ in what they leave you to build.

Most gift card systems are a build-from-template job. Budget the project on that assumption unless your catalog check finds a Connector for your specific system.

Choose the first path that fits

1. Install and configure a Public Connector when its published contract covers your requirements. For Voucherify, this is the whole job.
2. Prove that configuration can't close the gap before you change any code. Gift card Connectors commonly expose the system base URL, the account credentials, the currency, and the Payment interface name as configuration.
3. Fork an open-source Connector when the gap is genuine. The Voucherify Connector is open source, so a system with a similar balance-and-redeem API is often closer to a fork than to a fresh build. A fork keeps the Session authentication, the Payment ownership model, and the route contract that already work.
4. Build from the gift card integration template when no Connector exists for your system, which is the common case.

commercetools connect validate

Record the option you chose and the reason. Rebuilding a Connector that already exists is the most expensive way to obtain one.

Design the two applications

A gift card Connector declares two Connect applications. The split decides where secrets live and which credential authenticates each call.

• The processor is a service application. It holds the gift card system credentials, calls the system, and owns the commercetools Payment.
• The enabler is an assets application. It delivers the browser-facing library that renders the gift card input inside Checkout.

Separate the enabler from the processor

The enabler delivers the browser-facing library as static assets, and it keeps the gift card system credentials out of the browser. It holds no secrets, makes no call to the gift card system, and authenticates to the processor with the Checkout Session rather than with an API token.

Keep every credential in the processor. The enabler is served to the browser, so a value placed there is public. The payment integration template documents a reduction in Payment Card Industry compliance obligations for its own enabler. That claim covers cardholder data, it doesn't transfer to a gift card code, so don't rely on it here.

Authenticate each route correctly

Treat this table as the contract of the Connector you deploy. Wire each route to its own model rather than to one shared mechanism, and cover each route with a test that asserts the rejection as well as the acceptance.

Keep balance read-only and redeem idempotent

Balance is a read. It must not reserve, hold, or deduct value. Checkout calls it while the shopper is on the payment step, so a balance call with a side effect makes the card shrink every time the shopper looks at the page.

Redeem moves money, so it must be idempotent. Key it on the card code together with the Cart or Payment context. A replay of the same request then returns the first result, while a second, different card is still redeemed on its own. Reconcile against the Payments already attached to the Cart before you create another one.

Neither the gift card integration template nor the Voucherify Connector implements this. In both, a replayed redeem creates a second Payment and charges the card again. This is work you own, and it stays invisible until production traffic produces the first retry.

Configure the Connector

• connect.yaml sits at the root of the Connector, above application folders such as processor and enabler, rather than inside one of them. A nested file isn't found, and the Connector never appears.
• The endpoint value an application declares in connect.yaml sets the path that Connect appends to the deployment URL. Both current gift card Connectors serve the processor at the root of that URL, and Checkout calls the route paths in the contract directly. A processor that declares an extra path segment therefore answers a direct request while every Checkout call returns a not-found response.

Set the Region-specific values

The authorization host, the API host, the Session host, the JSON Web Key Set URL, and the token issuer are all Region-specific, and a Connector default often points at one Region. This misconfiguration has no deployment-time signal. The deployment succeeds and reports healthy, and then every call fails authentication.

Scope the deployment to a currency

Create the API Client

The processor built from the template runs a health check that fails unless the client holds all of the following scopes:

• manage_payments, because the processor creates the Payment and writes its Transactions.
• manage_orders, for the Cart and Order operations the redeem flow performs.
• view_sessions, to validate the Checkout Session that the enabler presents.
• view_api_clients, which the health check reads.
• manage_checkout_payment_intents, for the post-order operation route.
• introspect_oauth_tokens, to validate the OAuth token on that route.

Separate secured and standard configuration

Add lifecycle scripts if your system needs them

Configure the fallback Payment Integration

The rule at the top of this guide is also a configuration step. On the Checkout Application that carries the gift card Payment Integration, confirm that at least one other Payment Integration is configured and enabled, and that it covers the same currencies and Regions as the gift card deployment.

Verify this in the Application configuration rather than inferring it from the storefront, because the gift card path renders correctly whether or not a fallback exists. The absence shows only when a balance falls short.

Implement the gift card flows

Replace the simulated gift card client

This is the same trap as the sample Connector, reached by a different route, and it's more dangerous because the build looks like your own work. Replace the mock client with a client for your gift card system before you treat any verification result as evidence. Until you do, a green end-to-end run proves only that the Checkout contract is wired.

Keep the replacement behind the same interface the template defines. The route handlers, the Payment writes, and the currency guard then stay unchanged, and the tests keep a boundary to mock.

Check the balance

Balance answers a question and persists nothing. The contract is as follows:

1. The enabler collects the code, and the PIN when the system requires one, and calls POST /balance with the Checkout Session.
2. The processor reads the Cart that the Session identifies and derives the payable amount from it.
3. The processor compares the Cart currency against the deployment currency and stops with a 400 response on a mismatch.
4. The processor calls the gift card system's balance operation with the system credential.
5. The processor returns the amount and whether it covers the payable amount.

Treat an expired card and a card with a zero balance as successful reads that report an unusable card, rather than as failures of the balance operation. The shopper needs a message, not an error page.

Redeem value onto a Payment

Redeem is where the processor takes ownership of the commercetools Payment. Your own backend must not create Payment objects for gift cards. A second Payment for one attempt breaks the remainder arithmetic that the fallback method depends on.

The gift card integration template and the Voucherify Connector both implement the sequence below. This is the behavior of those Connectors rather than a documented platform guarantee, so confirm it against the Connector you deploy.

1. The enabler calls POST /redeem with the code and the amount to redeem, authenticated by the Checkout Session.
2. The processor reads the Cart and applies the currency guard.
3. The processor performs the idempotency check described in Keep balance read-only and redeem idempotent, and returns the earlier result when this request is a replay.
4. The processor creates a Payment whose amountPlanned is the amount being redeemed, not the Cart total, and whose paymentMethodInfo identifies the Connector and the gift card method.
5. The processor attaches the Payment to the Cart. This update uses the Cart version it just read, so a stale version produces a ConcurrentModification error.
6. The processor calls the gift card system's redeem operation and receives a redemption reference.
7. The processor adds a Charge Transaction to the Payment, using the Payment version returned by the create call. The Transaction carries the redeemed amount, the redemption reference as the interaction identifier, and a state mapped from the system result.

Two consequences of this sequence matter for failure design. First, the Payment exists before the gift card system is called, so a system failure leaves a Payment without a successful Transaction, and your monitoring must be able to recognize that. Second, every step operates on a Cart, so value leaves the card before the Order exists. Checkout creates the Order later in the flow, so a design that assumes an Order is present whenever value has moved is wrong.

Handle partial redemption and multiple cards

The default shopper-facing text in Checkout promises a reimbursement when the fallback method fails after a gift card was already redeemed. That text is a configurable default stored under a generic second-payment-method error key, not a documented reimbursement mechanism. Confirm the behavior against your Connector's refund implementation during verification, because the reimbursement depends on the Connector supporting the operation.

Implement refund and reversal

• Refund returns value to the card. Write the Refund Transaction before the external call, and update its state from the system result, so that an ambiguous timeout leaves a record to reconcile. See Refund Payment.
• Reversal returns the full planned amount. Automated Reversals cancel or refund a Payment when Order creation fails, and they work only when the Connectors in the Project support Reverse Payment. A gift card Connector that omits it removes that safety net for every Payment on the Cart.
• Capture and cancellation are a Connector implementation choice rather than an API restriction. The Payment Intents API defines both actions for a payment service provider or a gift card management system. A gift card redeems rather than authorizing and capturing later, so both current gift card Connectors answer these operations with an unsupported response. That response is correct behavior, even though it looks like an unimplemented feature.

Surface results in the storefront

Verify and operate the integration

Work through these checks in order:

1. Verify the configuration. Confirm that every host matches the Project Region, that the deployment currency matches the test Cart, that secrets appear only in secured configuration, and that the Checkout Application carries the fallback Payment Integration.
2. Verify that balance is a read. Check the balance of a card twice without redeeming. The amount is identical both times, the gift card system records no reservation, and the Cart carries no Payment.
3. Verify a full redemption. Redeem a card that covers the Cart. The Cart carries exactly one gift card Payment, its amountPlanned equals the redeemed amount, and it holds one successful Charge Transaction that carries the system's redemption reference.
4. Verify a partial redemption. Redeem a card worth less than the Cart total. The outstanding amount equals the Cart total minus the redeemed amount, the shopper is offered the fallback Payment Integration, and paying it produces a second Payment on the same Cart.
5. Verify multiple cards. Apply two cards to one Cart. Two Payments exist, each with its own Charge Transaction, and the second card was redeemed for the outstanding amount rather than the original Cart total.
6. Verify the Order. Confirm that exactly one Order exists and that it references every Payment created during the attempt.
7. Verify a replay. Send the same redeem request twice. One Payment exists, one Charge Transaction exists, and the gift card system records one redemption.
8. Verify refund and reversal. Refund a gift card Payment and confirm both the Refund Transaction and the value returned in the gift card system. Then confirm that the Connector answers the reverse operation, because Automated Reversals depend on it.
9. Verify the shortfall failure. Fail the fallback method after a gift card was redeemed, and confirm that the reimbursement your Connector performs matches what the shopper was told.
10. Verify unusable cards. Present an expired card and a card with a zero balance. Each produces a shopper-readable message and leaves the Cart unchanged.

Once live, monitor Payments that hold no successful Transaction, redeem retries, currency-mismatch responses, authentication failures per route, and Connector deployment health. Log the Cart identifier, the Payment identifier, and the gift card system's redemption reference together, because that record is what answers a balance query from finance.

Test with the simulated codes

These codes settle nothing. The documentation states that the values are for simulation purposes only and that no payment is made. A passing run with them is evidence about your Checkout configuration, and about nothing in your gift card system.

Diagnose common failures

Several correct behaviors in this domain look like defects.

Extend to another gift card system

Adding a second gift card system doesn't change the architecture. The two applications, the route contract, the authentication models, the Payment ownership, and the flows stay as described here. What changes is the client that talks to the system, the configuration that addresses it, and a second deployment with its own Payment Integration on the Checkout Application.