Gift Cards
Gift cards are prepaid stored-value cards that can be used as a payment method.
The following methods are supported:
| Integration Methods | Transactions* |
|---|---|
| All except Hosted Batch |
* Support depends on each gift card provider. For more information, contact your payment service provider. |
For limitations on the transactions you can use with specific integration methods, see Hosted Checkout, Hosted Session, and Direct Payment.
Prerequisites
To use gift cards as a payment method:
- You must sign up with a third-party provider for the cards.
- Your merchant profile must be configured by your payment service provider for the gift card provider.
About the method
Gift cards can be issued by various entities, such as retailers, businesses, or financial institutions. You need a separate agreement with each gift card provider you want to support.
Main supported features
When using gift cards as a payment method, you can:
- Perform payments using a single-action pay or the two-step authorization and capture transactions.
- Make refunds and voids, depending on the gift card provider*.
- Add supplementary data to your requests to make the payment more user-friendly for the payer or ease its processing in the payment system.
Required payment details
When using gift cards, you need to provide the following payment details to the Mastercard Gateway. Depending on your used integration, the gateway gathers the details through the checkout payment interface, from a session, or from a transaction request.
The following payment details are needed:
- Payment method (gift card).
- Gift card number.
- Gift card PIN, if required by the card.
In a transaction request, these details are provided as:
"sourceOfFunds": {
"type": "GIFT_CARD",
"provided": {
"giftCard": {
"number": "1234567",
"pin" : "1234"
}
}
}
Adding the method to your integration
Follow the instructions for the integration methods you want to use.
For examples of gift card transaction requests, download the postman collection.
Hosted Checkout
You can use the hosted payment page in a cardholder-initiated transaction (CIT) to verify the payer's gift card with the VERIFY transaction. Afterwards, to create a payment transaction, you need to send a merchant-initiated transaction (MIT), such as PAY.
To allow the payer to use a gift card in your Hosted Checkout integration, you must make the following customizations after implementing your generic Hosted Checkout integration:
- In the INITIATE CHECKOUT operation, set
interaction.operation = VERIFY. The hosted checkout page displays Gift Card as a payment option to the payer. - The gateway verifies the data entered by the payer using the verification methods supported by the configured acquirer.
You can determine the success of the verification operation by comparing the
resultIndicatorvalue returned in the payment response to thesuccessIndicatorvalue returned by the INITIATE CHECKOUT request.If the verification fails, the hosted checkout displays a related message to the payer and prompts them to try again.
Hosted Session
If you allow the payer to use a gift card in your Hosted Session integration, the gateway securely captures the gift card details and stores them into a payment session.
You must make the following customizations after implementing your generic Hosted Session integration :
- 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 set as
readonlyand omit thename attribute. - In the
PaymentSession.configure(configuration)function, provide the following details in the configuration object:- Session (optional)
If you do not provide one, the client library creates a payment session.
- Field selectors for gift card fields.
When provided, the selectors are replaced with corresponding proxy fields embedded in iFrames hosted by the gateway. The proxy fields have the same look and feel as the replaced fields.
- Mitigation options for clickjacking prevention. For more information, see Preventing Clickjacking.
- 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 thePaymentSession.updateSessionFromForm('giftCard', <localCardBrand>)function, see the next step.
- Session (optional)
- Call the
PaymentSession.updateSessionFromForm('giftCard', <localCardBrand>)function to store the collected gift card details into the payment session. Once the operation completes, theformSessionUpdate()callback is invoked with a result parameter. You must check theresult.statusvalue to determine if the operation was successful. For more information, see Payment Page Callbacks. - Use the session ID to perform the payment transaction. For more information, see Using a Session in a Payment Transaction.
Example of collecting gift card details
<html>
<head>
<!-- INCLUDE SESSION.JS JAVASCRIPT LIBRARY -->
<script src="https://test-gateway.mastercard.com/form/version/<version>/merchant/<merchant_ID>/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>
Direct Payment
To allow the payer to use a gift card in your Direct Payment integration, you can use the following transactions after implementing your generic Direct Payment integration:
- VERIFY
Use the transaction to verify that a gift card with the provided card number, and PIN, is a valid gift card issued by the provider.
- BALANCE INQUIRY
Use the transaction to inquire about the available balance on a gift card. You need to provide the following fields in the request:
sourceOfFunds.type = GIFT_CARDsourceOfFunds.provided.card.numberNumber of the gift card for which you are requesting balance information.
- AUTHORIZATION or PAY
Use the transaction to authorize or request payment. You need to provide the following fields in the request:
sourceOfFunds.type = GIFT_CARDsourceOfFunds.provided.giftCard.numberGift card number.
- sourceOfFunds.provided.giftCard.pin
Gift card PIN, can be mandatory depending on the gift card.
- order.amount
Amount to be paid.
- order.currency
Currency of the payment.
order.acceptPartialAmountWhether the gift card can be used for partial payment.
The field is optional and set to
FALSEby default.If you allow a gift card to be used for partial payment, you are responsible for creating another transaction for the outstanding balance using some other means of payment.
If the field is set to
FALSEand insufficient funds are available on the gift card, the gateway responds withresponse.gatewayCode = INSUFFICIENT_FUNDS.
In addition to the standard fields, the following fields are returned for a successful gift card transaction:
sourceOfFunds.type = GIFT_CARDAs in your request.
sourceOfFunds.provided.giftCard.numberMasked Gift card number.
sourceOfFunds.provided.giftCard.pinFully Masked Gift card PIN.
sourceOfFunds.provided.giftCard.schemeOrganization that owns a gift card brand and defines operating regulations for its use.
sourceOfFunds.provided.giftCard.brandBrand name used to describe the gift card that is recognized and accepted globally. For many major card types, this matches the scheme name.
sourceOfFunds.provided.giftCard.localBrandBrand name used to describe a gift card as determined by the gateway based on the Bank Identification Number (BIN) range of the card.
availableBalance.funds.amountAmount available to the payer to spend using this gift card after this payment, included if provided by the third-party provider.
availableBalance.funds.currencyCurrency of the available balance on the card expressed as an ISO 4217 alpha code, such as USD.
order.amountAccepted amount. If the card does not have sufficient funds and you have set
order.acceptPartialAmount = TRUE, the accepted amount can be less than the requested amount.order.acceptPartialAmountWhether a partial amount is accepted. With Vitamin Shoppe gift cards, you must set this to
TRUEin a PAY transaction.transaction.requestedAmountIf the transaction is partially approved,
response.gatewayCode = PARTIALLY_APPROVED, this contains the originally requested amount.If you have set
order.acceptPartialAmount = TRUE,transaction.amountandorder.amountare set to the actually approved amount.
Testing the method
For details on testing your integration with gift cards, see test cards and the testing instructions within each applicable integration method.