Gift Card Payments

The MasterCard Payment Gateway allows you to offer gift cards as a method of payment to your payers.

Prerequisites

  • You must have signed up with a third-party provider for the cards.
  • Your payment service provider must configure your MasterCard Payment Gateway merchant profile using the details of your account with the third-party provider.

Adding Gift Cards to your Integration

The gateway provides three options to integrate Gift Cards into your payment page:

Gift Cards via Hosted Checkout

If you have an existing Hosted Checkout integration, you can use Hosted Checkout to verify the gift card details.

You can do this by setting interaction.operation=VERIFY in the Create Checkout Session request. Hosted Checkout displays Gift Card as a payment option to the payer. The data entered by the payer is verified using the verification methods supported by the configured acquirer.

You can determine the success of the verification operation by comparing resultIndicator to successIndicator. If the interaction was not successful, Hosted Checkout displays a message indicating that verification has failed and prompts the payer to try again.

Gift Cards via Hosted Session

If you have your own payment page then you can choose the Hosted Session integration option to have the MasterCard Payment Gateway securely capture the gift card details and store them into a payment session.

Sample Code to Collect Gift Card Details
<html>
<head>
<!-- INCLUDE SESSION.JS JAVASCRIPT LIBRARY -->
<script src="https://eu-gateway.mastercard.com/form/version/72/merchant/<MERCHANTID>/session.js"></script>
<!-- APPLY CLICK-JACKING STYLING AND HIDE CONTENTS OF THE PAGE -->
<style id="antiClickjack">body{display:none !important;}</style>
</head>
<body>

<!-- CREATE THE HTML FOR THE PAYMENT PAGE -->

<div>Please enter your Gift Card details:</div>
<div>Card Number: <input type="text" id="gift-card-number" class="input-field" value="" readonly></div>
<div>Pin:<input type="text" id="gift-card-pin" class="input-field" value="" readonly></div>
<div><button id="payButton" onclick="pay();">Pay Now</button></div>

<!-- JAVASCRIPT FRAME-BREAKER CODE TO PROVIDE PROTECTION AGAINST IFRAME CLICK-JACKING -->
<script type="text/javascript">
if (self === top) {
    var antiClickjack = document.getElementById("antiClickjack");
    antiClickjack.parentNode.removeChild(antiClickjack);
} else {
    top.location = self.location;
}

PaymentSession.configure({
    fields: {
        // ATTACH HOSTED FIELDS TO YOUR PAYMENT PAGE FOR A GIFT CARD
        giftCard: {
        	number: "#gift-card-number",
        	pin: "#gift-card-pin",
        }
    },
    //SPECIFY YOUR MITIGATION OPTION HERE
    frameEmbeddingMitigation: ["javascript"],
    callbacks: {
        initialized: function(response) {
            // HANDLE INITIALIZATION RESPONSE
        },
        formSessionUpdate: function(response) {
            // HANDLE RESPONSE FOR UPDATE SESSION
            if (response.status) {
                if ("ok" == response.status) {
                    console.log("Session updated with data: " + response.session.id);
  
                } else if ("fields_in_error" == response.status)  {
  
                    console.log("Session update failed with field errors.");
                    if (response.errors.number) {
                        console.log("Gift card number invalid or missing");
                    }
                    if (response.errors.pin) {
                        console.log("Pin invalid.");
                    }
                } else if ("request_timeout" == response.status)  {
                    console.log("Session update failed with request timeout: " + response.errors.message);
                } else if ("system_error" == response.status)  {
                    console.log("Session update failed with system error: " + response.errors.message);
                }
            } else {
                console.log("Session update failed: " + response);
            }
        }
      }
  });

function pay() {
    // UPDATE THE SESSION WITH THE INPUT FROM HOSTED FIELDS
    PaymentSession.updateSessionFromForm('giftCard', '<localCardBrand>');
}
</script>
</body>
</html>
  1. Include the session.js client JavaScript library hosted by the gateway in your payment page. The path to this file includes both the api version and the merchant identifier for the session.
  2. Create the HTML for the payment page containing the gift card fields.
    To prevent submission of sensitive data to the server, ensure the sensitive data fields are readonly and do NOT have the name attribute.
  3. Invoke PaymentSession.configure(configuration) function.

    The configuration object allows you to attach hosted fields to your payment page. You need to provide the following:

    • session(optional), if you do not provide one, the client library creates a payment session.
    • field selectors for gift card fields, which when provided are replaced with corresponding proxy fields embedded in iFrames hosted by the MasterCard Payment Gateway. The proxy fields will have the same look and feel as the replaced fields.
    • mitigation option(s) for clickjacking prevention

      Clickjacking, also known as a "UI redress attack", is when an attacker uses multiple transparent or opaque layers to trick a user into clicking on a button or link on another page when they were intending to click on the top level page. To use Hosted Session, you must implement one or more of the following defenses against clickjacking attacks.

      Frame Mitigation Option Implementation
      javascript include "frame-breaker" JavaScript in your payment page.
      x-frame-options your server should return an X-Frame Options HTTP response header.
      csp your server should return Content-Security-Policy HTTP response header containing a frame-ancestors directive.

      You must specify which defenses are implemented via the frameEmbeddingMitigation parameter in the PaymentSession.configure(configuration) call. For information on defending against clickjacking attacks, see Clickjacking Defense Cheat Sheet on the OWASP External Website.

    • callbacks for handling various events during the Hosted Session interaction
      • initialized( ): invoked when the hosted fields attach to your payment page.
      • formSessionUpdate( ): invoked in response to the PaymentSession.updateSessionFromForm('giftCard', <localCardBrand>) function (see next step)

  4. Invoke PaymentSession.updateSessionFromForm('giftCard', <localCardBrand>) to store the collected gift card details into a payment session. Once the operation completes, formSessionUpdate( ) callback is invoked with a result parameter. You must check the result.status value to determine if the operation was successful. See Handle Callback Responses.
  5. You can use the returned payment session (session.id) to perform a tokenization or a payment transaction when required. For more information, see Perform an Operation Using the Session.

session.js Reference[JavaScript]

Gift Cards via Direct Payment

If you want full control over the Gift Cards interaction on your payment page, you can choose the Direct Payment option.

Gift Cards is supported by API versions 31 and above.
Request an Authorization or Payment using Gift Card

You need to provide the following fields in the Authorize request:

  • sourceOfFunds.type=GIFT_CARD
  • sourceOfFunds.provided.giftCard.number: Gift card number.
  • sourceOfFunds.provided.giftCard.pin: Gift card PIN. (Not always mandatory, depending on the gift card.)
  • order.amount: Amount to be paid.
  • order.currency: Currency of payment.
  • order.acceptPartialAmount: (Optional) Indicates whether you are prepared to accept the card for partial payment of the full amount. The default value for this is FALSE.

In addition to the standard fields, the following fields are returned for a successful authorization:

  • sourceOfFunds.type: GIFT_CARD, mirroring your request.
  • sourceOfFunds.provided.giftCard.number: Gift card number (masked).
  • sourceOfFunds.provided.giftCard.pin: Gift card PIN (fully masked).
  • sourceOfFunds.provided.giftCard.scheme: The organization that owns a gift card brand and defines operating regulations for its use.
  • sourceOfFunds.provided.giftCard.brand: The brand name used to describe the gift card that is recognized and accepted globally. For many major card types this will match the scheme name.
  • sourceOfFunds.provided.giftCard.localBrand: The brand name used to describe a gift card as determined by the gateway based on the BIN range of the card.
  • availableBalance.funds.amount: The amount available to the payer to spend using this gift card after this payment. (Provision of this information depends on the third-party provider.)
  • availableBalance.funds.currency: The currency of the available balance on the card expressed as an ISO 4217 alpha code, e.g. USD.
  • order.amount: Accepted amount. Note that this may be less than the amount requested, if the card does not have sufficient funds and you have set order.acceptPartialAmount=TRUE.
  • transaction.requestedAmount: If the transaction was partially approved (response.gatewayCode=PARTIALLY_APPROVED), this contains the originally requested amount.

    If you have set order.acceptPartialAmount=TRUE, transaction.amount and order.amount are set to the actually approved amount.
Verify Gift Card

You can verify that a gift card with the provided card number (and PIN) is a valid gift card issued by the provider by submitting an APIVERIFY request.

Verify API Reference [REST][NVP]

Balance Inquiry

You can inquire about the available balance on a gift card by submitting an API BALANCE_INQUIRY request. You need to provide the following in the request:

  • sourceOfFunds.type=GIFT_CARD
  • sourceOfFunds.provided.card.number: The gift card number for which you are requesting balance information.

Balance Inquiry API Reference[REST][NVP]

Manage Partial Approvals

If you are prepared to accept an approval for a partial amount for a transaction using a gift card, you must submit order.acceptPartialAmount=TRUE in your request. In this case you are responsible for creating another transaction for the outstanding balance using some other means of payment.

If you are not prepared to do this, set order.acceptPartialAmount=FALSE in your request. If insufficient funds are available on the gift card, the MasterCard Payment Gateway will respond with response.gatewayCode=INSUFFICIENT_FUNDS.

Card Details API Reference[REST][NVP]

Test and Go Live

You can test your gift card integration using your test merchant profile.

Copyright © 2023 MasterCard