How to enable your customers to pay with gift cards

Introduction

Selling and redeeming gift cards is a common and sensible practice in e-commerce for several reasons.

Firstly, gift cards provide a guaranteed revenue stream upfront, even if the cards are redeemed at a later date. This helps improve cash flow and provides financial stability for businesses.

Secondly, gift cards can drive customer loyalty and increase customer engagement. When customers receive gift cards, they are more likely to return to the online store or website to make purchases, potentially leading to repeat business.

Additionally, gift cards offer a convenient gifting option, attracting more customers and expanding the customer base. Overall, selling and redeeming gift cards in e-commerce presents a win-win situation, benefiting both sellers and customers.

To accommodate the selling and redeeming of gift cards the SCAYLE platform provides proven processes and a Checkout Gift Card API through which third-party gift card providers can be connected via middleware. Both scenarios will be described in detail in the following chapters.

Prerequesites

Before you tackle this topic, you should have a basic understanding of how products are handled in SCAYLE. Please read the following chapters:

• Creating Products
• Creating Variants
• Adding Stock

Selling of gift cards

In the standard, gift cards are created and treated as normal shop products and follow the same product data flow as other products. Please note that it's the responsibility of an external system to generate gift card codes and provide them to the customer after SCAYLE delegates an order containing a gift card to the client's system.

Product structure

Checkout Rule Engine

The Rule Engine can be used to enable or disable certain shipping or payment options when at least one gift card is included in an order. Typical use cases of the Rule Engine usage for gift cards are:

• deactivate certain payment methods like invoice or cash on delivery when purchasing gift cards,
• have a certain carrier for digital gift cards (e.g. “email”) with free delivery,
• disable the possibility of purchasing digital gift cards and regular products in one order.

Frontend wizard

Another typical use case is to provide input fields like “from”, “to” and “text” in a custom build wizard in the frontend to enable the customer to individualize their gift card. On the SCAYLE side, these values can be stored on the item’s customData object.

Usage of gift cards

System Context Diagram

A middleware sits between SCAYLE’s Checkout Gift Card API and the gift card provider(s) to map the requests from Checkout to the format of the third-party system(s) used by a tenant. In the case of multiple providers, the middleware is used as a gateway.

Technical prerequisites

To connect the SCAYLE Checkout Gift Card API to a third-party gift card provider you must provide a middleware that can support the following operations via an API so that the checkout and a gift card provider can be coupled:

Request headers

For every endpoint, the following request headers must be provided:

/gift-cards/balance

The gift card balance is requested during the customer checkout session when the customer wishes to apply a gift card to the order.

Based on the response of this endpoint, the customer may progress to the order confirmation with the gift card alone, or apply an additional payment method to cover the difference between the gift card value and the total order value.

This request is blocking for the customer, so it should be designed in the most performant manner possible.

Example request body

json

Copy

{
  "code": "aa34-234f-7b3e", // string (maximum length: 30)
  "currencyCode": "EUR", // string (length: 3)
  "pin": "1234", // string (optional) (maximum length: 10)
  "transactionKey": "fc68ff99b453c1d302c26b46b68f" // string
}

Example response

json

Copy

{
  "code": "aa34-234f-7b3e", // string (maximum length: 30)
  "currencyCode": "EUR", // string (length: 3)
  "isActive": true, // boolean
  "pin": "1234", // string (optional) (maximum length: 10)
  "serial": 123456789012345, // integer (optional)
  "status": { // object - all values in cents
    "balance": 30000, // integer
    "capturedAmount": 10000, // integer (optional)
    "initialAmount": 40000, // integer (optional)
    "refundedAmount": 0 // integer (optional)
  },
  "transactionKey": "fc68ff99b453c1d302c26b46b68f" // string
}

Status Codes

/gift-cards/cancel

The cancellation of a variable for payment via gift card is comparable to the cancellation of authorized amounts on individual payment methods. It is triggered after a cancellation notification (indicating that items are out of stock) has been received for either individual order items or the complete order or if there are issues in the confirmation process of an order, necessitating a rollback of all payment authorizations/captures.

Should the order feature an additional payment method, the amount due to the payment method would be refunded first, and then the balance of the gift card increased with the remaining amount due.

Should the initial cancellation request fail, it will be repeated for another 24 hours after the first attempt.

The transactionKey should be applied whenever handling a cancellation occurs, i.e. only one cancellation per transaction key should be processed. If a duplicate request is sent (possibly due to a timeout in the client system during the previous request), it should be immediately rejected with a 409 status code.

Example request body

json

Copy

{
  "amount": 1000, // integer
  "code": "aa34-234f-7b3e", // string
  "currencyCode": "EUR", // string (length: 3)
  "orderId": 2345234, // integer
  "pin": "1234", // string (optional) (maximum length: 10)
  "transactionKey": "8ff99b453c1d302c26b46b68ffc6" // string
}

Example response

json

Copy

{
    "amount": 1000, // integer
    "card": { // object
        "code": "aa34-234f-7b3e", // string (maximum length: 30)
        "currencyCode": "EUR", // string (length: 3)
        "isActive": true, // boolean
        "pin": "1234", // string (optional) (maximum length: 10)
        "serial": 123456789012345, // integer (optional)
        "status": { // object - all values in cents
            "balance": 30000, // integer
            "capturedAmount": 10000, // integer (optional)
            "initialAmount": 40000, // integer (optional)
            "refundedAmount": 0 // integer (optional)
        }
    },
    "orderId": 2345234 // integer (optional)
    "transactionKey": "8ff99b453c1d302c26b46b68ffc6" // string
}

Status Codes

/gift-cards/capture

The capture for payment via gift card is comparable to the instant capture of individual payment methods. It is triggered directly after order confirmation, or - if the order value dictates it, after the payment reservation (deferred payment) or capture (immediate payment) of an additional payment method. Once the capture has been completed, the available amount on the gift card should be reduced accordingly (by the captured amount).

If the request fails, then it will be repeated for a period of 24 hours while all further order processing is put on hold. After a final failure at the close of the 24 hours, the order will be cancelled. Any additional payment reservation will be cancelled or a refund initiated for captured funds. Should a voucher be applied to the order, it will also be detached (and in the case of single-use vouchers, reusable once again).

Once the request is resolved successfully, the order will advance to the next step in the order lifecycle: adjustment of internal quantities and delegation of the order to the merchant / warehouse system.

The transactionKey should be applied whenever handling a capture occurs, i.e. only one capture per transaction key should be processed. If a duplicate request is sent (possibly due to a timeout in the client system during the previous request), it should be immediately rejected with a 409 status code.

Example request body

json

Copy

{
    "amount": 1000, // integer
    "code": "aa34-234f-7b3e", // string (maximum length: 30)
    "currencyCode": "EUR", // string (length: 3)
    "orderId": 2345234, // integer
    "pin": "1234", // string (optional) (maximum length: 10)
    "transactionKey": "8ff99b453c1d302c26b46b68ffc6" // string
}

Example response

json

Copy

{
    "amount": 1000, // integer
    "card": { // object
        "code": "aa34-234f-7b3e", // string (maximum length: 30)
        "currencyCode": "EUR", // string (length: 3)
        "isActive": true, // boolean
        "pin": "1234", // string (optional) (maximum length: 10)
        "serial": 123456789012345, // integer (optional)
        "status": { // object - all values in cents
            "balance": 30000, // integer
            "capturedAmount": 10000, // integer (optional)
            "initialAmount": 40000, // integer (optional)
            "refundedAmount": 0 // integer (optional)
        }
    },
    "orderId": 2345234 // integer (optional)
    "transactionKey": "8ff99b453c1d302c26b46b68ffc6" // string
}

Status Codes

/gift-cards/refund

The refund for payment via gift card is comparable to the refunding of individual payment methods. It is triggered after a return notification has been received for either individual order items or the complete order.

Should the order feature an additional payment method, the amount due to the payment method would be refunded first, and then the balance of the gift card increased with the remaining amount due.

Should the initial refund request fail, it will be repeated for another 24 hours after the first attempt.

The transactionKey should be applied whenever handling a refund occurs, ie only one refund per transaction key should be processed. If a duplicate request is sent (possibly due to a timeout in the client system during the previous request), it should be immediately rejected with a 409 status code.

Example Request Body

json

Copy

{
    "amount": 1000, // integer
    "code": "aa34-234f-7b3e", // string (maximum length: 30)
    "currencyCode": "EUR", // string (length: 3)
    "orderId": 2345234, // integer
    "pin": "1234", // string (optional) (maximum length: 10)
    "transactionKey": "8ff99b453c1d302c26b46b68ffc6" // string
}

Example Response

json

Copy

{
    "amount": 1000, // integer
    "card": { // object
        "code": "aa34-234f-7b3e", // string (maximum length: 30)
        "currencyCode": "EUR", // string (length: 3)
        "isActive": true, // boolean
        "pin": "1234", // string (optional) (maximum length: 10)
        "serial": 123456789012345, // integer (optional)
        "status": { // object - all values in cents
            "balance": 30000, // integer
            "capturedAmount": 10000, // integer (optional)
            "initialAmount": 40000, // integer (optional)
            "refundedAmount": 0 // integer (optional)
        }
    },
    "orderId": 2345234 // integer (optional)
    "transactionKey": "8ff99b453c1d302c26b46b68ffc6" // string
}

Status Codes

Transaction Security

A transactionKey is supplied in the request body with every non-idempotent transaction. This is to ensure, that the service provider can securely differentiate between an initial request (such as a create, capture, or refund gift card) and any subsequent repeats, which may occur if the client system experiences a timeout on the initial call. It is the service provider's responsibility to ensure, that only one operation is processed per unique transactionKey.

Should a transactionKey be applied a second time, the service provider should respond with a 409 status code, and a representation of the requested entity (such as a gift card) in the response body.

Scoping of Gift Cards

Should the necessity arise to limit the applicability of gift cards to certain currencies, countries, or shops, it is the service provider's responsibility to manage these restrictions.

The Shop ID will be passed in the header of every request. Should an operation not be possible, due to for example a currency restriction, the service provider should respond with a 417 status code.

Frontend configurations

The gift card feature of SCAYLE’s checkout can be configured via the Panel in the Checkout → Configurations → Features → Gift cards area.

General Settings

1. Enabled - activates a gift card number input field on checkout,
2. Format - allows to define a regex for the frontend validation of gift card numbers,
3. Min & Max Length - allows to define the length of a gift card number,
4. Required - allows to define if gift cards must be mandatory for all customers,
5. Illegal Terms - strings that cannot be inputted as a gift card number,
6. Layered Validation - allows to define custom validations of gift card numbers and error messages for them.

PIN

1. Enabled - activates a pin input field on checkout,
2. Format - allows to define a regex for the frontend validation of pins,
3. Min & Max Length - allows to define the length of a pin,
4. Required - allows to define if pins must be mandatory for all customers,
5. Illegal Terms - strings that cannot be inputted as pins,
6. Layered Validation - allows to define custom validations of pins and error messages for them.

Broken link

Orders in the Admin API

A gift card is treated as a regular payment method. In case of a “mixed” payment between a regular payment method and a gift card, the order will have two attached payment methods.

Example response for /shops/:shopKey/countries/:countryCode/orders/:orderIdentifier:

json

Copy

"payment": [
    {
        "key": "giftcard",
        "amount": 5000,
        "data": {
            "amount": 10000,
            "giftCardCode": "example:12345678",
            "serial": example:12345678,
            "success": true,
            "transaction_id": "example:12345678",
            "type": "giftcard"
        },
        "transactionKey": "example:12345678",
        "isGiftCard": true
    }
],

Transactional emails

The following payment keys must be used in transactional emails:

• isGiftCardOnly - a gift card was used as the only payment method,
• isGiftCard - another payment method was also used in an order.

\