Δωροκάρτα
Το Mastercard Gateway σας δίνει τη δυνατότητα να προσφέρετε δωροκάρτες ως τρόπο πληρωμής στους πληρωτές σας.
Προαπαιτούμενα
- Πρέπει να έχετε εγγραφεί σε έναν τρίτο πάροχο για τις κάρτες.
- Your payment service provider πρέπει να διαμορφώσετε το Mastercard Gateway προφίλ εμπόρου σας χρησιμοποιώντας τα στοιχεία του λογαριασμού σας με τον τρίτο πάροχο.
Προσθήκη δωροκαρτών στην ενοποίησή σας
Η πύλη παρέχει τρεις επιλογές για την ενοποίηση δωροκαρτών στη σελίδα πληρωμής σας:
Δωροκάρτες μέσω Hosted Checkout
Αν έχετε μια υπάρχουσα ενοποίηση Hosted Checkout, μπορείτε να χρησιμοποιήσετε το Hosted Checkout για να επαληθεύσετε τις λεπτομέρειες της δωροκάρτας.
Αυτό μπορείτε να το κάνετε ρυθμίζοντας το interaction.operation=VERIFY στο αίτημα Create Checkout Session. Το Hosted Checkout εμφανίζει τη δωτοκάρτα ως μια επιλογή πληρωμής στον πληρωτή. Τα δεδομένα που εισάγονται από τον πληρωτή επαληθεύονται χρησιμοποιώντας τις μεθόδους επαλήθευσης που υποστηρίζονται από τη διαμορφωμένη τράπεζα εμπόρου.
Μπορείτε να καθορίσετε την επιτυχία της πράξης επαλήθευσης συγκρίνοντας την παράμετρο resultIndicator με την παράμετρο successIndicator. Αν η αλληλεπίδραση δεν ήταν επιτυχής, το Hosted Checkout εμφανίζει ένα μήνυμα που υποδεικνύει ότι η επαλήθευση απέτυχε και προτρέπει τον πληρωτή να δοκιμάσει ξανά.
Δωροκάρτες μέσω Hosted Session
Αν έχετε τη δική σας σελίδα πληρωμής, μπορείτε να κάνετε την επιλογή ενοποίησης Hosted Session προκειμένου το Mastercard Gateway να δεσμεύσει με ασφάλεια τις λεπτομέρειες της δωροκάρτας και να τις αποθηκεύσει ένα session πληρωμής (payment session).
<html>
<head>
<!-- INCLUDE SESSION.JS JAVASCRIPT LIBRARY -->
<script src="https://mtf.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.jsJavaScript πελάτη που φιλοξενείται από την πύλη στη σελίδα πληρωμής σας. Η διαδρομή προς αυτό το αρχείο περιλαμβάνει τόσο την έκδοση API όσο και το αναγνωριστικό εμπόρου για την περίοδο λειτουργίας (session). - Δημιουργήστε την HTML για τη σελίδα πληρωμής που περιέχει τα πεδία δωροκάρτας.
Για να αποτρέψετε την υποβολή ευαίσθητων δεδομένων στον διακομιστή, βεβαιωθείτε ότι τα πεδία ευαίσθητων δεδομένων είναιreadonlyκαι ΔΕΝ έχουν το χαρακτηριστικόname. - Κάντε επίκληση στη συνάρτηση
PaymentSession.configure(configuration).
Το αντικείμενο
configurationσάς επιτρέπει να προσαρτήσετε hosted πεδία στη σελίδα πληρωμής σας. Πρέπει να δώσετε τα εξής:
- session(optional), αν δεν το δώσετε, η βιβλιοθήκη πελάτη δημιουργεί ένα session πληρωμής (payment session).
- επιλογείς πεδίων για πεδία δωροκάρτας, οι οποίοι όταν παρέχονται, αντικαθίστανται από αντίστοιχα πεδία μεσολάβησης ενσωματωμένα σε iFrames που φιλοξενούνται από το Mastercard Gateway. Τα πεδία μεσολάβησης θα έχουν την ίδια εμφάνιση και αίσθηση με τα αντικατεστημένα πεδία.
- επιλογές μετριασμού για την αποτροπή clickjacking
Το clickjacking, γνωστό και ως "επίθεση επανόρθωσης UI", είναι όταν ένας εισβολέας χρησιμοποιεί πολλαπλά διαφανή ή αδιαφανή επίπεδα για να εξαπατήσει έναν χρήστη να κάνει κλικ σε ένα κουμπί ή σε έναν σύνδεσμο σε άλλη σελίδα ενώ σκόπευε να κάνει κλικ στη σελίδα του ανώτερου επιπέδου. Για να χρησιμοποιήσετε το Hosted Session, πρέπει να εφαρμόσετε μία ή περισσότερες από τις ακόλουθες δυνατότητες άμυνας κατά των επιθέσεων clickjacking.
Επιλογή μετριασμού πλαισίων Υλοποίηση javascriptσυμπεριλάβετε ένα JavaScript "frame-breaker" στη σελίδα πληρωμής. x-frame-optionsο διακομιστής σας πρέπει να επιστρέψει μια κεφαλίδα απόκρισης X-Frame Options HTTP. cspο διακομιστής σας θα πρέπει να επιστρέψει την κεφαλίδα απόκρισης Content-Security-Policy HTTP που περιέχει μια οδηγία frame-ancestors. Πρέπει να καθορίσετε ποιες άμυνες υλοποιούνται μέσω της παραμέτρου
frameEmbeddingMitigationστην κλήσηPaymentSession.configure(configuration). Για πληροφορίες σχετικά με την υπεράσπιση των επιθέσεων clickjacking, βλ. το Clickjacking Defense Cheat Sheet στον εξωτερικό ιστότοπο OWASP. - ανακλήσεις για τον χειρισμό διαφόρων συμβάντων κατά τη διάρκεια της αλληλεπίδρασης Hosted Session
initialized( ): γίνεται επίκληση όταν τα hosted πεδία προσαρτώνται στη σελίδα πληρωμής σας.formSessionUpdate( ): γίνεται επίκληση σε απόκριση στη συνάρτησηPaymentSession.updateSessionFromForm('giftCard', <localCardBrand>)(βλ. επόμενο βήμα)
- Γίνεται επίκληση του
PaymentSession.updateSessionFromForm('giftCard', <localCardBrand>)για αποθήκευση των λεπτομερειών δωροκάρτας που συλλέγονται σε ένα session πληρωμής (payment session). Μόλις ολοκληρωθεί η διαδικασία, γίνεται επίκληση της ανάκλησηςformSessionUpdate( )με μια παράμετρο αποτελέσματος. Πρέπει να ελέγξετε την τιμήresult.statusγια να καθορίσετε αν η πράξη ήταν επιτυχής. Βλ. Χειρισμός αποκρίσεων ανάκλησης. - Μπορείτε να χρησιμοποιήσετε την επιστρεφόμενη περίοδο λειτουργίας πληρωμής (session.id) για να εκτελέσετε μια συναλλαγή tokenization ή πληρωμής, όταν απαιτείται. Για περισσότερες πληροφορίες, βλ. Εκτέλεση πράξης χρησιμοποιώντας την περίοδο λειτουργίας.
Αναφορά session.js[JavaScript]
Δωροκάρτες μέσω Direct Payment
Αν θέλετε πλήρη έλεγχο της αλληλεπίδρασης με δωροκάρτες στη σελίδα πληρωμής σας, μπορείτε να κάνετε την επιλογή Direct Payment.
Αίτημα έγκρισης ή πληρωμής χρησιμοποιώντας δωροκάρτα
Πρέπει να δώσετε τα ακόλουθα πεδία στο αίτημα Authorize:
sourceOfFunds.type=GIFT_CARDsourceOfFunds.provided.giftCard.number: Αριθμό δωροκάρτας.sourceOfFunds.provided.giftCard.pin: PIN δωροκάρτας. (Δεν είναι πάντα υποχρεωτικό, ανάλογα με τη δωροκάρτα.)order.amount: Ποσό για πληρωμή.order.currency: Νόμισμα πληρωμής.order.acceptPartialAmount: (Προαιρετικό) Υποδεικνύει αν είστε έτοιμοι να δεχτείτε την κάρτα για μερική πληρωμή του πλήρους ποσού. Η προεπιλεγμένη τιμή για αυτό είναιFALSE.
Επιπλέον των βασικών πεδίων, επιστρέφονται τα ακόλουθα πεδία για μια επιτυχημένη έγκριση:
sourceOfFunds.type:GIFT_CARD, αντανακλώντας το αίτημά σας.sourceOfFunds.provided.giftCard.number: Αριθμό δωροκάρτας (με απόκρυψη).sourceOfFunds.provided.giftCard.pin: PIN δωροκάρτας (με πλήρη απόκρυψη).sourceOfFunds.provided.giftCard.scheme: Ο οργανισμός στον οποίο ανήκει ένα είδος δωροκάρτας και ορίζει τους κανονισμούς λειτουργίας που διέπουν τη χρήση της.sourceOfFunds.provided.giftCard.brand: Το εμπορικό σήμα που χρησιμοποιείται για να περιγράψει τη δωροκάρτα, το οποίο αναγνωρίζεται και είναι αποδεκτό παγκοσμίως. Για πολλούς σημαντικούς τύπους καρτών, συνήθως είναι ίδιο με το όνομα του προγράμματος.sourceOfFunds.provided.giftCard.localBrand: Το όνομα εταιρείας που χρησιμοποιείται για να περιγράψει μια δωροκάρτα όπως προσδιορίζεται από την πύλη βάσει της περιοχής BIN της κάρτας.availableBalance.funds.amount: Το ποσό που διατίθεται στον πληρωτή να δαπανήσει χρησιμοποιώντας αυτή τη δωροκάρτας μετά από αυτή την πληρωμή. (Η παροχή αυτών των πληροφοριών εξαρτάται από τον τρίτο πάροχο.)availableBalance.funds.currency: Το νόμισμα του διαθέσιμου υπολοίπου της κάρτας εκφράζεται ως άλλος άλφα κωδικός ISO 4217, π.χ. USD.order.amount: Αποδεκτό ποσό. Σημειώστε ότι αυτό μπορεί να είναι μικρότερο από το ποσό που ζητήθηκε, αν η κάρτα δεν διαθέτει επαρκή χρήματα και έχετε ορίσειorder.acceptPartialAmount=TRUE.transaction.requestedAmount: Αν η συναλλαγή εγκρίθηκε μερικώς (response.gatewayCode=PARTIALLY_APPROVED), περιέχει το αρχικά ζητούμενο ποσό.
Αν ορίσατεorder.acceptPartialAmount=TRUE, ταtransaction.amountκαιorder.amountορίζονται στο πραγματικά εγκεκριμένο ποσό.
Επαλήθευση δωροκάρτας
Μπορείτε να επαληθεύσετε ότι μια δωροκάρτα με τον παρεχόμενο αριθμό κάρτας (και το PIN) είναι μια έγκυρη δωροκάρτα που εκδίδεται από τον πάροχο, υποβάλλοντας ένα αίτημα APIVERIFY.
Verify - Αναφορά API [REST][NVP]
Balance inquiry
Μπορείτε να ρωτήσετε για το διαθέσιμο υπόλοιπο σε μια δωροκάρτα, υποβάλλοντας ένα αίτημα API BALANCE_INQUIRY. Πρέπει να δώσετε τα ακόλουθα στο αίτημα :
sourceOfFunds.type=GIFT_CARDsourceOfFunds.provided.card.number: Τον αριθμό της δωροκάρτας δώρου για την οποία ζητάτε πληροφορίες σχετικά με το υπόλοιπο.
Balance Inquiry - Αναφορά API[REST][NVP]
Διαχείριση μερικών εγκρίσεων
Αν είστε έτοιμοι να δεχτείτε έγκριση για μερικό ποσό για μια συναλλαγή χρησιμοποιώντας μια δωροκάρτα, πρέπει να υποβάλετε το order.acceptPartialAmount=TRUE στο αίτημά σας. Σε αυτή την περίπτωση, είστε υπεύθυνοι για τη δημιουργία μιας άλλης συναλλαγής για το υπόλοιπο ποσό χρησιμοποιώντας κάποιον άλλο τρόπο πληρωμής.
Αν δεν είστε έτοιμοι να το κάνετε, ορίστε το order.acceptPartialAmount=FALSE στο αίτημά σας. Αν στην κάρτα δώρου δεν υπάρχουν επαρκή χρήματα, το Mastercard Gateway θα αποκριθεί με response.gatewayCode=INSUFFICIENT_FUNDS.
Λεπτομέρειες κάρτας - Αναφορά API[REST][NVP]
Δοκιμή και έναρξη λειτουργίας
Μπορείτε να δοκιμάσετε την ενοποίηση δωροκάρτας χρησιμοποιώντας το δοκιμαστικό προφίλ εμπόρου.