Εφαρμογή της Hosted Payment Page
Έχετε δύο επιλογές για την εφαρμογή του Hosted Payment Page:
- Η ενσωματωμένη σελίδα είναι ένα στοιχείο που ενεργοποιείται στην υπάρχουσα σελίδα checkout του ιστότοπού σας.
- Η σελίδα πληρωμής είναι μια ξεχωριστή σελίδα στην οποία ο πληρωτής ανακατευθύνεται από την υπάρχουσα σελίδα checkout.
Μόλις δημιουργηθεί μια περίοδος λειτουργίας (session) checkout, η διαδικασία υλοποίησης του Hosted Payment Page για Hosted Checkout αποτελείται από τα ακόλουθα βήματα:
- Δημιουργήστε ένα αντικείμενο checkout.
- Διαμορφώστε το αντικείμενο checkout.
- Χρησιμοποιήστε την κατάλληλη μέθοδο του αντικειμένου checkout για να ξεκινήσετε τη διαδικασία πληρωμής.
Επιπλέον, μπορείτε να ορίσετε ανακλήσεις που ενεργοποιούνται όταν ο πληρωτής πραγματοποιεί συγκεκριμένες ενέργειες κατά τη διαδικασία πληρωμής.
Η υλοποίηση του Hosted Payment Page πραγματοποιείται στην εφαρμογή ή στον ιστότοπό σας, χρησιμοποιώντας τη βιβλιοθήκη Checkout JavaScript (JS).
Βήμα 1: Δημιουργήστε το αντικείμενο checkout
Μετά την εκκίνηση της περίοδος λειτουργίας (session), πρέπει να ανατρέξετε στο αρχείο checkout.min.js από τον διακομιστή πύλης στη σελίδα checkout. Αυτό τοποθετεί ένα αντικείμενο Checkout σε παγκόσμια εμβέλεια.
<script src="https://gateway-japa.americanexpress.com/static/checkout/checkout.min.js" data-error="errorCallback" data-cancel="cancelCallback"></script>
Βήμα 2: Διαμορφώστε το αντικείμενο checkout
Καλέστε τη συνάρτηση Checkout.configure() και διαβιβάστε της ένα αντικείμενο JSON που περιλαμβάνει το session.id που επιστράφηκε από την πράξη Initiate Checkout νωρίτερα.
Checkout.configure({
session: {
id: '<your_initiate_checkout_ID>'
}
});
- Στο API v67 ή νεότερη, το αντικείμενο περιόδου λειτουργίας είναι το μόνο πεδίο που επιτρέπεται μέσω της configure(). Όλα τα άλλα πεδία πρέπει να περιλαμβάνονται μέσω του INITIATE CHECKOUT.
- Τα δεδομένα που διαβιβάζονται στο Checkout.configure() δεν αντικαθιστούν ποτέ τα δεδομένα που έχετε ήδη δώσει στην πράξη INITIATE CHECKOUT.
Βήμα 3: Έναρξη της διαδικασίας πληρωμής
Ξεκινήστε τη διαδικασία πληρωμής καλώντας μία από τις παρακάτω μεθόδους του αντικειμένου Checkout, ανάλογα με το είδος Hosted Payment Page που εφαρμόζετε.
- Για να εμφανίσετε την αλληλεπίδραση checkout σε μια ενσωματωμένη σελίδα:
Παράδειγμα
Checkout.showEmbeddedPage('#embed-target') - Για να εμφανίσετε την αλληλεπίδραση checkout σε μια σελίδα πληρωμής:
Παράδειγμα
Checkout.showPaymentPage()
Παράδειγμα κώδικα HTML για να ζητήσετε την ενσωματωμένη σελίδα ή τη σελίδα πληρωμής
<html>
<head>
<script src="https://gateway-japa.americanexpress.com/static/checkout/checkout.min.js" data-error="errorCallback" data-cancel="cancelCallback"></script>
<script type="text/javascript">
function errorCallback(error) {
console.log(JSON.stringify(error));
}
function cancelCallback() {
console.log('Payment cancelled');
}
Checkout.configure({
session: {
id: '<your_initiate_checkout_session_ID>'
}
});
</script>
</head>
<body>
...
<div id="embed-target"> </div>
<input type="button" value="Pay with Embedded Page" onclick="Checkout.showEmbeddedPage('#embed-target');" />
<input type="button" value="Pay with Payment Page" onclick="Checkout.showPaymentPage();" />
...
</body>
</html>
Παράδειγμα κώδικα HTML για χρήση της λειτουργίας modal
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<link rel="stylesheet" href="https://stackpath.bootstrapcdn.com/bootstrap/4.5.2/css/bootstrap.min.css" integrity="sha384-JcKb8q3iqJ61gNV9KGb8thSsNjpSL0n8PARn9HuZOnIxN0hoP+VmmDGMN5t9UJ0Z" crossorigin="anonymous">
<title>Hello, world!</title>
</head>
<body>
<h1>Hello, world!</h1>
<button type="button" class="btn btn-primary" data-toggle="modal" data-target="#exampleModal">
Launch demo modal
</button>
<div class="modal fade" id="exampleModal" tabindex="-1" role="dialog" aria-labelledby="exampleModalLabel" aria-hidden="true">
<div class="modal-dialog" role="document">
<div class="modal-content">
<div class="modal-header">
<h5 class="modal-title" id="exampleModalLabel">Modal title</h5>
<button type="button" class="close" data-dismiss="modal" aria-label="Close">
<span aria-hidden="true">—</span>
</button>
</div>
<div class="modal-body" id="hco-embedded">
</div>
<div class="modal-footer">
<button type="button" class="btn btn-secondary" data-dismiss="modal">Close</button>
<button type="button" class="btn btn-primary">Save changes</button>
</div>
</div>
</div>
</div>
<script src="https://code.jquery.com/jquery-3.6.0.slim.min.js" integrity="sha256-u7e5khyithlIdTpu22PHhENmPcRdFiHRjhAuHcs05RI=" crossorigin="anonymous"></script>
<script src="https://cdn.jsdelivr.net/npm/bootstrap@4.5.2/dist/js/bootstrap.min.js" crossorigin="anonymous"></script>
<script src="https://gateway-japa.americanexpress.com/static/checkout/checkout.min.js" ></script>
<script>
// Configure Checkout first
Checkout.configure({
session: {
id: "<your_initiate_checkout_ID>"
}
})
// after the modal is shown, then call Checkout.showEmbeddedPage('#hco-embedded')
$('#exampleModal').on('shown.bs.modal', function (e) {
Checkout.showEmbeddedPage('#hco-embedded',
() => { $('#exampleModal').modal() } // tell Checkout how to launch the modal
)
});
$('#exampleModal').on('hide.bs.modal', function (e) {
sessionStorage.clear(); // tell Checkout to clear sessionStorage when I close the modal
});
</script>
</body>
</html>
Βήμα 4: Εφαρμογή ανακλήσεων
Παρέχονται επανακλήσεις για τη διαχείριση συμβάντων που μπορεί να προκύψουν κατά την αλληλεπίδραση πληρωμής. Η χρήση ανακλήσεων είναι προαιρετική, αλλά αν τις χρειάζεστε, πρέπει να τις ορίσετε στο σώμα της ίδιας ετικέτας <script> που κάνει αναφορά στο checkout.min.js.
Όλες οι καθορισμένες ανακλήσεις πρέπει να έχουν μια υλοποίηση. Επικαλούνται όταν ενεργοποιείται το σχετικό συμβάν. Το ακόλουθο δείγμα κώδικα δείχνει ένα παράδειγμα ανάκλησης (που ενεργοποιείται αν ο πληρωτής ακυρώσει την πληρωμή) που ορίζεται και εφαρμόζεται σε μια σελίδα.
<script src="https://gateway-japa.americanexpress.com/static/checkout/checkout.min.js"
data-cancel="cancelCallback"
data-beforeRedirect="Checkout.saveFormFields"
data-afterRedirect="Checkout.restoreFormFields">
</script>
<script>
function cancelCallback() {
confirm('Are you sure you want to cancel?');
// code to manage payer interaction
}
// or if you want to provide a URL:
// cancelCallback = "someURL"
</script>
Υπάρχουν δύο τύποι μεθόδων ανάκλησης: βασικές ανακλήσεις και ανακατευθυντικές ανακλήσεις.
Βασικές ανακλήσεις
Παρέχονται βασικές ανακλήσεις για τον χειρισμό των ακόλουθων συμβάντων:
- cancel: Όταν ο πληρωτής ακυρώνει την αλληλεπίδραση πληρωμής.
Η ανάκληση cancel μπορεί να χρησιμοποιηθεί μόνο με μια σελίδα πληρωμής, δεν λειτουργεί με ενσωματωμένη σελίδα.
- error: Όταν παρουσιαστεί σφάλμα.
- complete: Όταν ο πληρωτής ολοκληρώνει την αλληλεπίδραση πληρωμής.
- timeout: Όταν η πληρωμή δεν έχει ολοκληρωθεί εντός της διάρκειας που είναι διαθέσιμη στον πληρωτή για να κάνει την πληρωμή.
Ανακλήσεις ανακατεύθυνσης
Καθώς το Hosted Checkout υποστηρίζει αλληλεπιδράσεις πληρωμής που απαιτούν την ανακατεύθυνση του πληρωτή σε άλλους ιστότοπους για τη συνέχιση της πληρωμής (π.χ. PayPal), παρέχονται ανακλήσεις προκειμένου να διαχειρίζεστε τι συμβαίνει πριν από την ανακατεύθυνση και μετά την επιστροφή στο Hosted Checkout προκειμένου να ολοκληρωθεί η διεκπεραίωση της συναλλαγής.
- beforeRedirect: Πριν στον πληρωτή εμφανιστεί το περιβάλλον εργασίας πληρωμής. Επιστρέφει δεδομένα που απαιτούνται για την επαναφορά της κατάστασης διεπαφής πληρωμής για χρήση από το afterRedirect.
- afterRedirect: Όταν ο πληρωτής επιστρέφει από την ολοκλήρωση της αλληλεπίδρασης πληρωμής. Χρησιμοποιεί τα δεδομένα που έχουν αποθηκευτεί από το beforeRedirect για να επιστρέψει την αποθηκευμένη κατάσταση διεπαφής πληρωμής.
Το αντικείμενο Checkout παρέχει επίσης δύο συναρτήσεις για να σας βοηθήσει να εφαρμόσετε τις ανακλήσεις beforeRedirect και afterRedirect:
- saveFormFields(): Αποθηκεύει όλα τα τρέχοντα πεδία φόρμας για χρήση από το restoreFormFields(). Χρησιμοποιήστε τη συνάρτηση στην υλοποίηση beforeRedirect ή υλοποιήστε το beforeRedirect ως Checkout.saveFormFields().
- restoreFormFields(): Επαναφέρει τα πεδία φόρμας με τη συνάρτηση saveFormFields(). Χρησιμοποιήστε τη συνάρτηση στην υλοποίηση afterRedirect ή υλοποιήστε το afterRedirect ως Checkout.restoreFormFields().
Συχνές ερωτήσεις
Τι πρέπει να κάνω αν το Hosted Checkout επιστρέψει σφάλμα;
Το Hosted Checkout μπορεί να επιστρέψει έναν αριθμό σφαλμάτων ενοποίησης. Βλ. Βήματα δοκιμής για περισσότερες πληροφορίες σχετικά με τις δοκιμές και τα σφάλματα.
Γιατί λαμβάνω μια σελίδα σφάλματος αντί για το Hosted Payment Page;
Εμφανίζεται μια σελίδα σφάλματος όταν επιχειρείται ένα λανθασμένο αίτημα Hosted Checkout. Οι συνηθισμένες αιτίες για σφάλματα είναι οι εξής:
- Λείπουν υποχρεωτικά πεδία.
- Οι διευθύνσεις URL που παρέχονται στο αίτημα δεν είναι απόλυτες.
Τι συμβαίνει αν ο πληρωτής κάνει διπλό κλικ στο κουμπί "Πληρωμή";
Αν ο πληρωτής κάνει διπλό κλικ στο κουμπί "Πληρωμή", δηλαδή υποβάλει την πληρωμή δύο φορές, τότε η συναλλαγή δεν επαναλαμβάνεται με τη δική σας τράπεζα ή την τράπεζα του πληρωτή.