Gift cards

DotApparel integrates Apparel21 "vouchers" with Shopify for purchase, redemption, and balance checking. Apparel21 vouchers, similar to "gift cards" in e-commerce, have a voucher number, PIN, and balance.

Using Apparel21 vouchers instead of Shopify gift cards allows customers to purchase and redeem vouchers at the point of sale (POS), enabling immediate online or in-store redemption.

It's important to note that Apparel21 is always the source of truth for vouchers in this model. When redeeming a voucher in Shopify, DotApparel verifies the PIN and balance directly with Apparel21 before applying it to the order.

Prerequisites

If setting up AP21 gift voucher:

• Apparel21 SKU IDX

• Apparel21 voucher type

If the merchant is using Shopify gift card:

• Apparel21 SKU IDX (dummy)

"dummy" is used for mapping order line items with an AP21 sku idx when purchasing a Shopify gift card. This can ensure the order is synced without issues (such as "cannot parse sku idx for xxxxx").

If setting up any other new payment gateway

• Ap21 Merchant ID

• Card Type

Implement Gift Cards with DotApparel

1. Install DotApparel Voucher Widget or Checkout UI Extension

JS Widget

In layout/checkout.liquid, add the following just before the </head> tag.

<script src="https://unpkg.com/@dotdev/dotapparel-voucher-widget"></script>

Note: If a previous custom Gift Card exists, you may need to remove this from the codebase.

Checkout UI Extension

Find the Gift Card Redemption app and add it to the checkout customization.

2. Use the new SKU structure

Each denomination of the gift card and gift card type (physical or digital) should be defined as a separate variant of the Shopify product. The SKU structure should define the type and denomination so you might have giftcard-p-20, giftcard-p-40, giftcard-e-20, giftcard-e-40. The frontend template should allow the customer to select a gift card type (physical/digital) and then a denomination, which should select the appropriate variant.

3. Update the custom line item attributes

The custom line item attributes must have the following names.

• From - This is the name of the sender.

• To - This is the name of the receiver.

• Email - This is the email of the receiver, for digital vouchers.

• Message - Personal message, included in the email.

• Email Subject (Optional) - This will override the email subject of the voucher.

• Delivery Date (Optional) - This is the future date that the gift card will be delivered. The format is YYYY-MM-DD (e.g. 2023-10-20). Please don’t provide this attribute unless the purchased gift card will be delivered via email and email should be delayed.

Please note: Make sure all key names above are capitalised as they are case-sensitive within DotApparel.

Please also note: If using Delivery Date , additional setup is required in Apparel21.

4. Test Gift Cards

The Gift Card form appears in the checkout

Ensure that the request is sent to the DotApparel api-giftcardValidation endpoint.

Purchasing vouchers

Purchasing vouchers in Shopify works like any other product, with the addition of some custom line item attributes which allow the customer to provide attributes such as the receivers name, email, and a personal message which is either included in the email (if it's a digital voucher) or included with the plastic card (if it's a physical voucher).

An example of this in action can be found at https://www.decjuba.com.au/products/gift-card. The gift card itself is an ordinary Shopify product, which is manually created directly in Shopify. A custom product template is used to show the additional fields, which when added to the cart, are stored as line item attributes.

Each denomination of the gift card and gift card type (physical or digital) should be defined as a separate variant of the Shopify product. The SKU structure should define the type and denomination so you might have giftcard-p-20, giftcard-p-40, giftcard-e-20, giftcard-e-40. The frontend template should allow the customer to select a gift card type (physical/digital) and then a denomination, which should select the appropriate variant.

When added to the cart with these attributes, the rest of the process works like any other product through to checkout. When DotApparel receives the order, it will send the appropriate attributes to Apparel21 where a new voucher will be generated, and in the case of a digital voucher, an email will be sent directly from Apparel21 to the receiver, containing the voucher number and PIN.

Reducing fraud risk

Gift vouchers are subject to a high risk of fraudulent transactions. When a digital voucher is purchased, Apparel21 will immediately generate a voucher and email it to the receiver. If the purchaser has used fraudulent card details, this means that the merchant could be subject to a chargeback, but the attacker has already received their voucher number and PIN. By the time the fraud has been detected, the attacker could have purchased physical items from a store using the voucher at POS, which would not be recoverable.

DotDev strongly recommends that the Shopify Fraud prevention system is utilised to detect potentially fraudulent transactions. Orders which are marked as fraud can be prevented from reaching Apparel21 using the following process.

1. In Shopify, configure transactions do not automatically capture, this means that by default, all payments will be authorized but not yet captured

2. Install and configure the Shopify Flow app to check the fraud rating assigned by Shopify to each order, and also the value of any gift cards added to the order
3. If Shopify has assigned the order a low fraud rating, and the value of the gift cards is low (e.g. under $500), set Shopify Flow to automatically capture the payment on the order, this will result in the order flowing through to Apparel21 and the voucher being generated/sent

4. If Shopify has assigned the order a high fraud rating, or the value of the gift cards in the order is suspiciously high (e.g. more than $500), do not automatically capture the order

5. Orders which have not automatically been captured will remain in Shopify in an authorized state and can be reviewed from within the Shopify admin panel

6. The merchant should manually review these orders, including contacting the customer for further identification details. If the customer cannot adequately identify themselves as a legitimate order, the order should be cancelled in Shopify, which will simply let the authorization expire (thus not costing the merchant any transaction fees). If the order is deemed to not be fraudulent, the merchant should capture the payment using the button in Shopify, which will then trigger the sync to Apparel21, thus generating and dispatching the voucher.

Redeeming vouchers

As the Apparel21 voucher redemption process is quite complicated, DotDev provides a premade Javascript widget to be included in the checkout template. This widget will display the Apparel21 gift card form, and perform the logic required to redeem the voucher.

DotApparel provides a solution for redeeming Apparel21 vouchers at the Shopify checkout. This requires checkout customisations to be enabled, which is only available on the Shopify Plus plan as a custom form needs to be embedded into the checkout, to capture the voucher number and PIN.

Shopify itself only understands Shopify gift cards, and there is no other mechanism for applying a voucher-type discount to a Shopify order. Therefore, the DotApparel solution works by first capturing the voucher number and PIN from the customer, before validating that information with Apparel21 to check the number, PIN, and balance.

If the voucher is valid, a temporary Shopify gift card is created equal to the balance of the Apparel21 voucher. Behind the scenes, the Shopify gift card is applied to the checkout which reduces the payable amount. However, due to the checkout customisations, it looks like the Apparel21 voucher itself has been applied against the order.

When the order is completed, DotApparel detects that a Shopify gift card has been applied against the order, and swaps it out for the real Apparel21 voucher before sending the order to Apparel21. When Apparel21 receives the order, the voucher balance is deducted accordingly.

Because this solution uses temporary Shopify gift cards, it is to be expected that the Shopify backend will show a list of gift cards in the admin panel. These gift cards should be ignored as they are only for internal purposes. It is not possible to use Shopify gift cards at the same time as Apparel21 vouchers, any vouchers must be generated in Apparel21.

Check balance API

POST https://{shopDomain}/apps/dotapparel/api-checkGiftcardBalance

{
    "number": "4213925",
    "pin": "30411"
}

// Response
{
  status: "success",
  data: {
    voucherNumber: "4213925",
    expiryDate: "2023-12-01",
    originalAmount: "100",
    usedAmount: "0",
    availableAmount: "100",
  },
}