External Gift Cards

External gift cards connect Centra to an external gift card issuer so shoppers can pay at checkout using balances issued outside Centra - for example Givex through Centra's direct connector, or another issuer using Gift Card SPI (custom) middleware.

You can let shoppers redeem external gift cards in checkout. Split payment is supported: part of the order on the gift card, the rest on a regular Centra payment method (for example Adyen, Klarna, Stripe, Qliro, or PayPal).

Use plugin restrictions to control where redemption is offered—for example by market, country, or currency.

After orders are placed, AMS and the Integrations API expose the same kinds of capture, cancel, and payment history patterns you already use for card payments, extended with gift-card-specific entries where applicable.

The sections below cover setup, APIs, day-to-day operations, and limitations.

This page is the public integration guide for checkout and order operations. It is aligned with how the gift card module behaves in the Centra application (including rate limits and error codes).

Supported payment scenarios

• 100% gift card - applied balance covers subtotal, shipping, and tax, so there is no remaining amount to pay through a PSP (no card / wallet charge for the balance). Your storefront may still send the shopper through a generic checkout step (addresses, terms, confirmation) if you designed it that way—that is separate from paying a remainder to a PSP. The order can still show Waiting for Gift Card Authorization until funds are reserved with the gift card issuer.
• Split payment - part of the order is covered by one or more external gift cards; the remainder is paid with a regular Centra payment plugin (Adyen, Klarna, Stripe, Qliro, PayPal, etc.).

Centra supports both digital and physical gift cards (for example bought online or in store), as long as the provider considers them active and funded.

Connection modes

In AMS, the External Gift Card plugin Connector dropdown chooses how Centra talks to the issuer network: Gift cards SPI (custom) (your middleware URL), or a direct connector where Centra calls a supported provider's API with no middleware in between.

Gift Card SPI (custom connector)

Centra calls your HTTPS endpoint (middleware) that translates requests to your provider’s API.

• Checkout-time HTTP actions sent to your Custom connection URL: balance_check and authorize (fund reservation / pre-authorization after the order exists). Requests are signed with X-Centra-Signature using the configured Endpoint secret (timestamp + body).
• Plugin fields (AMS): status, name, connector, custom connection URL, endpoint secret, merchant ID, store number, optional automatic order cancellation on failed authorization, Direct capture (plugin or store default), and standard country / market / pricelist restrictions.

The full JSON contract (payloads, response shapes, and any post‑capture operations your middleware must support) is provided as Gift Card SPI documentation when you onboard as an integration partner - ask Centra for the current schema pack.

Direct provider connector

With a direct connector there is no middleware URL in the plugin: Centra calls the provider's API from the platform. Onboarding, credentials, and behavior are supplied by Centra in a separate package.

Multiregional setups

Redemption can be enabled per currency / market / country by creating multiple External Gift Card plugins (each with its own restrictions and, usually, its own provider account).

Features

• Redeem physical or digital cards in Checkout API or Storefront API.

• Split payment: gift card + credit card, wallet or invoice on the same order.

• Flexible apply timing: Centra supports adding a gift card at any point in the customer journey, including:

  • Product page
  • Basket page
  • Checkout page

  The shopper can remove an applied gift card from an order if your UI allows that. While it stays applied, the temporary credit voucher is still subject to voucher lifetime.

• Multiregional: use separate plugin instances with pricelist / market / country restrictions (and matching provider accounts per currency) - see the screenshot above.

Selling vs redeeming

Redemption of external gift cards is supported in Centra out of the box (configure the External Gift Card plugin). Selling external gift cards requires custom development on your side, or using your gift card service provider's capabilities.

• Redeeming external gift cards requires plugin configuration in Centra, and custom development if the Gift Card SPI (custom) connector is selected (your middleware implements the SPI contract).
• Selling digital external gift cards can be achieved by leveraging native gift certificates functionality and custom integration with an external gift card service provider for issuing.
• Selling omnichannel external gift cards can use your gift card service provider's capabilities (for example a dedicated checkout for gift cards). Another option is gift cards as regular products in Centra together with custom integration with your gift card service provider for issuing.

Building blocks - how selling / issuing relates to redemption in Centra (generic pattern; your project may use only part of it):

Note: Gift certificates in this diagram are Centra's native selling path. Selling external gift cards through gift certificates still requires custom development.

The diagram mentions Givex or SVS only as examples of third-party issuers behind a hosted or partner checkout, not as references to any specific retailer.

Typical combinations (examples only - your architecture may differ):

How cards are sold / issued	How shoppers redeem in Centra
Provider-hosted shop or partner checkout	External Gift Card plugin
Centra gift certificate product	Built-in gift certificate → voucher flows (not this plugin)
Normal product SKU + your systems issue codes	External Gift Card plugin or internal credit vouchers, depending on how codes are modeled

Checkout and gift cards

Apply gift cards in the same phase as other selection changes (vouchers, lines, shipping): Centra runs the issuer balance check, persists encrypted card data, and updates totals as a credit voucher on the selection.

Continue with the same checkout and payment sequence documented for your stack: Checkout and Payment flows for Storefront API, and the migration table for Checkout API parity - any remaining grandTotal follows the same PSP steps as a cart without gift cards.

Typical runtime (high level)

1. Gift card applied on the basket - shopper adds the card on the product page, basket, or checkout; Centra runs the issuer balance check and stores encrypted card data on the selection.
2. Credit voucher on the selection - Centra creates a credit voucher for the amount of the order total covered by the applied gift card (you will see the same pattern in AMS once an order exists).
3. Regular PSP payment (if needed) - when grandTotal is not fully covered by the gift card, the shopper pays the remainder with your normal Centra payment plugin.
4. Order placed - checkout completes and the order is created.
5. Hold and Waiting for Gift Card Authorization - the order sits in Hold with Waiting for Gift Card Authorization while issuer-side authorization runs.
6. Automatic call to the gift card provider - Centra sends pre-authorization / authorization requests to the provider in the background (no AMS button to trigger this).
7. Authorization succeeds - on success, the order moves toward Pending and the usual capture / fulfillment path; failures follow your plugin and cancellation rules.

AMS: waiting for gift card authorization

Automatic authorization with the gift card provider

After the order is created, Centra automatically calls the gift card provider to authorize the reserved amounts. There is no AMS action (such as a per-order button) that staff must trigger to start that call - Centra runs it in the background while the order shows Hold and Waiting for Gift Card Authorization until each applied card succeeds or the flow fails (subject to your plugin and capture settings).

Orders using external gift cards are placed with Hold and Waiting for Gift Card Authorization while that automatic authorization runs. This applies until every card succeeds, and is visible in AMS even when the final total is zero (100% gift card).

Frontend integration

When to show the gift card field

Checkout API: GET /selection includes externalGiftCardAvailable when an active External Gift Card plugin matches the selection (restrictions and store configuration).

Storefront API: the Selection type exposes externalGiftCardAvailable (Selection reference).

Apply gift card

Checkout API

POST /gift-card-apply

{
  "cardNumber": "1234555523335555",
  "pin": "1234"
}

Storefront API

Use the applyGiftCard mutation with cardNumber and optional pin in the input (same semantics as Checkout API).

Remove gift card

Checkout API: remove the applied code voucher like any other voucher, e.g. DELETE /vouchers (or the voucher-specific delete your integration already uses).

Storefront API: removeVoucher.

See also the API comparison table.

Applied card on the selection

Externally applied cards appear alongside other vouchers / discounts. Typical traits:

• Names like GiftCard_<id>_<lastFour> for display and reconciliation.
• Credit type (amount off the order).
• isExternal: true and lastFourDigits where the API exposes them (Checkout API voucher object; Storefront API discount metadata - see vouchers for discount shape).

You can present each applied card on its own row in checkout (for example a label with the last four digits of the card number) so shoppers can distinguish them.

For a standard headless build, wiring applyGiftCard, removeVoucher, and selection totals is usually a small frontend effort compared to PSP work.

Error codes (balance check / apply)

These machine-readable codes are returned when apply fails (Checkout API: errors array; GraphQL: errors on the mutation). They are defined in application code and safe to branch on in the storefront.

Code	Meaning
internal_error	Unexpected failure (e.g. malformed provider response).
invalid_input	Validation failed (unknown card, wrong PIN, malformed input). With the SPI (custom) connector, an empty PIN is rejected as invalid_input at balance check.
inactive_card	Card inactive or not usable.
insufficient_funds	Balance lower than required amount.
invalid_gift_card_currency	Card currency does not match the selection pricelist currency.
empty_card_balance	Zero balance.
gift_card_rate_limit_exceeded	Too many apply attempts for the selection; see Rate limiting below.

Example (Checkout API style):

{
  "errors": ["invalid_gift_card_currency"]
}

Order management

AMS capabilities

From AMS you can capture or cancel gift card authorizations in line with ordinary payments for supported setups. Refunding external gift card value is not exposed as a single AMS button for all configurations - after capture, expect to use Integrations API / provider processes depending on your connector and PSP.

You cannot top up or edit an external card’s balance inside Centra; reconciliation happens in the issuer’s portal (using serial or reference fields from transaction details where your program exposes them).

Payment history and types

AMS lists combined payment history for the order. Gift card rows use the same lifecycle as card payments but with a -gc suffix on the type string, for example:

• auth-gc - authorization / reservation
• capture-gc - capture (final deduction against the provider where applicable)
• cancel-gc - canceled authorization
• refund-gc - refund path where supported

Split auth and capture for both PSP and gift card on one order:

AMS: totals and “discount” rows

Externally paid value appears as a discount (credit voucher) line on the order (name prefix GiftCard_), while the grand total reflects what remains for the PSP.

Each application also creates a short‑lived credit voucher row in voucher lists (typically Code, Credit, max use 1, ~1 hour validity). That row is the Centra-side mirror of the external application, not the issuer’s master record:

Integrations API

Automated flows (ERP, OMS, custom middleware) should use the Integrations API GraphQL:

• Capture: captureOrder, captureShipment, or createShipment with capture as appropriate - same mutations as for the rest of the order; gift card portions produce gift card capture history when the capture pipeline runs.
• Cancel before capture: cancelDirectToConsumerOrder with cancelAuthorization: true so that gift card authorizations are released together with the PSP where applicable.
• Release unused authorization: releaseRemainingOrderAuthorization (gift card side effects follow the same payment history patterns as cancellation for GC rows where applicable).

Payment history query: pass includeGiftCardsPaymentHistory: true so gift card transactions are included in the unified payment history list.

Naming - AMS vs Integrations API: AMS uses string types such as auth-gc / capture-gc. The Integrations API returns structured entryType values (for example AUTH next to AUTH_GIFT_CARD, and CAPTURE next to CAPTURE_GIFT_CARD) plus paymentMethod and externalReference from the provider channel - use these fields when building dashboards or ERP feeds.

Example shape - split payment order payment history (values illustrative):

Reconciliation: use the order’s gift card / discount breakdown from the Integrations API to list each applied voucher and amount. When several cards reduce the total to zero, grandTotal reflects that while per‑card rows remain inspectable:

Machine‑readable breakdown is preferable to parsing AMS labels alone when you rebuild gross merchandise value or tax bases for finance.

Refunds

• SPI (custom) connector - refund and re‑issue style operations are defined in the SPI / onboarding pack from Centra (not duplicated on this page).
• Split payment (gift card + PSP) - today you typically calculate the split (amount back to the card program vs amount to the PSP), run card refunds through your PSP integration, and run gift card refunds through the Integrations / provider path your project agreed on. End‑to‑end orchestration in a single mutation is not guaranteed; confirm the roadmap with Centra if you need a packaged split‑refund flow.

Examples of Integration API shapes live alongside other DTC topics in example queries.

Order cancellation in AMS

Canceling an order from AMS before capture should cancel both the ordinary payment authorization and gift card authorizations. After capture, use refund flows instead of cancel where required by your PSP and gift card program.

Credit voucher behind the scenes

When a shopper applies an external card, Centra creates a credit voucher tied to that application (shown in AMS as a credit-type voucher). That voucher is scoped to the selection and expires one hour after creation; after expiry the shopper must apply the card again (triggering a new balance check).

Centra is not the issuer: the balance shown is the balance returned at apply time, not a live synced wallet.

Limitations and accounting implications

Topic	Detail
Order total / reporting	Applied external gift cards reduce the order total (credit voucher). Reported revenue and exports reflect the reduced total unless you reconstruct gross using breakdown / line data from the Integrations API.
Tax	External gift cards are applied after tax is calculated on the selection, so the shopper always sees the correct tax amount, including US sales tax and other tax-on-top setups. The gift card credit then reduces what remains to pay and can cover the tax portion of the order (alongside product and shipping). Campaign discounts and tax still run through Centra’s normal basket pipeline before that reduction. Use the Integrations API monetary fields for automation - some AMS tax summaries can look sparse when the grand total is zero, even though tax rules still apply on the order.
Currency	No cross‑currency redemption: the card must match the selection currency. Use multiple plugins (and provider accounts) per currency / region.
Double spend	Balance at checkout is informative; authorization after order placement is authoritative. A second order racing the same balance fails authorization and can remain held / failed unless you use automatic order cancellation on authorization failure.
Data retention	Card numbers and PINs are encrypted (AES‑256) in Centra; they are not shown in AMS and are not accessible to Centra staff.
Selling gift cards	Selling (issuing) Centra gift products is separate from external redemption; see internal product docs and gift certificates for Centra‑issued certificates.

Related links

• Storefront API migration - gift cards
• Vouchers and discounts
• Integration API index