AxtonPay API

Κοινές πληροφορίες

Τερματικό σημείο API

https://mp.axtonpay.com/api/v1/private/checkout

Content-type

Το API δέχεται HTTP αιτήματα με 2 τύπους περιεχομένου: 'application/x-www-form-urlencoded', 'application/json'.

Η κεφαλίδα HTTP θα πρέπει να ταιριάζει με το περιεχόμενο του σώματος POST.

Συντομογραφίες και ορισμοί

• {PID} - Ταυτότητα του τιμολογίου, συνήθως είναι η μοναδική αλφαριθμητική ακολουθία 8 χαρακτήρων.
• Shop - Η ιστοσελίδα σας που δέχεται πληρωμές μέσω της υπηρεσίας AxtonPay

Αλγόριθμος εργασίας με API

Συνήθης ακολουθία ενεργειών για να λάβετε πληρωμή:

• δημιουργήστε ένα τιμολόγιο ('/api/v1/private/checkout/payment/create'), η απάντηση του API θα επιστρέψει το URL του τιμολογίου ('invoice_url'),
• στείλε τον αγοραστή σε αυτό το τιμολόγιο για να πραγματοποιήσει την πληρωμή,
• περίμενε για AxtonPay ειδοποιήσεις διακομιστή, που θα έρχονται στο 'server_notification_url',
• κατά την παραλαβή οποιασδήποτε ειδοποίησης από AxtonPay, ελέγξτε την εγκυρότητα της υπογραφής της και κατά προτίμηση στείλτε μια επιβεβαίωση παραλαβής στο AxtonPay ('/api/v1/private/checkout/payment/confirm/{PID}'),
• εάν αλλάξει η κατάσταση ενός τιμολογίου, εκτελέστε ενέργειες που αντιστοιχούν σε αυτή την κατάσταση (π.χ., ζητήστε πλήρεις πληροφορίες σχετικά με το τιμολόγιο, στείλτε τα εμπορεύματα, δημιουργήστε ένα δελτίο για την ομάδα υποστήριξης κ.λπ.).

Εάν ορίσετε ένα κενό ή άκυρο 'server_notification_url' κατά τη δημιουργία ενός τιμολογίου, η υπηρεσία δεν μπορεί να στέλνει ειδοποιήσεις σχετικά με αλλαγές κατάστασης· σε τέτοιες περιπτώσεις, θα πρέπει να ελέγχετε εσείς το τιμολόγιο σε κάποια διαστήματα ('/api/v1/private/checkout/payment/get/{PID}').

Έγκριση αιτήσεων

Για να εξουσιοδοτηθεί ένα αίτημα, είναι απαραίτητο να υπολογιστεί ένα Hash από μια συμβολοσειρά που σχηματίζεται με ειδικό τρόπο. Η συμβολοσειρά αποτελείται από την συνένωση (ένωση) των παραμέτρων URL (QUERY_STRING) και του σώματος του αιτήματος POST (REQUEST_BODY). Είναι σημαντικό όλα τα στοιχεία να ληφθούν ακριβώς με τη μορφή που θα μεταδοθούν στον διακομιστή. Οι παράμετροι URL (QUERY_STRING) πρέπει να ληφθούν από το URL ως μία ενιαία γραμμή, χωρίς αλλαγή της σειράς των παραμέτρων και χωρίς να αφαιρεθεί οποιοδήποτε στοιχείο. Το σώμα του αιτήματος POST (REQUEST_BODY) πρέπει επίσης να χρησιμοποιηθεί χωρίς καμία τροποποίηση, συμπεριλαμβανομένου του ότι δεν πρέπει να αφαιρεθούν από αυτό εισαγωγικά, κενά, αγκύλες ή διακοπές γραμμής.

Στις περιπτώσεις ενός κενό POST σώματος αιτήματος, και στην περίπτωση κενών παραμέτρων URL, εκείνο το στοιχείο θα είναι απλώς κενή συμβολοσειρά.

Η ακολουθία των δεδομένων στο αίτημα υπογραφής: QUERY_STRING πρώτα, μετά τα POST δεδομένα. Δεν πρέπει να εισάγετε κανένα σημείο σύνδεσης μεταξύ τους, απλώς συνενώστε τις δύο συμβολοσειρές κειμένου.

Για άλλη μια φορά, κάθε σύμβολο είναι σημαντικό. Δεν πρέπει να προσθέσετε ή να αφαιρέσετε ούτε ένα κενό ή σύμβολο νέας γραμμής. Απλώς χρησιμοποιήστε τα ακατέργαστα δεδομένα που λαμβάνονται από τον διακομιστή.

Ένα SHA-256 hash με το κλειδί 'Secret key' λαμβάνεται από τη προκύπτουσα συμβολοσειρά και χρησιμοποιείται ως το δεύτερο όρισμα της συνάρτησης hash_hmac().

Είναι υποχρεωτικό να περάσετε την παράμετρο 'time' που περιέχει το τρέχον POSIX timestamp (Unix time).

Αυτή η υπογραφή είναι έγκυρη για 24 ώρες. Εάν η τιμή της παραμέτρου 'time' διαφέρει από την τρέχουσα ώρα του διακομιστή κατά περισσότερο από 24 ώρες (είτε προς τα εμπρός είτε προς τα πίσω), το αίτημα θα αποτύχει ακόμη και αν η υπογραφή υπολογιστεί χωρίς σφάλματα.

Αν το πάνελ του εμπόρου έχει αποδεχθεί ένα αίτημα με κάποια υπογραφή, αυτή η υπογραφή δεν μπορεί να χρησιμοποιηθεί ξανά, ακόμη και για να σταλεί το αίτημα με τις ίδιες παραμέτρους (αυτό περιλαμβάνει την παράμετρο 'time').

Το αποτέλεσμα του hash περνάει στην κεφαλίδα HTTP 'Sign'.

Εκτός από την υπολογισμένη υπογραφή, το αίτημα πρέπει επίσης να περιέχει μια επικεφαλίδα 'Api-Key' που περιέχει το χρησιμοποιούμενο κλειδί API. Παράδειγμα:

$headers = [
      'Api-Key: ' . $the_api_key,
      'Sign: ' . $signature_sha256
    ];

Μπορείτε να υπογράψετε το αίτημα που στάλθηκε στο AxtonPay με οποιοδήποτε έγκυρο κλειδί που ανήκει σε αυτό το ταμείο. Ωστόσο, το AxtonPay χρησιμοποιεί πάντα το κλειδί που έχετε επιλέξει στον πίνακα ελέγχου του εμπόρου.

Παράδειγμα υπολογισμού υπογραφής:

/* 
Imagine there is the POST request:
URI: '/api/v1/private/checkout/payment/create?time=1735084500.3561'
POST body: '[email protected]&shop_payment_id=INVOICE-1746&pms=all&amount=19.95&currency=USD'
So there are HTTP query string and request body:
*/ 
$the_query_string = 'time=1735084500.3561';
$the_request_body = '[email protected]&shop_payment_id=INVOICE-1746&pms=all&amount=19.95&currency=USD';

// • A pair of 'API key' and 'Secret key' gathered from the admin panel
$the_api_key = 'key1';
$the_api_secret = 'secret1';

// • Concatenation:
$string_for_sha = $the_query_string . $the_request_body;
// Value: '[email protected]&shop_payment_id=INVOICE-1746&pms=all&amount=19.95&currency=USD'

// • Calculating the HTTP header 'Sign'
// hash method is SHA-256
$signature_sha256 = hash_hmac("sha256", $string_for_sha, $the_api_secret); 
// '31ca271a15e45802e07b7559a5f520656c050dda79e6fa46d52a15fc51d193cd'

/* • Signed HTTP request:
  Method: POST
  URI: '/api/v1/private/checkout/payment/create?time=1735084500.3561'
  HTTP header 'Api-Key': 'key1'
  HTTP header 'Sign': '31ca271a15e45802e07b7559a5f520656c050dda79e6fa46d52a15fc51d193cd'
  POST body: '[email protected]&shop_payment_id=INVOICE-1746&pms=all&amount=19.95&currency=USD'
*/

Δώστε προσοχή στα κενά και στα διαλείμματα γραμμής σε ένα άλλο παράδειγμα:

/* 
Imagine there is the POST request:
URI: '/api/v1/private/checkout/payment/create?shop_name=Very%20useful%20service'
POST body: '{
  "shop_user_id": "[email protected]",
  "shop_payment_id": "INVOICE-1746",
  "shop_payment_desc": "Premium service
(1 month)",

  "pms": "all",
  "amount": "19.95",
  "currency": "USD",
  "time": "1735084500.3561"
}'

Attention! It's important to keep the raw data 'as is', including all tabulations, whitespaces, and line breaks. 
For example, the signature becomes invalid if your software formats json, adds or removes spaces. 

So there are such HTTP query string and POST request body:
*/ 
$the_query_string = 'shop_name=Very%20useful%20service';
$the_request_body = '{
  "shop_user_id": "[email protected]",
  "shop_payment_id": "INVOICE-1746",
  "shop_payment_desc": "Premium service
(1 month)",

  "pms": "all",
  "amount": "19.95",
  "currency": "USD",
  "time": "1735084500.3561"
}';

// • A pair of 'API key' and 'Secret key' gathered from the merchant panel
$the_api_key = 'key1';
$the_api_secret = 'secret1';

// • Concatenation:
//
// hash method is SHA-256 (HTTP query string + request body)
$string_for_sha = $the_query_string . $the_request_body;
/* Value: 'shop_name=Very%20useful%20service{
  "shop_user_id": "[email protected]",
  "shop_payment_id": "INVOICE-1746",
  "shop_payment_desc": "Premium service
(1 month)",

  "pms": "all",
  "amount": "19.95",
  "currency": "USD",
  "time": "1735084500.3561"
}'
*/

// • Calculating the HTTP header 'Sign'

$signature_sha256 = hash_hmac("sha256", $string_for_sha, $the_api_secret); 
// 'ef15476f28b379e4b137a2dcd9ed495332e4766004ac3610bb92a69ba2303c28'

/* • Signed HTTP request:
  Method: POST
  URI: '/api/v1/private/checkout/payment/create'
  HTTP header 'Api-Key': 'key1'
  HTTP header 'Sign': 'ef15476f28b379e4b137a2dcd9ed495332e4766004ac3610bb92a69ba2303c28'
  POST body: '{
  "shop_user_id": "[email protected]",
  "shop_payment_id": "INVOICE-1746",
  "shop_payment_desc": "Premium service
(1 month)",

  "pms": "all",
  "amount": "19.95",
  "currency": "USD",
  "time": "1735084500.3561"
}' 
*/

Το Python παράδειγμα σύνθεσης της σειράς για τον υπολογισμό της υπογραφής:

string_for_hash_calculation = f'{request.query_params.urlencode()}{request.data.urlencode()}'

Παράμετροι

Το API δέχεται όλες τις παραμέτρους τόσο στο QUERY_STRING όσο και στο σώμα του POST αιτήματος.

Μεταβλητές Boolean

Το API αναμένει να λάβει '0' ή '1' σε Boolean μεταβλητές, αλλά λόγω της έμμεσης μετατροπής τύπων, οποιοδήποτε κείμενο θα θεωρείται ως '1', ακόμη και η λέξη 'false'. Έτσι, για να ορίσετε ρητά μια τιμή 'FALSE' για μια Boolean μεταβλητή, πρέπει να της περάσετε είτε την τιμή '0' είτε μια κενή συμβολοσειρά.

Δεκαδικός διαχωριστής

Μόνο η δεκαδική τελεία χρησιμοποιείται ως δεκαδικός διαχωριστής στους αριθμούς.

Μεγέθος χαρακτήρων στις παραμέτρους

Με λίγες εξαιρέσεις, όλοι οι παράμετροι είναι ευαίσθητοι σε πεζά-κεφαλαία.

Διεύθυνση URL επανάκλησης

Στο πάνελ διαχείρισης του AxtonPay, στη σελίδα ρυθμίσεων ολοκλήρωσης αγοράς, είναι δυνατό να οριστούν διευθύνσεις URL του καταστήματος για τη λήψη ειδοποιήσεων server-server από το AxtonPay, καθώς και διευθύνσεις URL για την ανακατεύθυνση του αγοραστή μετά την πληρωμή του τιμολογίου ή την ακύρωσή του, καθώς και σε περίπτωση σφάλματος.

Αυτά τα URL μπορούν να παρακαμφθούν στο αίτημα δημιουργίας τιμολογίου.

Μέθοδοι του AxtonPay API

Δημιουργία τιμολογίου: /api/v1/private/checkout/payment/create

Η μέθοδος /api/v1/private/checkout/payment/create ξεκινά τη δημιουργία του τιμολογίου.

Εάν είναι επιτυχής, η μέθοδος επιστρέφει έναν σύνδεσμο ('invoice_url') στον οποίο θα πρέπει να κατευθύνετε τον πελάτη για πληρωμή.

Δικές παραμέτρους τιμολογίου:

• time (απαιτείται) - POSIX timestamp (Unix time)
• amount (απαιτείται) - ποσό προς πληρωμή (η τιμή του προϊόντος ή της υπηρεσίας που θέλει να λάβει το κατάστημα)
• currency (απαιτείται) - Κωδικός νομίσματος 3 γραμμάτων σύμφωνα με ISO 4217-alpha, χωρίς διάκριση πεζών-κεφαλαίων
• pms (απαιτείται) - μέθοδοι πληρωμής που εμφανίζονται στη σελίδα τιμολογίου. Εάν θέλετε να επιτρέψετε όλες τις μεθόδους πληρωμής, η τιμή είναι 'all'· εάν θέλετε να επιτρέψετε μόνο μερικές από αυτές, καταγράψτε τους αριθμητικούς τους αναγνωριστικούς, χωρισμένους με κόμμα.
• pm - ταυτότητα της επιλεγμένης μεθόδου πληρωμής. Είναι σημαντικό ότι αν περαστεί η παράμετρος 'pm', το τιμολόγιο θα δημιουργηθεί σε 'διαφανή λειτουργία', δηλαδή ο αγοραστής δεν θα δει τη σελίδα του τιμολογίου, αλλά θα μεταβεί απευθείας στο σύστημα πληρωμών.
• extra_data - ένα συσχετιστικό πίνακα που περιέχει οποιαδήποτε πρόσθετα δεδομένα· αυτά τα δεδομένα επιστρέφονται στο κατάστημα στο σύνολό τους
• shop_user_id - αναγνωριστικό χρήστη στο κατάστημα, επιστρέφεται στο κατάστημα με την αμετάβλητη μορφή
• shop_payment_id - αναγνωριστικό πληρωμής στο κατάστημα, επιστρέφεται στο κατάστημα με την αμετάβλητη μορφή
• shop_name - όνομα καταστήματος (εμφανίζεται στη σελίδα του τιμολογίου)
• shop_payment_desc - περιγραφή παραγγελίας (εμφανίζεται στη σελίδα του τιμολογίου)
• shop_payment_remark - οι σημειώσεις σας σχετικά με αυτή την πληρωμή (αυτό είναι ένα πεδίο για τυχόν σημειώσεις που έχετε σχετικά με την πληρωμή, τις οποίες AxtonPay δεν στέλνει πουθενά· είναι ορατές μόνο στη λίστα πληρωμών· δεν επιστρέφει στο κατάστημα)
• valid_time - το χρονικό διάστημα μέσα στο οποίο μπορεί να πληρωθεί το τιμολόγιο· σε δευτερόλεπτα
• view_time - χρονικό διάστημα κατά το οποίο το τιμολόγιο είναι διαθέσιμο για προβολή μέσω εξωτερικού συνδέσμου· σε δευτερόλεπτα· η αντίστροφη μέτρηση ξεκινά μετά τη λήξη της περιόδου 'valid_time'
• server_notification_method - μέθοδος αποστολής ειδοποιήσεων διακομιστή-διακομιστή σχετικά με τα στάδια πληρωμής στο κατάστημα· έγκυρες τιμές: POST, GET

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

Παράμετροι ολοκλήρωσης αγοράς που μπορούν να παρακαμφθούν για αυτό το τιμολόγιο:

• customer_success_url - ένας σύνδεσμος στον οποίο θα ανακατευθυνθεί ο αγοραστής εάν το τιμολόγιο καταβληθεί επιτυχώς (δηλαδή αν η κατάσταση του τιμολογίου είναι 'paid' ή 'overpaid').
• customer_cancel_url - ένας σύνδεσμος στον οποίο θα ανακατευθυνθεί ο αγοραστής εάν η πληρωμή ακυρωθεί
• customer_fail_url - ένας σύνδεσμος στον οποίο θα ανακατευθυνθεί ο αγοραστής εάν η πληρωμή καταλήξει σε σφάλμα
• server_notification_url - σύνδεσμος για την αποστολή ειδοποιήσεων κατάστασης πληρωμών από διακομιστή σε διακομιστή στο κατάστημα

Σημείωση: Προκειμένου να τηρείτε τη δική σας πολιτική απορρήτου, συνήθως δεν είναι απαραίτητο να περιλαμβάνετε τα προσωπικά δεδομένα του πελάτη σας στις ιδιότητες του τιμολογίου. Για παράδειγμα, στην παράμετρο "shop_user_id", είναι προτιμότερο να καθορίσετε ένα αφηρημένο αναγνωριστικό πελάτη αντί για το email ή τον αριθμό τηλεφώνου τους. Επίσης, στο "shop_payment_desc", είναι καλύτερο να μην περιλαμβάνονται καθόλου τα δεδομένα του πελάτη, διότι αυτά γνωρίζουν ήδη όλα για τον εαυτό τους· αντ’ αυτού, μπορείτε να γράψετε κάποιες πληροφορίες για τα πληρωμένα προϊόντα ή τις υπηρεσίες, ή ακόμη και απλώς να γράψετε τον τύπο της ενέργειας, για παράδειγμα, "Αγορά" ή "Φόρτωση υπολοίπου".

Όλες οι αναφορές μεταδίδονται απαραίτητα με το πρωτόκολλο.

Παράδειγμα αιτήματος:

<?php
// API credentials - get it from settings of the checkout
$api_key = 'API_KEY';
$api_secret = 'API_SECRET';
// API endpoint
$api_endpoint = 'https://mp.axtonpay.com/api/v1/private/checkout';
// Current POSIX timestamp
$time = time();
// API method URL
$api_url = $api_endpoint . '/payment/create';

// Prepare POST parameters
$post_data = [
    'amount' => 4.99,
    'currency' => 'USD',
    'pms' => 'all', // visible payment methods; either 'all' or comma-separated list of selected GUIDs
    // 'pm' => '92807385', // define the certain payment method if you do not want payer to see the list of all possible payment methods

    // Below parameters are optional
    'extra_data' => ['param1'=>'value 1', 'param2'=>'value 2'],

    'shop_user_id' => '[email protected]',
    'shop_payment_id' => 'TEST-333-' . $time,
    'shop_name' => 'TEST-333 web shop',
    'shop_payment_desc' => 'TEST-333 payment description visible to payer',
    'shop_payment_remark' => 'TEST-333 payment remark for admin',

    'customer_success_url' => 'https://example.com/?status=paid-or-overpaid&once=TEST-333-' . $time, 
    'customer_cancel_url' => 'https://example.com/?status=cancelled-by-payer&once=TEST-333-' . $time,
    'customer_fail_url' => 'https://example.com/?status=error&once=TEST-333-' . $time,
    'server_notification_url' => 'https://example.com/?for=server-to-server-notificataions',
    'server_notification_method' => 'POST',
	
    'valid_time' => 60*60*24*7, // seconds
    'view_time'  => 60*60*24*21, // seconds, clock starts after ending of 'valid_time' period
];

// Prepare GET parameters
$query_string = 'time=' . $time;

// Build the request body
$request_body = json_encode($post_data); // Encode as JSON
// $request_body = http_build_query($post_data);

// Concatenate QUERY_STRING and REQUEST_BODY
$string_for_sha = $query_string . $request_body;

// Calculate the signature
$signature = hash_hmac('sha256', $string_for_sha, $api_secret);

// Prepare HTTP headers
$headers = [
    'Api-Key: ' . $api_key,
    'Sign: ' . $signature,
    'Content-Type: application/json'
];

// Initialize cURL
$ch = curl_init($api_url . '?' . $query_string);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $request_body);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);

// Execute the request
$response = curl_exec($ch);

// Close cURL
curl_close($ch);
?>

Παράδειγμα μιας επιτυχημένης απάντησης κατά την αίτηση δημιουργίας ενός τιμολογίου:

{
    "status": "ok",
    "data": "invoice created",
    "pid": "HNQ5CAHM",
    "test": false,
    "created_at": "2025-12-27T08:14:55.000000Z",
    "invoice_url": "https:\/\/27375212.b88pay.com\/i\/HNQ5CAHM"
}

Λήψη πληροφοριών τιμολογίου: /api/v1/private/checkout/payment/get/{PID}

Για να λάβετε τις πληροφορίες που χρειάζεστε, καλέστε τη μέθοδο /api/v1/private/checkout/payment/get/{PID}, καθορίζοντας το PID του τιμολογίου στο τέλος του URL.

Παράμετροι αιτήματος:

• time (απαιτείται) - POSIX timestamp (Unix time)

Παράδειγμα γραμμής για τη σύνταξη υπογραφής:

// Full URL:
https://mp.axtonpay.com/api/v1/private/checkout/payment/get/GIKR3XPY?time=1766837343

// String for signature calculation: 
time=1766837343

Παράδειγμα απάντησης:

{
    "status": "ok",
    "data": {
        "pid": "HNQ5CAHM",
        "checkout_guid": 34677320,
        "created_at": "2025-12-27 12:07:21",
        "updated_at": "2025-12-27 12:07:34",
        "data": {
            "ip": "1.2.3.4",
            "pms": "all",
            "extra_data": {
                "param1": "val1",
                "param2": "val2",
                "server_notification_url": "https:\/\/example.com\/?for=server-to-server-notificataions"
            },
            "redirect_url": "\/wait\/HNQ5CAHM",
            "customer_fail_url": "https:\/\/example.com\/?status=error&id=TEST-333-1766837240",
            "allow_change_amount": false,
            "customer_cancel_url": "https:\/\/example.com\/?status=cancelled-by-payer&id=TEST-333-1766837240",
            "customer_success_url": "https:\/\/example.com\/?status=paid-or-overpaid&id=TEST-333-1766837240"
        },
        "payment_status": 0,
        "amount": "4.99",
        "filled": "0.00",
        "currency_id": 5,
        "transparent": 1,
        "expires_at": "2026-01-03 12:07:21",
        "invisible_at": "2026-01-26 12:07:21",
        "paid_at": null,
        "confirmed_at": null,
        "shop_name": "TEST-333 web shop",
        "shop_user_id": "[email protected]",
        "shop_payment_id": "TEST-333-1766837240",
        "shop_payment_desc": "TEST-333 payment description visible to payer",
        "shop_payment_remark": "TEST-333 payment remark for merchant",
        "payment_method_id": 92807385,
        "gateway_id": 40056646,
        "payment_option_id": 297,
        "txid": null,
        "account_from": null,
        "account_to": "TEnYvbfg9YqJeaVtVHAwEvG2kmAJcTzxTh",
        "payment_option_amount": "17.865973",
        "payment_option_filled": "0.000000",
        "payment_option_currency_id": 317,
        "exchange_rates_expires_at": "2025-12-27 12:27:33",
        "test": false,
        "initiator": "api",
        "initiator_info": null,
        "payment_option": {
            "id": 297,
            "gateway_id": 40056646,
            "pm": "trx",
            "currency_id": 317,
            "name": "Tron",
            "icon": "crypto\/tron.png",
            "min_invoice": null,
            "max_invoice": null
        },
        "payment_option_currency": {
            "id": 317,
            "name": "Tron",
            "code": "TRX",
            "minor_unit": 6
        },
        "currency": {
            "id": 5,
            "name": "United States dollar",
            "code": "USD",
            "minor_unit": 2
        },
        "invoice_url": "https:\/\/27375212.b88pay.com\/i\/HNQ5CAHM"
    }
}

Σύγκριση του αιτούμενου ποσού και του καταβληθέντος ποσού

Η απάντηση περιέχει διάφορα διαφορετικά ποσά (στην νόμισμα στην οποία εκδόθηκε το τιμολόγιο):

• "amount" - τιμολογηθέν ποσό,
• "filled" - πληρώθηκε μέρος του τιμολογίου,
• "total_filled" - πόσο πλήρωσε συνολικά ο πελάτης, συμπεριλαμβανομένων των προμηθειών.

Αν "filled = amount", τότε πληρώνεται ακριβώς όσο χρειάζεται.

Αν "filled > amount", υπάρχει υπερπληρωμή.

Εάν "filled < amount", το τιμολόγιο δεν έχει εξοφληθεί πλήρως (υποπληρωμή).

Τιμολόγιο: επεξεργασία ειδοποίησης από AxtonPay σχετικά με αλλαγή κατάστασης

Κάθε φορά που αλλάζει η κατάσταση ενός τιμολογίου, AxtonPay στέλνει μια ειδοποίηση σε server_notification_url (χρησιμοποιώντας το server_notification_method)

Παράδειγμα δεδομένων:

{
    "pid": "U5IB4WIO",
    "status": "3",
    "shop_user_id": "3q23g",
    "shop_payment_id": "h76r5",
    "amount": "240.00000000",
    "filled": "0.00000000",
    "fee": "0",
    "total_filled": "0.00000000",
    "currency": "DASH",
    "test": "0"
}

Σε απάντηση σε αυτή την ειδοποίηση, AxtonPay αναμένει να λάβει HTTP code 200, το οποίο επιβεβαιώνει την επιτυχή παραλαβή της. Διαφορετικά, AxtonPay θα προσπαθήσει ξανά 12 φορές σε διαρκώς αυξανόμενα διαστήματα και στη συνέχεια η κατάσταση της ειδοποίησης αλλάζει σε 'error' (αλλά αυτό δεν επηρεάζει την κατάσταση του τιμολογίου καθαυτού).

Πιθανά τιμές κατάστασης:

• 0 - pending
• 1 - paid
• 2 - error
• 3 - cancelled by customer
• 4 - underpaid
• 5 - overpaid
• 8 - expired

Οι επιτυχημένες καταστάσεις πληρωμής είναι 1 (paid) και 5 (overpaid)· σε περίπτωση παραλαβής τους μπορείτε να μεταφέρετε την πληρωμένη αγορά στον πελάτη ή να ανανεώσετε το υπόλοιπο. Για τις πληρωμές με κατάσταση 5 (overpaid), σε περίπτωση ανανέωσης υπολοίπου μπορείτε να ανανεώσετε το υπόλοιπο με το ποσό της πραγματικά ληφθείσας πληρωμής, αλλά σε περίπτωση πώλησης αγαθών/υπηρεσιών και σημαντικού ποσού υπερπληρωμής συνιστάται να επικοινωνήσετε με τον πληρωτή και να αποφασίσετε μαζί του πώς να αντιμετωπίσετε την υπερπληρωμή.

Η κατάσταση μερικής επιτυχίας είναι 4 (underpaid)· σε περίπτωση λήψης αυτής της κατάστασης είναι δυνατή η επαναφόρτιση του υπολοίπου με το ποσό της πραγματικά ληφθείσας πληρωμής. Ωστόσο, αυτή η κατάσταση δεν μπορεί να θεωρηθεί επιτυχής για την πώληση αγαθών/υπηρεσιών.

Όλοι οι άλλοι καθεστώτες - 0 (pending), 2 (error), 3 (canceled by customer) σημαίνουν πλήρη απουσία πληρωμής· σε περίπτωση λήψης τους δεν πρέπει να πραγματοποιούνται ενέργειες για αναπλήρωση υπολοίπου ή πώληση αγαθών/υπηρεσιών.

Έλεγχος υπογραφής

Για να είστε σίγουροι ότι η ειδοποίηση έχει σταλεί ακριβώς από την AxtonPay, είναι απαραίτητο να επαληθεύσετε την υπογραφή της ληφθείσας ειδοποίησης πριν την εμπιστευτείτε. Η επαλήθευση είναι παρόμοια με την υπογραφή των δικών σας αιτήσεων, μόνο ότι προστίθεται το τελευταίο βήμα, όπου πρέπει να συγκρίνετε την υπολογισμένη υπογραφή με την ληφθείσα κεφαλίδα HTTP 'Sign'.

Τα κύρια βήματα μετά τη λήψη ειδοποίησης για την αλλαγή της κατάστασης πληρωμής είναι τα εξής:

• πάρε ολόκληρη την ακολουθία επιχειρημάτων (QUERY_STRING) από την ληφθείσα ειδοποίηση,
• πάρε ολόκληρο το POST data (REQUEST_BODY) από την παραληφθείσα ειδοποίηση,
• υπολόγισε την υπογραφή χρησιμοποιώντας εκείνα τα QUERY_STRING + REQUEST_BODY και το κατάλληλο 'Secret key',
• συγκρίνετε την υπολογισμένη υπογραφή με αυτή που λαμβάνεται στην κεφαλίδα HTTP 'Sign',
• εάν οι υπογραφές είναι οι ίδιες, η ειδοποίηση προήλθε πραγματικά από AxtonPay;
• εάν οι υπογραφές είναι διαφορετικές, μπορεί να είναι μια απόπειρα εξαπάτησης από τον πληρωτή.

Παράδειγμα γραμμής για δημιουργία υπογραφής:

// Full URL:
https://EXAMPLE.COM?time=1737027838.1237

// POST body: 
pid=ABCD5678&status=1&shop_user_id=&shop_payment_id=&amount=25.00000000&filled=25.00000000&fee=0&total_filled=25.00000000&currency=RDD&test=0

// String for signature calculation: 
time=1737027838.1237pid=ABCD5678&status=1&shop_user_id=&shop_payment_id=&amount=25.00000000&filled=25.00000000&fee=0&total_filled=25.00000000&currency=RDD&test=0

Επιβεβαίωση ότι το κατάστημα έχει επεξεργαστεί τις πληροφορίες πληρωμής: /api/v1/private/checkout/payment/confirm/{PID}

Αυτό το αίτημα αποστέλλεται στο AxtonPay σε απάντηση μιας ειδοποίησης που ελήφθη από αυτό. Λειτουργικά, αποτελεί επιβεβαίωση ότι το κατάστημα έχει λάβει και επεξεργαστεί επιτυχώς την παραληφθείσα ειδοποίηση.

Για να στείλετε ένα αίτημα, καλέστε τη μέθοδο /api/v1/private/checkout/payment/confirm/{PID}, δηλώνοντας το pid του τιμολογίου στο τέλος του URL.

Παράμετροι αιτήματος:

• time (απαιτείται) - POSIX timestamp (Unix time)
• status (απαιτείται, ακέραιος) - αριθμός κατάστασης πληρωμής για τον οποίο το κατάστημα στέλνει επιβεβαίωση

Αν η μεταδιδόμενη κατάσταση ταιριάζει με την τρέχουσα κατάσταση αυτού του τιμολογίου στο σύστημα, AxtonPay θα απαντήσει με 'OK' και αν δεν ταιριάζει, θα απαντήσει με σφάλμα.

Παράδειγμα γραμμής για δημιουργία υπογραφής:

// Full URL:
https://mp.axtonpay.com/api/v1/private/checkout/payment/confirm/ABCD5678?time=1737011414

// POST body: 
{"status":"1"}

// String for signature calculation:
time=1737011414{"status":"1"}

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

{
    "status": "ok",
    "data": "\"Paid\" status notification is confirmed"
}

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

{
    "status": "error",
    "message": "Something went wrong"
}

Κωδικοί νομισμάτων

Τα νομίσματα που μπορούν να χρησιμοποιηθούν για τη δημιουργία ενός τιμολογίου.

Οι περισσότεροι από τους χρησιμοποιούμενους κωδικούς νομισμάτων ανήκουν σε νομίσματα fiat, και είναι ίσοι με το ISO 4217. Η λίστα επίσης περιέχει αρκετά κρυπτονομίσματα.