Προγραμματιστές

Είμαστε διαθέσιμοι με πολλούς τρόπους, κάθε φορά που θα μας χρειαστείτε.

Προσομοίωση κλήσης ειδοποίησης

Για να μπορέσετε να προσομοιώσετε το HTTP POST στο paymentURL, μπορείτε να κάνετε τα παρακάτω:

Ανοίγετε έναν οποιονδήποτε Rest Client (Postman, Chrome plugin, Mozilla plugin etc)
HTTP Method: POST
Headers: Content-type: application/json; charset=utf-8
Βάζετε στο Request Body την απάντηση του PayByBank API κατά την καταχώρηση της παραγγελίας, δηλαδή ένα ORDER object σε JSON (δείτε παράδειγμα παρακάτω), και αλλάζετε το status από PENDING σε PAID.

Request Body:

{
“id”: 14559842, “merchantOrderId”: “thisismytest2”,
“merchantCustomerAssociateId”: “”,
“merchant”: {
“id”: 61,
“name”: “Test Test”,
“apiKey”: “XXXXXXXXXXXXXXXXXXXXX”,
“confirmationURL”: null,
“paymentURL”: “http://test/paymentUrl.jsp“,
“is_active”: 1,
“ins_usr_id”: 0,
“insertDatetime”: 1466061915787,
“updt_usr_id”: 101287,
“updateDatetime”: 1509023570810
},
“amount”: 100,
“omtTransactionBank”: {
“txn_id”: 14559842,
“referReason”: null,
“bankPaymentCode”: “0012101793321”,
“bankName”: null,
“bankAccount”: null,
“bankAccountHolder”: null,
“merchantOrderStatus”: “PAID“,
“merchantPaymentLog”: null
},
“insertDatetime”: 1512719700160,
“updateDatetime”: 1512719700160
}

Διαδικασία Ροής PayByBank

Επεξήγηση Διαδικασίας Ροής για αιτήματα κωδικού πληρωμής

Κάθε φορά που θέλετε να καταχωρήσετε μια παραγγελία η οποία θα έχει αρχικό status PENDING, πραγματοποιείται η κλήση :
/rest/api/v1/order/merchant/{api_key}?merchant_order_id={merchant_order_id}&merchant_customer_id={merchant_customer_id}&amount={amount}
Οι λεπτομέρειες του request/response βρίσκονται αναλυτικά στο PayByBank API (link to APIS/Order Services For merchants).
Xωρίς έλεγχο ποσού
Αν στην παραπάνω κλήση δεν αποσταλεί η παράμετρος amount, τότε καταχωρείται ένα αίτημα κωδικού πληρωμής χωρίς έλεγχο ποσού και σε κατάσταση active. Για αυτόν τον κωδικό πληρωμής, o τρόπος πληρωμής PayByBank μπορεί να δεχθεί απεριόριστο αριθμό πληρωμών χωρίς έλεγχο ποσού. Σε αυτή την περίπτωση για κάθε πληρωμή που έρχεται, ο PayByBank καταχωρεί μια εικονική παραγγελία
(Order) σε status PAID. Σε περίπτωση που ο Merchant δεν επιθυμεί να δέχεται άλλες πληρωμές γι’ αυτόν τον κωδικό πληρωμής, τότε μπορεί να τον απενεργοποιήσει με την κλήση cancel
Όταν ο PayByBank ενημερωθεί από την τράπεζα ότι έγινε η πληρωμή από τον πελάτη επιχειρεί να στείλει ένα HTTP POST request (Content–Type: application/json) στο paymentURL που έχει δηλώσει ο Merchant και στο body του οποίου θα περιέχεται ένα Order object με τις λεπτομέρειες της παραγγελίας. Τα πεδία του Order object βρίσκονται και αυτά στο PayByBank API (ενότητα OBJECTS/Order).
Τα status για να θεωρείται ένα ORDER ως πληρωμένο είναι: PAID ή COMPLETED.
α) Σε περίπτωση κωδικού πληρωμής με έλεγχο ποσού: Εφόσον ο merchant ενημερωθεί (*) το status της παραγγελίας αλλάζει από PAID σε COMPLETED.
β) Σε περίπτωση κωδικού πληρωμής χωρίς έλεγχο ποσού: καταχωρείται ένα ORDER σε status PAID με το ποσό που αντιστοιχεί στην πληρωμή που ήρθε.

* Σημείωση:
Το status της παραγγελίας αλλάζει από PAID σε COMPLETED στις 2 παρακάτω περιπτώσεις:

Εάν το PayByBank API πάρει επιτυχή απάντηση στην POST κλήση που θα πραγματοποιήσει στο paymentURL. Σαν επιτυχημένη απάντηση ορίζεται μόνο η επιστροφή ενός σκέτου text ΟΚ
Εάν Ολοκληρωθούν οι προσπάθειες για την ενημέρωση του Merchant και ο PayByBank API μετά από 10 retries (1 προσπάθεια ανά 3 λεπτά) δεν πάρει επιτυχή απάντηση στην POST κλήση που θα γίνει στο paymentURL. Σε αυτή την περίπτωση είναι στην ευθύνη του Merchant να πραγματοποιήσει την κλήση GetStatus (2.Β. Από την ενότητα Κατηγορίες και Κλήσεις) για να γνωρίζει την κατάσταση της παραγγελίας.

Merchant PaymentURL:

Το PaymentURL μας το στέλνετε και το δηλώνουμε πάνω στο Merchant account.

Διαδικασία διασύνδεσης

Για να μπορέσετε να διασυνδεθείτε παραγωγικά με τον τρόπο πληρωμής PayByBank και να γίνουν όλοι οι απαραίτητοι έλεγχοι σχετικά με την υλοποίησή του θα πρέπει να προχωρήσετε στα παρακάτω βήματα:

Βήμα 1:

Υλοποίηση των απαραίτητων κλήσεων μέσα από το PlayGround του τρόπου πληρωμής PayByBank

Βήμα 2:

Πιστοποίηση της υλοποίησης πάνω στο συγκεκριμένο Payment URL που έχει δηλώσει ο developer σας όπως περιγράφεται αναλυτικά παρακάτω.

Διαδικασία πιστοποίησης

Για να ενεργοποιηθεί το Merchant account στην παραγωγή, απαιτείται η διασφάλιση της υλοποίησης που έχει γίνει στο test περιβάλλον με βάση και το paymentURL που έχει δηλώσει ο Merchant ή ο υπεύθυνος developer.

Το τεστ που πραγματοποιείται θα γίνει πάνω σε αυτό το paymentURL για να επιβεβαιωθεί ότι είναι λειτουργικό. Εφόσον η πιστοποίηση γίνει με αυτό το payment URL το ίδιο URL θα χρησιμοποιηθεί και στην παραγωγή (αν αυτό δεν είναι εφικτό τότε θα πρέπει να γίνει εκ νέου η πιστοποίηση και για το παραγωγικό Payment URL)

Υποχρεωτικά θα πρέπει να έχουν υλοποιηθεί οι παρακάτω κλήσεις:

Add order call (2.Δ. Από την ενότητα Κατηγορίες και Κλήσεις)
Get status call (2.Β. Από την ενότητα Κατηγορίες και Κλήσεις)

Επιπλέον θα ακολουθηθούν τα παρακάτω βήματα:

Μας αποστέλλετε μέσω email (integration@paybybank.eu):

Το paymentURL στο οποίο θα γίνει το HTTP POST notification για την ολοκλήρωση της πληρωμής.
Ένα test ORDER που έχετε πραγματοποιήσει από το Merchant λογαριασμό σας.

Αυτό το ORDER object μπορείτε να το πάρετε και αυτούσιο από το Playground όπως σας επιστρέφεται με την επιτυχημένη καταχώριση ενός Order.

Γυρίζουμε το status του παραπάνω ORDER από PENDING σε PAID για να γίνουν οι προσπάθειες για το POST.
Το certification process ολοκληρώνεται όταν το PayByBank API πάρει επιτυχή απάντηση στο HTTP POST (OK).

Σημείωση:

Πάντα πρέπει να γίνεται έλεγχος του status του Object που σας κάνουμε POST, καθώς στο ίδιο paymentUrl γίνονται POST και τα ORDER με status READY_TO_CANCEL/CANCELLED σε περίπτωση απόρριψης της πληρωμής αν λήξει ο χρόνος ζωής της παραγγελίας.

Βήμα 3:

Αφού ολοκληρωθεί με επιτυχία η διασύνδεση τότε θα πρέπει να ενημερώσετε για τις IPs από τις οποίες θα πραγματοποιούνται οι κλήσεις (και όπου θα έρχεται το notification) καθώς και να επιβεβαιώσετε πως το παραγωγικό URL είναι το ίδιο (και στον ίδιο server) με το test url.

*Αν το payment url της παραγωγής είναι διαφορετικό από το test τότε θα πρέπει να επαναληφθεί η πιστοποίηση (βήμα 2 παραπάνω). Προαιρετικά, και εφόσον το επιθυμείτε μπορείτε να ορίσει έναν προκαθορισμένο χρόνο ζωής για όλες τις παραγγελίες σας.

Για να γίνει αυτό, θα πρέπει να μας ενημερώσετε για τον χρόνο ζωής που επιθυμείτε μέσω email, διαφορετικά θα χρησιμοποιηθεί η προκαθορισμένη από το σύστημα τιμή (720 ώρες / 30 μέρες).

Βήμα 4:

Τέλος όταν τα παραπάνω βήματα έχουν ολοκληρωθεί με επιτυχία τότε:

Θα χρειαστεί να αντικαταστήσετε το test domain με το παραγωγικό URL ώστε να μεταβείτε στην παραγωγή. Σημείωση: Μόνο το domain (testapi.e-paylink.com ) θα πρέπει να αντικατασταθεί ενώ το υπόλοιπο URL θα παραμείνει ίδιο.
Θα ενεργοποιηθείτε στην παραγωγή αφού προηγουμένως έχετε λάβει το παραγωγικό API Key.

PayByBank Plugin: Σε περίπτωση που έχετε χρησιμοποιήσει κάποιο έτοιμο plugin για την επικοινωνία με το PayByBank τότε θα πρέπει η ομάδα του Integration να πιστοποιήσει το παραγωγικό σας payment url και στη συνέχεια να προχωρήσετε στα βήματα 4 & 5 για την παραλαβή του παραγωγικού API Key.

Playground

Δεν έχετε λογαριασμό; Δημιουργείστε τον λογαριασμό σας εδώ

Συνδεθείτε στο Playground

APIS:

Επιλέξτε πρώτα την κατηγορία που επιθυμείτε και στην συνέχεια την συγκεκριμένη κλήση και θα βρείτε αναλυτικές περιγραφές για την κάθε μέθοδο, τις παραμέτρους και το schema των Requests/Responses.

Ταυτόχρονα μπορείτε στην ενότητα “Playground” να κάνετε δοκιμές ώστε να δείτε ακριβώς την απάντηση του API ανάλογα με το κάθε request. Τις ίδιες ακριβώς κλήσεις θα πραγματοποιήσει και ο developer από το περιβάλλον ανάπτυξής του, οπότε το Playground μπορεί να χρησιμοποιηθεί και σαν μια πρώτη επιβεβαίωση ότι οι κλήσεις έχουν υλοποιηθεί σωστά.

OBJECTS:

Εδώ βλέπετε συγκεντρωτικά πληροφορίες σχετικά με τα Objects που επιστρέφονται από τις κλήσεις του API.

Κατηγορίες και Κλήσεις

Merchant services: Επιλέξτε την συγκεκριμένη κατηγορία για να δείτε τις κλήσεις που αφορούν στη διαχείριση του λογαριασμού σας στο PayByBank. Στην ενότητα αυτή, μπορείτε να δείτε τα στοιχεία του λογαριασμού σας και να αλλάξετε τον κωδικό του λογαριασμού σας (API Key).

Α. Επανάκτηση στοιχείων του λογαριασμού.
Path: /rest/api/v1/merchant/{api_key}

Β. Αλλαγή του API Key για τον λογαριασμό μου. Εφόσον καλέσετε αυτή την μέθοδο ένα νέο API Key θα σας επιστραφεί ενώ το προηγούμενο API Key δεν θα είναι πλέον έγκυρο.
Path: /rest/api/v1/merchant/{api_key}/password

Order services for merchants: Επιλέξτε την συγκεκριμένη κατηγορία για να δείτε όλες τις κλήσεις που αφορούν στη διαχείριση και αποστολή αιτημάτων έκδοσης κωδικών πληρωμής:
Ανάκτηση των Orders ενός merchant με δυνατότητα επιλογής ενός status πληρωμής.
Εφόσον δεν συμπληρωθεί το πεδίο status τότε θα επιστραφούν όλα τα αιτήματα πληρωμών. Για τα αιτήματα με σταθερό κωδικό πληρωμής θα επιστραφούν μόνο οι ολοκληρωμένες πληρωμές για τον συγκεκριμένο κωδικό (status Completed ή Paid). Για περιπτώσεις σταθερού κωδικού τα πεδία merchant_order_id και merchant_customer_id θα επιστραφούν μόνο εφόσον έχουν συμπληρωθεί κατά τηνκαταχώρηση του σταθερού κωδικού (κλήση Καταχώρησης αιτήματος έκδοσης κωδικού πληρωμής)

Path: /rest/api/v1/order/merchant/{api_key}?status={status}

Β. Ανάκτηση των Orders με δυνατότητα επιλογής ενός συγκεκριμένου αναγνωριστικού. Εφόσον δεν συμπληρωθεί το αναγνωριστικό (πεδίο merchant_order_id) τότε θα επιστραφούν όλες οι πληρωμές ενώ επιπρόσθετα δίνεται η δυνατότητα να περαστούν παραπάνω από ένα merchant_order_id χρησιμοποιώντας ένα κόμμα (“,”) σαν διαχωριστικό (π.χ 0001,0002).
Path: /rest/api/v1/order/merchant/{api_key}/{merchant_order_id}

Γ. Ακύρωση PENDING Order/ Απενεργοποίηση αιτήματος κωδικού πληρωμής. Εφόσον ολοκληρωθεί η απενεργοποίηση του κωδικού πληρωμής το συγκεκριμένο Order θα πάρει status CANCELLED_BY_MERCHANT. Η κλήση ισχύει και για κωδικούς πληρωμής χωρίς έλεγχο ποσού (κλήση Ε.) όπου ο κωδικός πληρωμής ακυρώνεται (isActivePaymentCode=0)
Path: /rest/api/v1/order/merchant/cancel/{api_key}}/{merchant_order_id}

Δ. Καταχώρηση αιτήματος έκδοσης κωδικού πληρωμής

Α. Mε έλεγχο ποσού (σε pending status).
Με την καταχώρηση του αιτήματος το Order object που θα λάβετε θα είναι σε status Pending. Μετά την πληρωμή της παραγγελίας μέσω Τράπεζας (βλέπε Διαδικασία Ροής PayByBank) Path:/rest/api/v1/order/merchant/{api_key}?merchant_order_id={merchant_order_id}&merch ant_customer_id={merchant_customer_id}&amount={amount}

Β. Xωρίς έλεγχο ποσού (σε active state)
Αν δεν καταχωρηθεί ποσό στο request (πεδίο Amount) τότε καταχωρείται ένα αίτημα κωδικού πληρωμής χωρίς έλεγχο ποσού. Με το συγκεκριμένο κωδικό μπορείτε να πραγματοποιήσετε πολλαπλές πληρωμές. Στην περίπτωση αυτή έχετε την επιλογή να καταχωρήσετε ή όχι το πεδίο merchant_order_id αφού πλέον ο κωδικός αυτός μπορεί να εξυπηρετεί την πληρωμή πολλαπλών orders. Αν χρησιμοποιείτε τη λογική κωδικού ανά merchant, η καταχώρηση έχει νόημα καθότι θα λαμβάνεται πίσω αυτή την πληροφόρηση σε κάθε πληρωμή. Από την άλλη δεν έχει νόημα σε κωδικούς που χρησιμοποιούνται από πολλούς merchants αφού δεν θα είναι κάτι σταθερό. Path:/rest/api/v1/order/merchant/{api_key}?merchant_order_id={merchant_order_id}&merch ant_customer_id={merchant_customer_id}

Για κάθε μέθοδο, περιγράφεται με λεπτομέρεια:

Path: το path της μεθόδου που θα καλέσει ο Merchant
Method: η HTTP κατηγορία κλήσης (Get, Post, Put)
Path Parameters: οι παράμετροι που πρέπει να περάσει ο Merchant στη μέθοδο.

Οι συγκεκριμένες παράμετροι περνιούνται στο URL του Request.

Query Parameters: οι παράμετροι αναζήτησης που πρέπει να περάσει ο Merchant στην κλήση της μεθόδου.
Αυτές οι παράμετροι περνιούνται επίσης στο URL της κλήσης (όπως πχ στην περίπτωση της κλήσης Α. όπου το status είναι Query Parameter, /rest/api/v1/order/merchant/0000-1111-2222-3333-4444?status=PAID)

Response Object:
To response που θα λάβει ο Merchant μετά την κλήση της μεθόδου

Errors:
Τα error responses που πιθανώς μπορεί να λάβει ο Merchant μετά την κλήση της μεθόδου.

Υποστηριζόμενα eCommerce Plugins