Givex (Shift4)

Information about working with Cardigan's Givex (Shift4) integration.

Overview

Givex (acquired by Shift4) is available as a default provider option immediately on Cardigan installation.

Givex supports the full range of Cardigan functionality: provisioning new digital and physical gift cards, balance checks, transaction history, redemption using an authorize-and-capture flow, refunds, and activation of physical cards at the point of sale.

Setup

After installation, navigate to the "Profiles" section in your Cardigan settings and add a new "Givex (Shift4)" gift card provider.

Credentials

Your Givex API credentials will be provided to you by your Givex account manager, if you don't already have them. Typically, Givex will provide you with Beta environment credentials for your staging environment, and subsequently the appropriate production credentials once everything has been confirmed working.

As Cardigan has already been certified for use with Givex's APIs across a range of use cases, no fresh certification will typically be required.

Note that your Givex API user will need to have specific API methods enabled, depending on the piece of functionality you are using. These include:

• 994 Secure Balance: if using balance check or redemption flows;
• 920 Pre-Auth and 921 Post-Auth if using redemption flows;
• 956 E-Cert Order or 904 Register if using purchase flows or issuing refunds to a new card, depending on the digital provisioning method you select below;
• 927 Merchandise Credit if issuing refunds back to the original card;
• 906 Activation if activating physical gift cards after purchase on Shopify POS.

API Endpoint

The endpoint to connect to - this will almost always be Beta (beta-dataconnect.givex.com) for a staging environment, and the appropriate data center for your production deployment.

User ID

Your Givex API user ID.

Password

Your Givex API password.

Configuration options

Default digital card face ID

Only required if you are supporting purchase flows, or are issuing new gift cards in response to gift card refunds. This specifies the gift card template Givex will use to send a provisioned digital gift card, and is also known as the CWS item reference within the Givex portal.

Default physical card face ID

The equivalent template used when provisioning physical gift cards. If not provided, this will default to the same value as the digital card face ID.

Default shipping option ID

The ID of the shipping option for Givex to use when provisioning physical cards.

Digital provisioning method

Which Givex API method to use when provisioning new digital cards. Two options are available:

• 956 (Ecert Order): issues the card as an e-certificate order;
• 904 (Register): registers the card directly.

Your choice here determines which API method needs to be enabled on your Givex account, and which issuance reference options are available below.

Issuance reference

Determines the reference that Cardigan attaches to gift cards it provisions, so that you can trace a card in the Givex portal back to the Shopify order that created it.

The options available depend on the digital provisioning method selected:

• When using 956 (Ecert Order), you can choose which Shopify identifier to use as the order reference. The reference attached to gift cards in the Givex portal will look something like WEB5234523 or 8238261731662, depending on your selection.
• When using 904 (Register), the reference is always the source Shopify ID, and the transaction code in the Givex portal will look something like 8238261731662.36ffbd.

The admin form shows a live example of the resulting reference format as you change this setting, which is the quickest way to confirm you've picked the right one.

Redemption transaction code reference

Determines the reference Cardigan attaches to redemption transactions, so redemptions can be traced back to the originating Shopify order or payment.

As with the issuance reference, the admin form shows an example of the resulting format for each option.

Refund behaviour

Select the desired behaviour when a refund is triggered against a gift card redemption transaction (when manually from the Shopify admin or via the Shopify API). Options include:

• Take no action, in which case Cardigan will ignore the refund;
• Issue new, in which case Cardigan will provision a new digital gift card for the refunded amount. Note that the new digital gift card will be issued back to the customer that placed the order being refunded -- this will likely be a different customer to the original purchaser;
• Refund to original, in which case Cardigan will return the funds to the original gift card used to pay for the order. Note that you will need to have the 927 Merchandise Credit API method enabled on your Givex account for this to work.

Taking no action is the default, but in general we recommend issuing a new digital gift card on refund. Not only does this help with auditing gift card history for a particular customer, it also avoids issues in situations where the customer holding the gift card has lost or discarded their original gift card details.

Usage

Once the Givex profile is set up and configured, you can add Cardigan's front end widgets to your store and test flows like balance lookups and redemptions. You will need to have test card numbers provided to you by Givex (or issue them yourself) to test the balance check and redemption flows.