Everypay.js


Στη σελίδα αυτή θα δούμε τι ακριβώς είναι και πώς λειτουργεί η βιβλιοθήκη everypay.js

Εισαγωγή του script στη σελίδα σας

Η φόρτωση της βιβλιοθήκης Javascript μπορεί να γίνει μέσα στο <head> της σελίδας αλλά προτείνεται να φορτώνεται ακριβώς πριν κλείσει η ετικέτα <body>, και αυτό γίνεται για βελτιστοποίηση της ταχύτητας φορτώματος της σελίδας σας. To javascript αρχείο πρέπει να φορτώνεται από τους servers του EveryPay για να εξασφαλίζεται οτι η έκδοση είναι η πλέον ενημερωμένη.

<script type="text/javascript" src="https://js.everypay.gr/everypay.js"></script>

setPublicKey

Η μέθοδος setPublicKey('PUBLIC_API_KEY') απαιτείται πριν από τη χρήση του Everypay.js για να ταυτοποιηθεί ο λογαριασμός που θα χρησιμοποιήσετε για τις συναλλαγές σας με το EveryPay. Όλα τα κλειδιά δημόσια και ιδιωτικά μπορείτε να τα δείτε στη διαχείριση του λογαριασμού σας.

Το όρισμα που πρέπει να δώσουμε στην μέθοδο αυτή είναι το δημόσιο κλειδί της εταιρείας για την οποία θα πραγματοποιήσουμε συναλλαγές. Η χρήση γίνεται ως εξής:

<script type="text/javascript">

    /* Δήλωση του δημόσιου κλειδιού */
    Everypay.setPublicKey('pk_vI1tWSHzaskrVBobzcqvwk0uYAWXR8BP');

    /* Ενεργοποίηση του δοκιμαστικού περιβάλλοντος */
    Everypay.setSandbox();

</script>

Η μέθοδος createToken

Η μέθοδος αυτή δημιουργεί ένα token που έχει ισχύ για 15 λεπτά και μόνο στον λογαριασμό που έχει ταυτοποιηθεί (βλ. setPublicKey). Τα ορίσματα που πρέπει να δώσουμε είναι δύο. Το πρώτο είναι ένα αντικείμενο με τα στοιχεία της κάρτας (όπως έχουν συμπληρωθεί στη φόρμα) και το δεύτερο το όνομα της μεθόδου callback που θα εκτελεστεί μετά το τέλος της createToken.


Χρήση της createToken

<script type="text/javascript">
    Everypay.createToken({
        holder_name: 'John Doe',
        card_number: '4242424242424242',
        cvv: '123',
        expiration_month: '03',
        expiration_year: '2015',
        amount: '1050'
    }, handleTokenResponse);
</script>


Tα πεδία της κάρτας που πρέπει να στείλουμε για να πραγματοποιήσουμε μια ασφαλή συναλλαγή φαίνονται στον παρακάτω πίνακα:

πεδίο περιγραφή
card_number Ο αριθμός της κάρτας
cvv Ο τριψήφιος αριθμός στο πίσω μέρος της κάρτας
expiration_month Μήνας λήξης της κάρτας
expiration_year Έτος λήξης της κάρτας
holder_name Το όνομα κατόχου της κάρτας
amount Το ποσό της πληρωμής σε cents

Εναλλακτική χρήση της createToken

Όπως φαίνεται και στο παράδειγμα στη σελίδα της φόρμας πληρωμής, μπορεί να "περαστεί" μία ολόκληρη φόρμα ως πρώτο όρισμα της createToken. Για το σκοπό αυτό μπορεί να χρησιμοποιήθεί απλή javascript ή μία βιβλιοθήκη όπως η jQuery. Για παράδειγμα:

<script type="text/javascript">
    //απλή javascript
    var form = document.forms['payment-form'];
    //ή επιλογή με jQuery
    var form = jQuery('#payment-form');

    Everypay.createToken(form, handleTokenResponse);
</script>

Η συγκεκριμένη χρήση της createToken προϋποθέτει πως όλα τα πεδία που βρίσκονται στη φόρμα πληρωμής έχουν το χαρακτηριστικό data-card και αυτό έχει την σωστή τιμή σύμφωνα με τον παραπάνω πίνακα. Για παράδειγμα το πεδίο με τον αριθμό της κάρτας θα πρέπει να είναι ορισμένο ως εξής:

<input type="text" autocomplete="off" data-card="card_number">


H μέθοδος handleTokenResponse

Το δεύτερο όρισμα όπως αναφέρθηκε είναι η μέθοδος που θα χειριστεί την απάντηση για τη δημιουργία του token από τους servers της EveryPay. Η λειτουργία που πρέπει να εκτελεί είναι να υποβάλει τη φόρμα στην επόμενη σελίδα για περαιτέρω επεξεργασία με χρήση του token, αφού πρώτα έχει προσθέσει ένα hidden πεδίο με το token που πήρε σαν απάντηση. Σε περίπτωση που η δημιουργία του token δεν ήταν επιτυχημένη απλώς δείχνει το μήνυμα του λάθους.

Το παρακάτω ενδεικτικό παράδειγμα είναι το ίδιο με αυτό στην φόρμα πληρωμής.

<script type="text/javascript">
function handleTokenResponse(status, response) {
    var $form = $("#payment-form");
    if (response.error) {
        ...
        /* προβολή του λάθους στο χρήστη */
        $form.find(".form-error").html(response.error.message).show();
        $form.find('button').prop('disabled', false);
    } else {
        var token = response['token'];
        /* προσθήκη του token στη φόρμα */
        $form.append($('<input type="hidden" name="everypayToken"/>').val(token));
        /* αποστολή */
        $form.unbind('submit').submit();
    }
}
</script>

Περίπτωση 1. Η επιτυχής λήψη του token

{
    "token": "crd_bed96ed62ad862659a9379b8a7decf7c", /* Το id του token*/
    "is_used": false, /* δείχνει εάν το token αυτό έχει ξαναχρησιμοποιηθεί*/
    "has_expired": false, /* δείχνει αν το token έχει λήξει */
    "date_requested": "06-12-2012 15:24:42", /* ημερομηνία δημιουργίας */
    "card": { /* στοιχεία της κάρτας */
        "expiration_month": "04",
        "expiration_year": "2014",
        "last_four": "4242",
        "type": "Visa",
        "holder_name": null,
        "supports_installments": false,
        "max_installments": 0
    }
}

Περίπτωση 2. Εσφαλμένη απάντηση

{
    "error": {
        "status": 400,
        "code": 20001,
        "message": "Provide a valid expiration year for the card."
    }
}

Όλοι οι κωδικοί σφαλμάτων βρίσκονται εδώ


Βοηθητικές μέθοδοι

Oι παρακάτω μέθοδοι μπορούν να χρησιμοποιηθούν για τον έλεγχο εγκυρότητας των αντίστοιχων πεδίων.

μέθοδος περιγραφή τύπος ορίσματος επιστρέφει
validateCardNumber Έλεγχος εγκυρότητας αριθμού κάρτας string boolean
validateCVV Έλεγχος εγκυρότητας του τριψήφιου πεδίου CVV string boolean
validateExpiry Έλεγχος εγκυρότητας ημερομηνίας λήξης string month, string year boolean
cardType Επιστρέφει τον τύπο της κάρτας string "Visa", "MasterCard", "American Express", "Discover", "Diners Club", "JCB", "Unknown"

Παραδείγματα κλήσης

<script type="text/javascript">
/* Αριθμός κάρτας */
Everypay.validateCardNumber('4012888888881881')     //true
Everypay.validateCardNumber('4012-88888888-1881')   //true
Everypay.validateCardNumber('4012-8888-8888-1881')  //true
Everypay.validateCardNumber('12345678')             //false
Everypay.validateCardNumber('a-card-number')        //false
Everypay.validateCardNumber('4242-1234-1232-1234')  //false


/* Αριθμός CVV */
Everypay.validateCVV('443') // true
Everypay.validateCVV('3')   // false


/* Ημερομηνία λήξης */
Everypay.validateExpiry('04', '17')      // false
Everypay.validateExpiry('04', '11')      // false
Everypay.validateExpiry('04', '2019')    // true
Everypay.validateExpiry(4, 2019)         // true


/* Τύπος κάρτας */
Everypay.cardType('4012-8888-8888-1881')  // "Visa"
Everypay.cardType('5555555555554444')     // "Mastercard"
Everypay.cardType('1234')                 // "Unknown"
</script>

getToken

H μέθοδος αυτή μπορεί να χρησιμοποιηθεί για τη λήψη πληροφοριών σχετικά με ένα ήδη δημιουργημένο token. Οι πληροφορίες που επιστρέφονται είναι ίδιες με το αντικείμενο στην createToken (βλ.παραπάνω περίπτωση 1).


Παράδειγμα χρήσης

<script type="text/javascript">
Everypay.getToken(token, function(status, response){
    if (response.error){
        alert(response.error.message);
    } elseif (!response.used) {
        alert('To token αυτό είναι ακόμα ενεργό');
    } elseif (response.used) {
        alert('To token αυτό έχει ήδη χρησιμοποιηθεί');
    }
});
</script>

Δημιουργία φόρμας πληρωμής


Στη σελίδα αυτή θα δούμε πώς μπορείτε να δημιουργήσετε μία λειτουργική φόρμα πληρωμών σε μια σελίδα στο site σας. Για λόγους συντομίας το όνομα του site σας θα αναφέρεται ως yourshop.com.

Απαραίτητη προϋπόθεση πριν ξεκινήσετε είναι να έχετε στο λογαριασμό σας τουλάχιστον μία ενεργοποιημένη και διαπιστευμένη εταιρεία, από την οποία χρειαζόμαστε το Δημόσιο και Ιδιωτικό κλειδί για χρήση με το API. Στο παράδειγμά μας το δημόσιο κλειδί θα αναφέρεται ως 'PUBLIC_KEY' και το ιδιωτικό ως 'SECRET_KEY'.

Σημαντικό: Προς αποφυγή σφαλμάτων, για τις δοκιμαστικές πληρωμές να χρησιμοποιείτε πάντα τα κλειδιά απο τον λογαριασμό σας στο sandbox https://sandbox-dashboard.everypay.gr και την διεύθυνση https://sandbox-api.everypay.gr για τις κλησεις του api.
Tip: Στον παρακάτω σύνδεσμο θα βρείτε πληροφορίες για τη λειτουργία του κουμπιού το οποίο σας παρέχει έτοιμο όλο τον παρακάτω κώδικα. Με το script αυτό έχετε έτοιμη την φόρμα πληρωμής στο site σας γράφοντας μόνο λίγες σειρές κώδικα!


Βήμα 1. Η φόρμα με HTML

Στο βήμα αυτό θα δούμε τον HTML κώδικα που απαιτείται για την δημιουργία της φόρμας. Αυτός ο κώδικας θα περιέχεται στη σελίδα πληρωμής της σελίδας σας π.χ. yourshop.com/pay-step1

<form action="/yourshop.com/payment-step-2" method="POST" id="payment-form">
    <div class="form-row">
        <label>Αριθμός κάρτας</label>
        <input type="text" maxlength="16" autocomplete="off" data-card="card_number"/>
    </div>
    <div class="form-row">
        <label>Όνομα κατόχου</label>
        <input type="text" maxlength="30" autocomplete="off" data-card="holder_name"/>
    </div>
    <div class="form-row">
        <label>CVV</label>
        <input type="text" maxlength="3" autocomplete="off" data-card="cvv"/>
    </div>
    <div class="form-row">
        <label>Ημερομηνία Λήξης</label>
        <select data-card="expiration_month"/>
            <option value="1">1</option>
            <option value="2">2</option>
            ...
            <option value="12">12</option>
        </select>
        <span> / </span>
        <select data-card="expiration_year"/>
            <option value="2015">2015</option>
            <option value="2016">2016</option>
            <option value="2017">2017</option>
            <option value="2018">2018</option>
            <option value="2019">2019</option>
        </select>
    </div>
    <input type="hidden" data-card="amount" value="10001"/>
    <div class="form-error" style="display:none"></div>
    <button>Πληρωμή</button>
</form>

Σημαντικές παρατηρήσεις:


  1. Στη φόρμα δεν υπάρχει κουμπί τύπου "submit" για να αποφύγουμε τυχόν άμεση αποστολή των στοιχείων της κάρτας.
  2. Το ποσό της πληρωμής, καθώς και τα στοιχεία της κάρτας (όνομα κατόχου, αριθμός κάρτας, ημερ/νία λήξης και κωδικός ασφαλείας CVV) είναι υποχρεωτικά πεδία. Η πλήρης λίστα με όλα τα πεδία που μπορούν να χρησιμοποιηθούν βρίσκεται στο ευρετήριο του everypay.js.
  3. Κανένα από τα πεδία δεν πρέπει να έχει όνομα (attribute name) για να αποφευχθεί το 'ποστάρισμά' του στον server σας. Αντ'αυτού χρησιμοποιείται η ετικέτα "data-card" που χαρακτηρίζει τα πεδία.

Τα στοιχεία της κάρτας που θα αποσταλούν στον server της EveryPay πρέπει να αποστέλλονται μέσα από το πρωτόκολλο SSL, ωστόσο επειδή δεν αποθηκεύονται στην εφαρμογή σας δεν χρειάζεται να πάρετε πιστοποίηση PCI-DSS. Εάν χρησιμοποιείτε και τους προτεινόμενους τρόπους από το ΕveryPay, τότε δεν χρειάζεται να έχετε κάποια πιστοποίηση SSL στον δικό σας server.

Το επιθυμητό αποτέλεσμα είναι μία φόρμα όπως την παρακάτω εικόνα.

payment-form-everypay



Η μορφοποίηση με css μπορεί να γίνει κατά βούληση χωρίς να επηρεάσει το αποτέλεσμα και τη λειτουργικότητα της φόρμας. Μπορείτε να την εμφανίσετε ακόμη και σε popup modal.



Βήμα 2. Οι λειτουργίες Javascript

Πρώτα θα πρέπει να φορτωθεί η βιβλιοθήκη Javascript του EveryPay. Η φόρτωση μπορεί να γίνει μέσα στην ετικέττα <head> της σελίδας αλλά προτείνεται να φορτώνεται στο τέλος, ακριβώς πριν το τέλος της ετικέττας <body> για βελτιστοποίηση της ταχύτητας φορτώματος. To javascript αρχείο θα πρέπει να φορτώνεται από τους servers του EveryPay για να εξασφαλίζεται οτι η έκδοση είναι η τελευταία καθώς και η αυθεντικότητά του.

Σημείωση: Στο παράδειγμά μας χρησιμοποιούμε την βιβλιοθήκη jQuery για ευκολία. Εσείς δεν είναι απαραίτητο να συμπεριλάβετε κάποια βιβλιοθήκη στη σελίδα σας (π.χ. jQuery, MooTools κλπ.), καθώς η βιβλιοθήκη everypay.js λειτουργεί με Plain Javascript.
<script type="text/javascript" src="https://js.everypay.gr/everypay.js"></script>

Τώρα πρέπει να ταυτοποιήσουμε το λογαριασμό μας "σεττάροντας" το δημόσιο κλειδί μας. Το κλειδί αυτό είναι ασφαλές παρ'ότι βρίσκεται σε κοινή "θέα", κι'αυτό γιατί όλες οι συναλλαγές ολοκληρώνονται σε δεύτερο στάδιο με χρήση του "Ιδιωτικού κλειδιού". Το ιδιωτικό κλειδί δεν πρέπει να γνωστοποιείται πουθενά παρά μόνο στα scripts των εφαρμογών σας που εκτελούνται εντός του server σας.

<script type="text/javascript">

    /* Δήλωση του δημόσιου κλειδιού */
    Everypay.setPublicKey('pk_vI1tWSHzaskrVBobzcqvwk0uYAWXR8BP');

    /* Ενεργοποίηση του δοκιμαστικού περιβάλλοντος */
    Everypay.setSandbox();

</script>

Η μέθοδος Εverypay.setPublicKey(..) χρησιμοποιείται για να γνωστοποιήσουμε στο EveryPay ποιός λογαριασμός/εταιρεία θα χρησιμοποιηθεί στις επόμενες κινήσεις. Αντικαταστείστε την τιμή pk_vI1tWSHzaskrVBobzcqvwk0uYAWXR8BP με το δικό σας Δημόσιο Κλειδί.


Βήμα 3. Δημιουργία token

Σε αυτό το βήμα θα δημιουργηθεί ένα token το οποίο αντιπροσωπεύει μία μοναδική κίνηση. Τα token είναι μοναδικά και δεν πρέπει να αποθηκεύονται ή να επαναχρησιμοποιούνται. Η διάρκεια ζωής τους είναι 15 λεπτά. Εάν θέλετε να χρεώσετε μία κάρτα πάνω από μία φορές, χρησιμοποιήστε το token για να δημιουργήσετε ένα αντικείμενο πελάτη

H δημιουργία του token γίνεται όταν ο χρήστης πατήσει το κουμπί της πληρωμής που βρίσκεται στη φόρμα. Γι'αυτό το σκοπό γίνεται χρήση των event handlers της Javascript. Στο παρακάτω παράδειγμα χρησιμοποιούμε τη βιβλιοθήκη jQuery και "πιάνουμε" το event click του κουμπιού Πληρωμή που υπάρχει στη φόρμα.


Αποστολή των στοιχείων της κάρτας και λήψη του token

<script type="text/javascript">
$(document).ready(function() {
    $('#payment-form').submit(function(event){
        event.preventDefault();
        var $form = $(this);

        /*  απενεργοποίηση όλων των κουμπιών της φόρμας */
        $form.find('button').prop('disabled', true);
        /*  σβήσιμο των λαθών που υπάρχουν από τυχόν προήγουμενες αποτυχημένες προσπάθειες  */
        $form.find(".form-error").html('').hide();
        /*  δημιουργία του token */
        Everypay.createToken($form, handleTokenResponse);
        /*  Ακύρωση ποσταρίσματος της φόρμας */
        return false;
    });
});
</script>

Όπως φαίνεται χρησιμοποιούμε την μέθοδο everypay.createToken(arg1, arg2).

arg1: Ως πρώτο όρισμα δίνουμε την φόρμα η οποία περιέχει τα πεδία με τα στοιχεία της κάρτας. Εναλλακτικά μπορούμε να δώσουμε ένα αντικείμενο με τα στοιχεία της κάρτας ως εξής:

var card_details = {
    holder_name: $('[data-card="holder_name"]').val(),
    card_number: $('[data-card="card_number"]').val(),
    cvv: $('[data-card="cvv"]').val(),
    expiration_month: $('[data-card="expiration_month"]').val(),
    expiration_year: $('[data-card="expiration_year"]').val(),
    amount: $('[data-card="amount"]').val()
}
Everypay.createToken(card_details, handleTokenResponse);

arg2: To δεύτερο όρισμα (handleTokenResponse) είναι η μέθοδος callback που θα χειριστεί την απάντηση που θα λάβετε από το EveryPay. Όταν η μέθοδος createToken ολοκληρωθεί θα εκτελεστεί η μέθοδος handleTokenResponse. Η απάντηση που θα λάβετε από την δικιά μας υπηρεσία είναι ένα αντικείμενο με διάφορα πεδία. Εάν προκύψει κάποιο σφάλμα (π.χ. η κάρτα έχει λήξει) τότε το αντικείμενο αυτό περιέχει ένα πεδίο error με περισσότερες λεπτομέρειες αλλιώς ένα αντικείμενο με τις λεπτομέρειες του token.


Περίπτωση 1. Η επιτυχής λήψη του token

{
    "token": "crd_bed96ed62ad862659a9379b8a7decf7c", /* Το id του token*/
    "used": false, /* δείχνει εάν το token αυτό έχει ξαναχρησιμοποιηθεί*/
    "has_expired": false, /* δείχνει αν το token έχει λήξει */
    "date_requested": "06-12-2012 15:24:42", /* ημερομηνία δημιουργίας */
    "card": { /* στοιχεία της κάρτας */
        "expiration_month": "04",
        "expiration_year": "2014",
        "last_four": "4242",
        "type": "Visa",
        "holder_name": null
    }
}

Περίπτωση 2. Εσφαλμένη απάντηση

{
    "error": {
        "status": 400,
        "code": 20001,
        "message": "Provide a valid expiration year for the card."
    }
}

Όλοι οι κωδικοί των σφαλμάτων βρίσκονται εδώ


Βήμα 4. Υποβολή της φόρμας στην επόμενη σελίδα σας

  • Εάν η απάντηση που λάβατε στο προηγούμενο βήμα είναι αρνητική, τότε μπορείτε να κάνετε alert στον χρήστη την αιτία του λάθους.
  • Εάν η απάντηση είναι επιτυχής (το token δημιουργήθηκε), τότε θα προστεθεί ένα πεδίο με το token στη φόρμα και θα γίνει υποβολή της φόρμας στην επόμενη σελίδα του server σας για περαιτέρω επεξεργασία. Εδώ την σελίδα επεξεργασίας θα την ονομάζουμε yourshop.com/pay-step2.

Διαχείριση της απάντησης από το EveryPay

<script type="text/javascript">
function handleTokenResponse(status, response) {
    var $form = $('#payment-form');

    if (response.error) {
        /* προβολή του λάθους στο χρήστη */
        $form.find(".form-error").html(response.error.message).show();
        /* επανενεργοποίηση των κουμπιών της φόρμας */
        $form.find('button').prop('disabled', false);
    } else {
        var token = response.token;
        //* προσθήκη του token στη φόρμα */
        $form.append($('<input type="hidden" name="everypayToken"/>').val(token));
        /* αποστολή της φόρμας*/
        $form.unbind('submit').submit();
    }
}
</script>

Σημείωση: To μόνο στοιχείο που ουσιαστικά χρειάζεται να 'περάσει' στην επόμενη σελίδα είναι το token. Τα υπόλοιπα όπως προαναφέραμε δεν έχουν όνομα οπότε και δεν θα 'ποσταριστούν'.

Τι μπορούμε να κάνουμε με αυτό το Token?

Με το token που εκδόσαμε μπορούμε να προχωρήσουμε σε:

χρέωση ποσού σε αυτή την κάρτα. Δείτε
δημιουργία ενός πελάτη έτσι ώστε να μπορούμε να εκτελούμε χρεώσεις περιοδικά χωρίς τα στοιχεία της κάρτας (χρήσιμο σε συνδρομητικές υπηρεσίες). Δείτε