The Mastercard Payment Gateway allows you to offer gift cards as a method of payment to your payers.
The gateway provides three options to integrate Gift Cards into your payment page:
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.
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.
<html> <head> <!-- INCLUDE SESSION.JS JAVASCRIPT LIBRARY --> <script src="https://na.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>
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. readonly
and do NOT have the name
attribute.PaymentSession.configure(configuration)
function.The configuration
object allows you to attach hosted fields to your payment page. You need to provide the following:
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.
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)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.
session.js Reference[JavaScript]
If you want full control over the Gift Cards interaction on your payment page, you can choose the Direct Payment option.
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. order.acceptPartialAmount=TRUE
, transaction.amount
and order.amount
are set to the actually approved amount.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.
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.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
.
You can test your gift card integration using your test merchant profile.
Copyright © 2023 Mastercard