AxtonPay API

Üldine teave

API lõpp-punkt

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

Content-type

API aktsepteerib HTTP päringuid kahe sisutüübiga: 'application/x-www-form-urlencoded', 'application/json'.

HTTP päis peaks sobima POST keha sisuga.

Lühendid ja määratlused

• {PID} - Arve ID, tavaliselt on see unikaalne 8-kohaline tähestikuline ja numbriline jada.
• Shop - Teie veebisait, mis aktsepteerib makseid läbi AxtonPay teenuse

API-ga töötamise algoritm

Tavapärane tegevuste järjekord tasu saamiseks:

• loo arve ('/api/v1/private/checkout/payment/create'), API vastus tagastab arve URL-i ('invoice_url'),
• saada ostja sellele arvele maksmiseks,
• oota AxtonPay serveri teadete jaoks, mis tulevad 'server_notification_url',
• peale mis tahes teate kättesaamist AxtonPay, kontrollige selle allkirja kehtivust ja eelistatavalt saatke kinnitus kättesaamisest AxtonPay-le ('/api/v1/private/checkout/payment/confirm/{PID}'),
• kui arve olekut muudetakse, sooritage selle olekuga vastavad toimingud (nt taotlege kogu teavet arve kohta, saatke kaupu, looge tugimeeskonnale pilet jne).

Kui seadistate arve loomisel tühja või kehtetu 'server_notification_url', ei saa teenus saata teateid oleku muudatuste kohta; sellisel juhul peaksite arvet ise mingil ajal kontrollima ('/api/v1/private/checkout/payment/get/{PID}').

Päringute autoriseerimine

Selleks, et taotlust autoriseerida, on vajalik arvutada räsi stringist, mis on moodustatud erilise meetodi järgi. String koosneb URL-i argumentide (QUERY_STRING) ja POST taotluse keha (REQUEST_BODY) ühendamisest (kokku liitmisest). On oluline, et kõik komponendid võetaks täpselt sellisel kujul, nagu need serverisse edastatakse. URL-i argumendid (QUERY_STRING) tuleks võtta URL-ist ühe reana, muutmata argumentide järjekorda ja ilma elemente eemaldamata. POST taotluse keha (REQUEST_BODY) tuleks samuti kasutada muutmata kujul, sealhulgas ei tohi eemaldada tühikuid, jutumärke, sulgusid ega reavahetusi.

Tühja POST päringukehaga ja tühjade URL-argumentide puhul on see komponent lihtsalt tühi string.

Andmete järjestus allkirjastamise taotluses: QUERY_STRING esmalt, siis POST andmed. Nende vahele ei tohiks lisada mingeid ühendusmärke, lihtsalt liida kaks tekstijada kokku.

Veel kord, iga sümbol on oluline. Sa ei tohiks lisada ega eemaldada isegi tühikut või reavahetuse sümbolit. Kasuta ainult serveri poolt saadud toorandmeid.

Tulemusstringist võetakse võtmega 'Secret key' SHA-256 räsi ja seda kasutatakse funktsiooni hash_hmac() teise argumendina.

On kohustuslik edastada 'time' parameeter, mis sisaldab praegust POSIX timestamp (Unix time).

See allkiri kehtib 24 tundi. Kui 'time' parameetri väärtus erineb praegusest serveri ajast rohkem kui 24 tunni võrra (kas edasi või tagasi), ebaõnnestub päring isegi siis, kui allkiri on arvutatud ilma vigadeta.

Kui kaupmehe paneel on aktsepteerinud päringu mingi allkirjaga, ei saa seda allkirja uuesti kasutada, isegi kui saadetakse päring samade parameetritega (see hõlmab parameetrit 'time').

Tekkinud räsi edastatakse HTTP päisesse 'Sign'.

Lisaks arvutatud allkirjale peab päring sisaldama ka 'Api-Key' päist, mis sisaldab kasutatud API-võtit. Näide:

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

Sa võid allkirjastada AxtonPay saadetud päringu mis tahes kehtiva võtmega, mis kuulub selle kassa juurde. Kuid AxtonPay kasutab alati võtit, mille oled valinud kaupmehe paneelis.

Allkirja arvutamise näide:

/* 
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'
*/

Pööra tähelepanu tühikutele ja reavahetustele teises näites:

/* 
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"
}' 
*/

Näide Python stringi koostamisest allkirja arvutamiseks:

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

Parameetrid

API aktsepteerib kõiki parameetreid nii QUERY_STRING kui ka POST päringu kehas.

Boolese tüübi muutujad

API ootab, et Boolean-muutujad saaksid väärtuseks '0' või '1', kuid tänu kaudsele tüübikonversioonile käsitletakse mis tahes tekstistringi väärtusena '1', isegi sõna 'false' puhul. Seega, et määrata Boolean-muutujale otseselt 'FALSE' väärtus, peate sellele andma kas väärtuse '0' või tühja stringi.

Kümnendkoht

Numbrite puhul kasutatakse kümnendkoha eraldajana ainult koma.

Parameetrite tähe suurus

Mõne erandi tõttu on kõik parameetrid tõstutundlikud.

Tagasikutsumise URL

AxtonPay administraatori paneelis, ostuprotsessi seadete lehel on võimalik määrata poe URL-id serverist-serverisse teavituste vastuvõtmiseks AxtonPay-lt, samuti URL-id ostja suunamiseks pärast arve maksmist või selle tühistamist ning ka tõrke korral.

Neid URL-e saab arve loomise taotluses üle kirjutada.

AxtonPay API meetodid

Arve koostamine: /api/v1/private/checkout/payment/create

Meetod /api/v1/private/checkout/payment/create alustab arve loomist.

Kui meetod on edukas, tagastab see lingi ('invoice_url'), millele peaksite kliendi makse tegemiseks suunama.

Oma arve parameetrid:

• time (nõutav) - POSIX timestamp (Unix time)
• amount (nõutav) - tasumisele kuuluv summa (toote või teenuse hind, mida pood soovib saada)
• currency (nõutav) - 3-täheline valuutakood vastavalt ISO 4217-alpha, tõstutundlikkuseta
• pms (nõutav) - arveldusel kuvatavad makseviisid. Kui soovite lubada kõiki makseviise, on väärtus 'all'; kui soovite lubada ainult mõnda neist, loetlege nende komaeraldatud numbrilised identifikaatorid.
• pm - valitud makseviisi identifikaator. Oluline on, et kui 'pm' parameeter antakse, luuakse arve 'läbipaistvas režiimis', st ostja ei näe arve lehte, vaid suundub otse maksesüsteemi.
• extra_data - seotud massiiv, mis sisaldab kõiki täiendavaid andmeid; need andmed tagastatakse poodi tervikuna
• shop_user_id - kasutaja identifikaator poes, see tagastatakse poodi muutmata kujul
• shop_payment_id - makse identifikaator poes, see tagastatakse poodi muutmata kujul
• shop_name - poe nimi (kuvatakse arve lehel)
• shop_payment_desc - telli kirjeldus (kuvatakse arve lehel)
• shop_payment_remark - teie märkmed selle makse kohta (see on väli kõigile märkmetele, mis teil makse kohta on, mida AxtonPay mitte kuhugi ei saada; see on nähtav ainult maksete nimekirjas; see ei lähe tagasi poodi)
• valid_time - arve tasumise ajavahemik; sekundites
• view_time - ajavahemik, mille jooksul arve on välise lingi kaudu vaatamiseks kättesaadav; sekundites; taimer hakkab loendama pärast 'valid_time' perioodi lõppu
• server_notification_method - meetod makseolekute serveri-serveri teavituste saatmiseks poe suunas; kehtivad väärtused: POST, GET

Mõned arve seadistused on määratud kassaseadetega lehel. Kuid päringus edastatud väärtused omavad nende seadistuste üle eelise.

Kassaprotsessi parameetrid, mida saab selle arve jaoks muuta:

• customer_success_url - link, kuhu ostja suunatakse, kui arve on edukalt tasutud (st kui arve staatus on 'paid' või 'overpaid').
• customer_cancel_url - link, kuhu ostja suunatakse, kui makse tühistatakse
• customer_fail_url - link, kuhu ostja suunatakse, kui makse lõpeb veaga
• server_notification_url - link maksetingimuste server-serveri teavituste saatmiseks poodi

Märkus: Et järgida oma privaatsuspoliitikat, ei ole tavaliselt vajalik lisada arve omadustesse oma kliendi isikuandmeid. Näiteks "shop_user_id" parameetris on parem määrata abstraktne kliendi ID, mitte tema e-posti või telefoninumbrit. Samuti "shop_payment_desc" puhul on parem üldse mitte lisada kliendi andmeid, sest nad juba teavad enda kohta kõike; selle asemel võite kirjutada teavet ostetud kaupade või teenuste kohta või isegi lihtsalt tegevuse tüübi, näiteks „Ost“ või „Saldo täiendamine“.

Kõik viited edastatakse tingimata protokolliga.

Näide päringust:

<?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);
?>

Eduka vastuse näide arve loomise taotlemisel:

{
    "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"
}

Arveandmete saamine: /api/v1/private/checkout/payment/get/{PID}

Info saamiseks tuleb meetodit /api/v1/private/checkout/payment/get/{PID} kutsuda, märkides URL-i lõpus arve PID.

Päringu parameetrid:

• time (nõutav) - POSIX timestamp (Unix time)

Näide reast allkirja koostamiseks:

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

// String for signature calculation: 
time=1766837343

Vastuse näide:

{
    "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"
    }
}

Nõutud summa ja makstud summa võrdlus

Vastus sisaldab mitut erinevat summat (arve väljastamise valuutas):

• "amount" - arve summ
• "filled" - tasus osa arvest,
• "total_filled" - kui palju klient kokku maksis, sealhulgas komisjonitasud.

Kui "filled = amount", siis makstakse täpselt nii palju, kui vaja on.

Kui "filled > amount", on tegemist ülemaksega.

Kui "filled < amount", arve ei ole täielikult tasutud (alamtasu).

Arve: teate töötlemine AxtonPay staatuse muutuse kohta

Iga kord, kui arve staatust muudetakse, saadab AxtonPay teavituse server_notification_url-le (kasutades server_notification_method).

Näidisandmed:

{
    "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"
}

Selle teavituse peale ootab AxtonPay vastust HTTP code 200, mis kinnitab selle edukat kättesaamist. Vastasel juhul üritab AxtonPay veel 12 korda järjest kasvavate intervallidega, ning seejärel muutub teavituse staatus 'error'-ks (kuid see ei mõjuta arve enda staatust).

Võimalikud olekuväärtused:

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

Eduka makse staatused on 1 (paid) ja 5 (overpaid); nende kättesaamise korral saate tasutud ostu kliendile üle kanda või tasakaalu täiendada. Makse puhul staatuses 5 (overpaid) saate tasakaalu täiendada tegelikult laekunud makse summaga, kuid kaupade/teenuste müügi ja olulise ülemakse korral on soovitatav pöörduda makse sooritaja poole ja kokku leppida, kuidas ülemaksega toimida.

Osaliselt edukas olek on 4 (underpaid); selle oleku saamisel on võimalik tasakaalu täiendada tegelikult laekunud makse summas. Kuid seda olekut ei saa pidada kaupade/teenuste müügi eduka oleku märgiks.

Kõik teised olekud - 0 (pending), 2 (error), 3 (canceled by customer) tähendavad makse täielikku puudumist; nende saamisel ei tohiks teha mingeid toiminguid saldo täiendamiseks või kaupade/teenuste müügiks.

Allkirja kontrollimine

Et olla kindel, et teavituse on saatnud täpselt AxtonPay, on vaja enne selle usaldamist kontrollida saadud teavituse allkirja. Kontrollimine on sarnane oma päringute allkirjastamisele, ainult et lisatakse viimane samm, kus tuleks arvutatud allkirja võrrelda saadud HTTP päisega 'Sign'.

Peamised sammud pärast teavituse saamist muudetud makse staatuse kohta on järgmised:

• võta kogu argumentide jada (QUERY_STRING) saadud teavitusest,
• võta kogu POST data (REQUEST_BODY) saadud teavitusest,
• arvuta allkiri kasutades neid QUERY_STRING + REQUEST_BODY ja sobivat 'Secret key',
• võrrelge arvutatud allkirja HTTP-päisesse saadud allkirjaga 'Sign',
• kui allkirjad on samad, siis teavitus tuli tõepoolest AxtonPay-lt;
• kui allkirjad on erinevad, võib see olla makstava poolt petmise katsena.

Näide realt allkirja genereerimiseks:

// 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

Kinnitus, et pood on tasumise info töödelnud: /api/v1/private/checkout/payment/confirm/{PID}

See päring saadetakse AxtonPay-le vastuseks sellelt saadud teatele. Funktsionaalselt on see kinnitus, et pood on edukalt saanud ja töötlenud saadud teate.

Päringu saatmiseks kutsuge meetod /api/v1/private/checkout/payment/confirm/{PID}, määrates URL-i lõpus arve pid-i.

Päringu parameetrid:

• time (nõutav) - POSIX timestamp (Unix time)
• status (nõutav, täisarv) - makse staatuse number, mille kohta pood saadab kinnituse

Kui edastatud olek vastab selle arve praegusele olekule süsteemis, vastab AxtonPay 'OK' ja kui see ei klapi, vastab see veaga.

Näide realt allkirja genereerimiseks:

// 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"}

Vastuse näide, kui praegune makse staatus on sama:

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

Näide vastusest, kui praegune makse staatus erineb päringus edastatud staatusest:

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

Valuutakoodid

Valuutad, mida saab kasutada arve koostamiseks.

Enamik kasutatud valuutakoodidest kuulub fiat-valuutadele ja need on võrdsed ISO 4217. Samuti sisaldab nimekiri mitut krüptovaluutat.