- Κατευθυντήριες οδηγίες ενοποίησης
- Υλοποίηση μιας ενοποίησης Batch
Υλοποίηση μιας ενοποίησης Batch
Προαπαιτούμενα
- Βεβαιωθείτε ότι έχετε ενεργοποιήσει το προφίλ εμπόρου σας για την υπηρεσία Batch.
- Πριν ξεκινήσετε την ενοποίηση, βλ. την ενότητα Βέλτιστες πρακτικές και συμβουλές.
Βήματα ενοποίησης
Βήμα 1: Πρόσβαση στην πύλη
Ως πρώτο βήμα, ελέγξτε τη συνδεσιμότητά σας στο Mastercard Gateway.
Βήμα 2: Μάθετε τα πεδία εισαγωγής
Πριν ξεκινήσετε τη δόμηση της ενοποίησης, πρέπει να είστε προετοιμασμένοι με τις τιμές για τα πεδία που απαιτούν εισαγωγή από εσάς.
Βήμα 3: Δημιουργία αιτήματος πακέτου
Η δημιουργία του σώματος του αιτήματος είναι κρίσιμο βήμα για την ενοποίηση.
Βήμα 4: Αποστολή αιτήματος πακέτου
Υπάρχουν πολλά στοιχεία προκειμένου να διασφαλιστεί η ασφαλής αποστολή του σώματος του αιτήματος συναλλαγής στο Mastercard Gateway.
Βήμα 5: Ανάκτηση κατάστασης πακέτου
Μόλις υποβληθεί το πακέτο, μπορείτε να ζητάτε περιοδικά μια κατάσταση πακέτου για να καθορίσετε την τρέχουσα κατάσταση της διεκπεραίωσης του πακέτου.
Βήμα 6: Διεκπεραίωση απόκρισης πακέτου
Αφού ολοκληρωθεί η διεκπεραίωση ενός πακέτου, μπορείτε να ζητήσετε ένα αρχείο απόκρισης που να περιέχει το αποτέλεσμα κάθε μίας από τις πράξεις που έχουν ανέβει.
Βήμα 7: Δοκιμή και έναρξη λειτουργίας
Η δοκιμή σάς επιτρέπει να ελέγξετε αν η ενοποίησή σας λειτουργεί όπως επιθυμείτε.
Αντιμετώπιση προβλημάτων και συχνές ερωτήσεις
Μπορώ να χρησιμοποιήσω πολλαπλά προφίλ εμπόρου σε μια απόκριση πακέτου;
Ναι, μπορείτε να χρησιμοποιήσετε πολλαπλά προφίλ εμπόρου σε ένα αίτημα πακέτου αν μπορείτε να διασφαλίσετε ότι τα διαπιστευτήρια πράξης (αναγνωριστικό εμπόρου και κωδικός πρόσβασης ταυτοποίησης) για κάθε γραμμή εγγραφής πράξης είναι έγκυρα προκειμένου να είναι εφικτή η ταυτοποίηση και η έγκριση.
Από προεπιλογή, τα διαπιστευτήρια πράξης για κάθε πράξη σε ένα πακέτο θα χρησιμοποιήσουν τα διαπιστευτήρια ταυτοποίησης που παρέχονται στην κεφαλίδα του αιτήματος πακέτου (αναγνωριστικό εμπόρου και κωδικός πρόσβασης). Μπορείτε να επιλέξετε να χρησιμοποιήσετε τον μηχανισμό προεπιλογής ή να δώσετε διαπιστευτήρια πράξης για κάθε γραμμή εγγραφών πράξης. Με τη δεύτερη επιλογή, η ταυτοποίηση της πράξης θα χρησιμοποιήσει τα διαπιστευτήρια επιπέδου πράξης και δεν θα χρησιμοποιήσει από προεπιλογή στο διαπιστευτήρια που αιτήματος που ανεβαίνει. Αν τα διαπιστευτήρια επιπέδου πράξης είναι λανθασμένα, τότε το ανέβασμα πακέτου θα απορριφθεί.
Στο αρχείο δείγματος πακέτου, οι πράξεις VOID θα χρησιμοποιήσουν τα διαπιστευτήρια κεφαλίδας αιτήματος πακέτου, καθώς το αναγνωριστικό εμπόρου και ο κωδικός πρόσβασης δεν έχουν δοθεί.
merchant,apiPassword,apiOperation,order.id,transaction.id,transaction.amount,transaction.currency, cardDetails.card.number, cardDetails.card.expiry.month,cardDetails.card.expiry.year,card.number,result,error.cause, error.explanation,response.gatewayCode TESTMERCHANT,<TESTMERCHANT_API_PASSWORD>,PAY,921830104167,TXID1,30,AUD,5123456789012346,05,13,,,,, TESTMERCHANT,<TESTMERCHANT_API_PASSWORD>,PAY,921830104168,TXID1,30,AUD,5123456789012346,05,13,,,,, ,,VOID,1256378915689,TXID1,100,AUD,4987654321098769,05,13,,,,, ,,VOID,1256378915690,TXID1,100,AUD,4987654321098769,05,13,,,,, ,,VOID,1256378915691,TXID1,100,AUD,4987654321098769,05,13,,,,,
Ποιες είναι οι πιθανές αιτίες για την αποτυχία μιας υποβολής πακέτου;
Μια υποβολή πακέτου ενδέχεται να αποτύχει λόγω των ακόλουθων συνθηκών σφάλματος.
| Σενάριο | Μήνυμα σφάλματος |
|---|---|
| Το πακέτο είναι ατελές επειδή η σύνοψη μηνύματος SHA-1 δεν ταιριάζει | Η υποβολή πακέτου απέτυχε για έναν από τους παρακάτω λόγους:
|
Διπλότυπο όνομα πακέτου
|
Η υποβολή πακέτου απέτυχε: Ένα πακέτο με αυτό το όνομα ανεβαίνει αυτήν τη στιγμή ή ένα πακέτο με αυτό το όνομα αλλά διαφορετικό περιεχόμενο έχει ήδη ανέβει και επικυρωθεί. Αν το αρχείο ανεβαίνει ήδη, περιμένετε να τελειώσει το ανέβασμα. Αν χρησιμοποιείτε ένα όνομα αρχείου που είναι ήδη κατειλημμένο, μετονομάστε το αρχείο και επαναλάβετε την υποβολή. |
Επιστρέφεται σφάλμα ταυτοποίησης αν δεν έχετε επαρκή δικαιώματα για την υποβολή πακέτων:
|
Αποτυχία ταυτοποίησης: Τα διαπιστευτήρια που παρέχονται στην εγγραφή <record number> δεν είναι σωστά. Αυτό μπορεί να προκληθεί από:
|
| Επιστρέφεται σφάλμα ταυτοποίησης αν δώσετε μόνο τον κωδικό πρόσβασης αλλά όχι το ID εμπόρου σε επίπεδο πράξης. | Αποτυχία ταυτοποίησης. Στην εγγραφή <record number> του αρχείου πακέτου, δίνεται κωδικός πρόσβασης αλλά όχι ID εμπόρου. Προσθέστε ένα ID εμπόρου ή καταργήστε τον κωδικό πρόσβασης για να χρησιμοποιήσετε τα διαπιστευτήρια εμπόρου σε επίπεδο πακέτου για αυτήν την εγγραφή, στη συνέχεια, προσπαθήστε να υποβάλετε ξανά το αίτημα. |
| Επιστρέφεται σφάλμα ταυτοποίησης αν τα διαπιστευτήρια πακέτου δεν έχουν διαμορφωθεί σωστά. | Αποτυχία ταυτοποίησης: Τα διαπιστευτήρια που παρέχονται στην κεφαλίδα:
|
Επιστρέφεται σφάλμα ταυτοποίησης αν:
|
Αποτυχία ταυτοποίησης: Τα διαπιστευτήρια που παρέχονται για το πακέτο δεν είναι έγκυρα. Διορθώστε τα διαπιστευτήρια και προσπαθήστε να υποβάλλετε το αίτημα ξανά. |
| Επιστρέφεται σφάλμα ανάλυσης αν η κεφαλίδα περιέχει μη έγκυρους χαρακτήρες. | Η υποβολή πακέτου απέτυχε: Δεν ήταν δυνατή η ανάλυση του πακέτου, επειδή η κεφαλίδα περιείχε μη έγκυρο χαρακτήρα. Οι επιτρεπόμενοι χαρακτήρες είναι:
|
| Επιστρέφεται σφάλμα ανάλυσης αν μια γραμμή εγγραφής πράξης περιέχει περισσότερες τιμές από αυτές που ορίζονται στην κεφαλίδα. | Η υποβολή πακέτου απέτυχε: Δεν ήταν δυνατή η ανάλυση του πακέτου, επειδή η εγγραφή <record number> περιείχε περισσότερες τιμές από αυτές που ορίζονται στην κεφαλίδα. Διορθώστε το πακέτο, στη συνέχεια προσπαθήστε να το υποβάλλετε ξανά. |
| Επιστρέφεται σφάλμα ανάλυσης σε περίπτωση υπέρβασης του μέγιστου μεγέθους μεμονωμένου πεδίου ή έχει συμβεί άγνωστο σφάλμα ανάλυσης σε μια εγγραφή πράξης. | Η υποβολή πακέτου απέτυχε: Η ανάλυση του πακέτου δεν ήταν δυνατή λόγω σφάλματος στην εγγραφή <record number>. Βεβαιωθείτε ότι το πακέτο συμμορφώνεται με τη μορφή αρχείο και ότι χρησιμοποιείτε τη σωστή κωδικοποίηση, στη συνέχεια προσπαθήστε να υποβάλετε ξανά το πακέτο. |
| Επιστρέφεται σφάλμα κωδικοποίησης αν δεν έχει δοθεί κωδικοποίηση ή αν έχει δοθεί κωδικοποίηση που δεν υποστηρίζεται. | Αποτυχία αιτήματος: Η παρεχόμενη κωδικοποίηση δεν υποστηρίζεται. Οι υποστηριζόμενες κωδικοποιήσεις είναι η UTF-8 και η LATIN1. Υποβάλετε το αίτημα ξανά και προσπαθήστε να χρησιμοποιήσετε υποστηριζόμενη κωδικοποίηση. |
| Δεν ήταν δυνατή η εύρεση του πακέτου | Αποτυχία αιτήματος: Δεν ήταν δυνατή η εύρεση ενός πακέτου με αυτό το όνομα πακέτου. Διορθώστε το όνομα πακέτου και υποβάλετε το αίτημα ξανά. |
| Ο έλεγχος μήκους για την παρεχόμενη έκδοση απέτυχε. | Αποτυχία αιτήματος: Η παρεχόμενη έκδοση δεν είναι έγκυρη. Διορθώστε την έκδοση και υποβάλετε το αίτημα ξανά. |
| Ο έλεγχος μήκους για το παρεχόμενο όνομα πακέτου απέτυχε. | Αποτυχία αιτήματος: Το παρεχόμενο όνομα πακέτου δεν είναι έγκυρο. Διορθώστε το όνομα πακέτου και υποβάλετε το αίτημα ξανά. |
| Ο έλεγχος μήκους για το παρεχόμενο ID εμπόρου απέτυχε. | Αποτυχία αιτήματος: Το παρεχόμενο ID εμπόρου δεν είναι έγκυρο. Διορθώστε το ID εμπόρου και υποβάλετε το αίτημα ξανά. |
| Παρουσιάστηκε σφάλμα πύλης | Δεν ήταν δυνατή η υποβολή του αιτήματος στην πύλη λόγω εσωτερικού σφάλματος στην πύλη. Προσπαθήστε ξανά αργότερα. |
Η διεκπεραίωση πράξεων από το Batch μπορεί να αποτύχει λόγω προβλημάτων επικοινωνίας ή συστημάτων με αποτέλεσμα ένα από τα παρακάτω σφάλματα:
- Παρουσιάστηκε σφάλμα λόγω εσωτερικής βλάβης συστήματος.
- Παρουσιάστηκε σφάλμα επειδή ο διακομιστής δεν διέθετε επαρκείς πόρους για τη διεκπεραίωση του αιτήματος αυτήν τη στιγμή.
- Παρουσιάστηκε σφάλμα κατά τη διεκπεραίωση μιας συναλλαγής επαλήθευσης Tokenization
Όταν συμβαίνει αυτό και μπορεί να επαναληφθεί η πράξη, το Batch θα προσπαθήσει ξανά να αποστέλλει την πράξη για διεκπεραίωση είτε μέχρις ότου ληφθεί μια απόκριση χωρίς δυνατότητα επανάληψης για την πράξη είτε μέχρις όρου εξαντληθεί το όριο επαναλήψεων.
Το Batch αποθηκεύει τα ονόματα πακέτων και τον αντίστοιχο κώδικα ακεραιότητας μηνυμάτων (MIC) που έχετε ανεβάσει εσείς. Μπορούν να ταυτοποιηθούν πακέτα με όνομα πακέτου που είχε υποβληθεί στο παρελθόν αλλά με διαφορετικό περιεχόμενο και θα απορριφθούν από το Batch.
Μπορούν επίσης να ταυτοποιηθούν πακέτα με ίδιο όνομα και περιεχόμενο όπως για πακέτο που είχε υποβληθεί προηγουμένως. Το Batch επιστρέφει την ίδια κατάσταση όπως για το πακέτο που είχε ανεβεί προηγουμένως. Επομένως, αν ο έμπορος υποπτευθεί ότι υπάρχει πρόβλημα μετάδοσης, είναι σε θέση να επαληθεύσει ότι το πακέτο ανέβηκε με επιτυχία στο Batch.
Οι τιμές στη γραμμή κεφαλίδας ενός αιτήματος πακέτου που υποβλήθηκε για διεκπεραίωση μπορούν να περιέχουν μόνο χαρακτήρες που βρίσκονται στα ονόματα πεδίων του πρωτοκόλλου NVP για το API. Επιτρέπονται οι ακόλουθοι χαρακτήρες:
- Αλφαριθμητικοί (a-z, A-Z, 0-9)
- Τελεία (.)
- Αγκύλες ([ ])
Το Batch απορρίπτει ένα πακέτο αν προκύψουν σφάλματα ανάλυσης. Η ανάλυση περιλαμβάνει το διαχωρισμό του πακέτου σε γραμμές και των γραμμών σε πεδία.
Σφάλμα ανάλυσης μπορεί να παρουσιαστεί όταν:
- υπάρχει εγγραφή πράξης με περισσότερα κόμματα από αυτά που περιλαμβάνονται στην εγγραφή κεφαλίδας
- έχει γίνει υπέρβαση του μέγιστου μεγέθους ενός μεμονωμένου πεδίου
Πρέπει πρώτα να διορθώσετε αυτά τα σφάλματα πριν υποβάλετε ξανά το πακέτο για διεκπεραίωση.
Βέλτιστες πρακτικές και συμβουλές
Η υπηρεσία Batch δεν εγγυάται ότι θα διεκπεραιώσει πράξεις με την ίδια σειρά που καθορίζεται στο αρχείο πακέτου επειδή ο αποστολέας Batch μπορεί να διεκπεραιώσει πράξεις παράλληλα. Αυτή η συμπεριφορά μπορεί επίσης να αποδοθεί στη λειτουργία επανάληψης, δηλαδή αν ορισμένες πράξεις σε ένα αρχείο πακέτου απαιτούν επανάληψη, τότε οι πράξεις που είναι έτοιμες θα διεκπεραιωθούν πρώτες, ανεξάρτητα από τη σειρά με την οποία καθορίζονται. Για παράδειγμα, ακόμα και αν καθοριστούν επακόλουθες πράξεις μετά τις αρχικές (Capture ακολουθούμενη από Authorization, Void ακολουθούμενη από Pay), τότε η πράξη Capture μπορεί να εκτελεσθεί πριν από την πράξη Authorization, ή η πράξη Void πριν από την πράξη Pay.
Ως εκ τούτου, για πράξεις που πρέπει να ακολουθούν αυστηρά μια σειρά, συνιστάται να εκτελέσετε πρώτα το αρχικό πακέτο πράξεων, να περιμένετε το αρχείο απόκρισης πακέτου και αν είναι επιτυχές, να εκτελέσετε το επόμενο πακέτο πράξεων.
Το Tokenization αποθηκεύει λεπτομέρειες καρτών σε ένα token. Για χρήση του Tokenization με το Batch, πρέπει να χρησιμοποιήσετε ένα αναγνωριστικό token στο αρχείο πακέτου, όπως παρουσιάζεται παρακάτω.
apiOperation,cardDetails.card.number,cardDetails.card.expiry.month,cardDetails.card.expiry.year,cardDetails.card.securityCode,cardDetails.cardToken,transaction.amount,transaction.currency,transaction.id,transaction.authorizationCode,order.id,card.start.month,card.start.year,card.issueNumber,card.bankAccountType
AUTHORIZE,,,,,200,10,AUD,TXID1,,10323711802,,,,
AUTHORIZE,,,,,300,20,AUD,TXID1,,10323711803,,,,
AUTHORIZE,,,,,400,10,AUD,TXID1,,10323711804,,,,
AUTHORIZE,,,,,500,5.99,AUD,TXID1,,10323711805,,,,
Τα διαπιστευτήρια πράξης περιλαμβάνουν το αναγνωριστικό εμπόρου και τον κωδικό πρόσβασης. Τα διαπιστευτήρια πράξης για κάθε πράξη σε ένα πακέτο θα χρησιμοποιήσουν από προεπιλογή τα διαπιστευτήρια ταυτοποίησης που παρέχονται στην κεφαλίδα του αιτήματος πακέτου (αναγνωριστικό εμπόρου και κωδικός πρόσβασης). Ωστόσο, αν καθορίζετε τιμές και για τα δύο αυτά πεδία σε σχέση με γραμμές εγγραφών πράξεων, η ταυτοποίηση της πράξης θα χρησιμοποιήσει τα διαπιστευτήρια επιπέδου πράξης και δεν θα χρησιμοποιήσει από προεπιλογή στο διαπιστευτήρια που αιτήματος που ανεβαίνει.
Ναι, μπορείτε να διεκπεραιώσετε πολλαπλούς τύπους πράξεων σε ένα αρχείο πακέτου υπό την προϋπόθεση ότι ΔΕΝ σχετίζονται με την ίδια παραγγελία, δηλ. δεν περιέχουν το ίδιο αναγνωριστικό παραγγελίας. Η υπηρεσία Batch δεν εγγυάται ότι θα διεκπεραιώσει πράξεις με την ίδια σειρά που καθορίζεται στο αρχείο πακέτου επειδή ο αποστολέας Batch μπορεί να διεκπεραιώσει πράξεις παράλληλα. Αυτή η συμπεριφορά μπορεί επίσης να αποδοθεί στη λειτουργία επανάληψης, δηλαδή αν ορισμένες πράξεις σε ένα αρχείο πακέτου απαιτούν επανάληψη, τότε οι πράξεις που είναι έτοιμες θα διεκπεραιωθούν πρώτες, ανεξάρτητα από τη σειρά με την οποία καθορίζονται. Για παράδειγμα, αν πράξεις Pay και Void βρίσκονται στο ίδιο αρχείο πακέτου, οι πράξεις Void μπορεί να εκτελεστούν πριν από τις πράξεις Pay. Ωστόσο, αν οι πράξεις ΔΕΝ σχετίζονται με την ίδια παραγγελία, δηλ. αν περιέχουν διαφορετικά αναγνωριστικά παραγγελίας, τότε μπορείτε να έχετε πολλαπλούς τύπους πράξεων σε ένα αρχείο πακέτου.
Ναι, μπορείτε να χρησιμοποιήσετε πολλαπλές προελεύσεις λεπτομερειών κάρτας σε ένα αρχείο πακέτου, εκτός από το ID περιόδου λειτουργίας (session) πληρωμής. Για πληροφορίες σχετικά με τις πολλαπλές προελεύσεις, βλ. την ενότητα Πολλαπλές προελεύσεις λεπτομερειών κάρτας.
Οι πράξεις Authorize στο παρακάτω δείγμα χρησιμοποιούν token αντί για λεπτομέρειες κάρτας.
apiOperation,order.id,transaction.id,transaction.amount,transaction.currency,cardDetails.card.number,cardDetails.card.expiry.month,cardDetails.card.expiry.year,card.number,cardDetails.cardToken,result,error.cause,error.explanation,response.gatewayCode
PAY,921830104167,TXID1,30,AUD,5123456789012346,05,13,,,,,,
PAY,921830104168,TXID1,50,AUD,5123456789012346,05,13,,,,,,
PAY,921830104169,TXID1,100,AUD,4987654321098769,05,13,,,,,,
AUTHORIZE,10072028281,TXID1,,,,,,,200,,,,,
AUTHORIZE,10072028282,TXID1,,,,,,,300,,,,,
AUTHORIZE,10072028283,TXID1,,,,,,,400,,,,,