Magenta

Information about working with Cardigan's Magenta integration.

Overview

Magenta is available as a default provider option immediately on Cardigan installation.

Cardigan integrates with the Magenta point-of-sale platform's EEE ("Triple E") web service, with EEE remaining the system of record for gift card numbers and balances. The integration supports balance checks, redemption using a full authorize-and-capture flow backed by EEE reservations, refunds back to the original card, and provisioning of new digital gift cards drawn from your EEE instance's virtual card number ranges.

Setup

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

Credentials

Your Magenta web service credentials are managed within your EEE instance. The web service user Cardigan connects with needs access to the gift card methods: GiftCardBalance, GiftCardRedeemWithDate, GiftCardRedeemReverse, GiftCardIssue, GiftCardVirtualReserve and GiftCardVirtualReserveIssue, plus EEEVersion (used by the "Test credentials" button). Your Magenta support contact can confirm these are enabled.

API Endpoint

The full URL to your EEE instance's authenticated web service endpoint (ending in eeewebserviceauth.asmx). If your EEE web service is exposed through an API gateway, use the gateway URL here.

Username

The EEE web service user code.

Password

The EEE web service password.

API Token

Optional. If your endpoint sits behind an API gateway that requires token authentication, provide the token here — it is sent as an api-token header with every request. Leave blank when connecting to EEE directly.

Configuration options

Currency

The currency of this profile. In EEE, a gift card's currency is determined by the branch that issued it, so this setting must match the currency of the branch code below. Merchants selling in multiple currencies should create one profile per web branch.

Branch code

The EEE branch code that transactions are applied against — usual practice is a dedicated "web" branch. This determines the currency cards are issued and redeemed in; EEE only allows a card to be redeemed through a branch matching the currency it was issued in.

Till number

The till that new gift card issues are recorded against when Cardigan provisions cards.

Refund behaviour

Select the desired behaviour when a refund is triggered against a gift card redemption transaction (whether 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 as a balance top-up in EEE.

Taking no action is the default, but in general we recommend issuing a new digital gift card on refund.

Usage

Once the Magenta 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.

When a customer applies a gift card at checkout, Cardigan places a reservation against the card in EEE; the reservation is committed when the order completes, reversed if the card is removed, and expired automatically if the checkout is abandoned. New digital gift cards provisioned by Cardigan are drawn from your EEE instance's virtual gift card number ranges and are active as soon as they are issued.

Test gift cards on your staging EEE environment can be created by completing a gift card purchase through Cardigan on a development store, using the "Issue Card" feature in Cardigan's Admin UI, or generated for you by your Magenta support contact.