AxtonPay API

Vanlig information

API-endpunkt

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

Content-type

API accepteras HTTP förfrågningar med 2 innehållstyper: 'application/x-www-form-urlencoded', 'application/json'.

HTTP rubriken bör passa innehållet i POST kroppen.

Förkortningar och definitioner

• {PID} - ID för fakturan, vanligtvis är det den unika 8-tecken långa alfanumeriska sekvensen.
• Shop - Din webbplats som accepterar betalningar via AxtonPay-tjänsten

Algoritm för arbete med API

Vanlig ordningsföljd av åtgärder för att få betalning:

• skapa en faktura ('/api/v1/private/checkout/payment/create'), API-svaret kommer att returnera fakturans URL ('invoice_url'),
• skicka köparen till denna faktura för att göra betalning,
• vänta på AxtonPay servermeddelanden, som kommer till 'server_notification_url',
• vid mottagande av någon avisering från AxtonPay, kontrollera giltigheten av dess signatur och skicka helst en kvittens på mottagandet till AxtonPay ('/api/v1/private/checkout/payment/confirm/{PID}'),
• om statusen på en faktura ändras, utför åtgärder som motsvarar denna status (t.ex. begär fullständig information om fakturan, skicka varorna, skapa en supportärende till supportteamet, etc.).

Om du anger en tom eller ogiltig 'server_notification_url' när du skapar en faktura, kan tjänsten inte skicka meddelanden om statusändringar; i sådana fall bör du kontrollera fakturan själv med jämna mellanrum ('/api/v1/private/checkout/payment/get/{PID}').

Auktorisering av förfrågningar

För att auktorisera en begäran är det nödvändigt att beräkna en hash från en sträng som bildas på ett speciellt sätt. Strängen består av att sammanfoga (limma ihop) URL-argumenten (QUERY_STRING) och kroppen av POST-begäran (REQUEST_BODY). Det är viktigt att alla komponenter tas exakt i den form de kommer att skickas till servern. URL-argumenten (QUERY_STRING) bör tas från URL:en som en enda rad, utan att ändra ordningen på argumenten och utan att ta bort några element. POST-begärans kropp (REQUEST_BODY) bör också användas utan några ändringar, inklusive att inte ta bort citattecken, mellanslag, parenteser eller radbrytningar.

I fall av en tom POST förfrågningskropp, och i fallet med tomma URL-argument, kommer den komponenten helt enkelt vara en tom sträng.

Sekvensen av data i signeringsbegäran: QUERY_STRING först, sedan POST-data. Du bör inte sätta in några sambandstecken mellan dem, utan bara sammanfoga de två textsträngarna.

Återigen, varje symbol är betydelsefull. Du bör inte lägga till eller ta bort ens ett blanksteg eller ny rad-symbol. Använd bara de råa data som mottagits av servern.

En SHA-256 hash med nyckeln 'Secret key' tas från den resulterande strängen och används som det andra argumentet till funktionen hash_hmac().

Det är obligatoriskt att skicka med 'time'-parametern som innehåller den aktuella POSIX timestamp (Unix time).

Denna signatur är giltig i 24 timmar. Om värdet på 'time'-parametern skiljer sig från den aktuella serverns tid med mer än 24 timmar (oavsett framåt eller bakåt), kommer begäran att misslyckas även om signaturen beräknas utan fel.

Om handlarpanelen har accepterat en begäran med någon signatur kan den signaturen inte användas igen, inte ens för att skicka begäran med samma parametrar (detta inkluderar parameter 'time').

Den resulterande hashen skickas i HTTP-huvudet 'Sign'.

Förutom den beräknade signaturen måste förfrågan också innehålla en 'Api-Key'-huvud som innehåller den använda API-nyckeln. Exempel:

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

Du kan signera begäran som skickats till AxtonPay med vilken giltig nyckel som helst som tillhör denna kassa. Dock använder AxtonPay alltid den nyckel som du har valt i merchantpanelen.

Exempel på signaturberäkning:

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

Uppmärksamma mellanslag och radbrytningar i ett annat exempel:

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

Det Python exemplet på att komponera strängen för signaturberäkning:

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

Parametrar

API:et accepterar alla parametrar både i QUERY_STRING och i kroppen av POST-förfrågan.

Booleska variabler

API:et förväntar sig att få '0' eller '1' i booleska variabler, men på grund av implicit typkonvertering kommer vilken textsträng som helst att behandlas som en '1', även ordet 'false'. Så, för att uttryckligen ange ett 'FALSE'-värde för en boolesk variabel, måste du skicka till den antingen värdet '0' eller en tom sträng.

Decimalavskiljare

Endast decimalpunkten används som decimalavskiljare i tal.

Bokstavsstorlek i parametrar

Med få undantag är alla parametrar skiftlägeskänsliga.

Återuppringnings-URL

I administrationspanelen för AxtonPay, på sidan med kassainställningar, är det möjligt att ange butikens URL:er för att ta emot server-till-server-notifikationer från AxtonPay, samt URL:er för att omdirigera köparen efter fakturabetalning eller dess avbokning, samt vid ett fel.

Dessa URL:er kan åsidosättas i fakturaskapandeförfrågan.

Metoder för AxtonPay API

Fakturaskapande: /api/v1/private/checkout/payment/create

Metod /api/v1/private/checkout/payment/create startar fakturaskapandet.

Om metoden lyckas returnerar den en länk ('invoice_url') till vilken du bör vidarebefordra kunden för betalning.

Egna fakturaparametrar:

• time (obligatoriskt) - POSIX timestamp (Unix time)
• amount (obligatoriskt) - belopp att betala (priset på produkten eller tjänsten som butiken vill erhålla)
• currency (obligatoriskt) - 3-bokstavig valutakod enligt ISO 4217-alpha, skiftlägesokänslig
• pms (obligatoriskt) - betalningsmetoder som visas på fakturasidan. Om du vill tillåta alla betalningsmetoder är värdet 'all'; om du vill tillåta endast vissa av dem, lista deras kommaseparerade numeriska identifierare.
• pm - identifier för den valda betalningsmetoden. Det är viktigt att om 'pm'-parametern skickas, kommer fakturan att skapas i 'transparent läge', det vill säga köparen kommer inte att se fakturasidan, utan kommer direkt till betalningssystemet.
• extra_data - en associativ array som innehåller alla ytterligare data; dessa data returneras till lagret i sin helhet
• shop_user_id - användaridentifierare i butiken, det returneras till butiken i oförändrad form
• shop_payment_id - betalningsidentifierare i butiken, den återlämnas till butiken i oförändrad form
• shop_name - butiksnamn (visas på fakturasidan)
• shop_payment_desc - orderbeskrivning (visas på fakturasidan)
• shop_payment_remark - dina anteckningar om denna betalning (detta är ett fält för eventuella anteckningar du har om betalningen, som AxtonPay inte skickar någonstans; det är endast synligt i listan över betalningar; det går inte tillbaka till butiken)
• valid_time - tidsintervallet under vilket fakturan kan betalas; i sekunder
• view_time - tidsintervall under vilket fakturan är tillgänglig för visning via extern länk; i sekunder; nedräkning startar efter att 'valid_time'-perioden har slutat
• server_notification_method - metod för att skicka server-till-server-notifikationer om betalningsstatus till butiken; giltiga värden: POST, GET

Vissa inställningar för fakturan är inställda på sidan för kassa-inställningar. Men de värden som skickas i förfrågan kommer att ha företräde framför dessa inställningar.

Checkout-parametrar som kan åsidosättas för denna faktura:

• customer_success_url - en länk som köparen kommer att omdirigeras till om fakturan är betald (dvs om fakturans status är 'paid' eller 'overpaid').
• customer_cancel_url - en länk till vilken köparen kommer att omdirigeras om betalningen avbryts
• customer_fail_url - en länk som köparen kommer att omdirigeras till om betalningen slutar med ett fel
• server_notification_url - länk för att skicka server-till-server-notifikationer om betalningsstatusar till butiken

Obs: För att följa din egen integritetspolicy är det vanligtvis inte nödvändigt att inkludera din kunds personuppgifter i fakturans egenskaper. Till exempel, i "shop_user_id"-parametern är det bättre att ange ett abstrakt kund-ID istället för deras e-postadress eller telefonnummer. Även i "shop_payment_desc" är det bättre att inte inkludera kunddata alls, eftersom de redan vet allt om sig själva; istället kan du skriva viss information om de betalda varorna eller tjänsterna, eller till och med bara skriva typen av åtgärd, till exempel "Köp" eller "Saldo påfyllning".

Alla referenser överförs nödvändigtvis med protokollet.

Exempel på förfrågan:

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

Exempel på ett framgångsrikt svar vid begäran om skapande av en faktura:

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

Hämtar fakturainformation: /api/v1/private/checkout/payment/get/{PID}

För att få den information du behöver, ring metoden /api/v1/private/checkout/payment/get/{PID} genom att ange PID för fakturan i slutet av URL:en.

Förfrågningsparametrar:

• time (obligatoriskt) - POSIX timestamp (Unix time)

Exempel på en rad för att komponera en signatur:

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

// String for signature calculation: 
time=1766837343

Exempel på ett svar:

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

Jämförelse av begärt belopp och utbetalt belopp

Svaret innehåller flera olika belopp (i den valuta som fakturan utfärdades i):

• "amount" - fakturerat belopp,
• "filled" - betalade en del av fakturan,
• "total_filled" - hur mycket kunden betalade totalt, inklusive provisioner.

Om "filled = amount", då betalas det exakt så mycket som det behöver.

Om "filled > amount", finns det en överbetalning.

Om "filled < amount", har fakturan inte betalats i sin helhet (underbetalning).

Faktura: bearbetning av meddelande från AxtonPay om statusändring

Varje gång statusen för en faktura ändras, skickar AxtonPay en avisering till server_notification_url (med hjälp av server_notification_method)

Exempeldata:

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

Som svar på denna avisering förväntar sig AxtonPay att ta emot HTTP code 200, vilket bekräftar dess framgångsrika mottagande. Annars kommer AxtonPay att försöka igen 12 gånger till med gradvis ökande intervall, och sedan ändras aviseringens status till 'error' (men detta påverkar inte själva fakturans status).

Möjliga statusvärden:

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

Framgångsrika betalningsstatus är 1 (paid) och 5 (overpaid); vid mottagande av dessa kan du överföra det betalda köpet till kunden eller fylla på saldot. För betalningar med status 5 (overpaid), vid påfyllning av saldo kan du fylla på saldot med det faktisk mottagna betalningsbeloppet, men vid försäljning av varor/tjänster och ett betydande överskottsbelopp är det lämpligt att kontakta betalaren och tillsammans bestämma hur man ska hantera överskottsbetalningen.

Delvis framgångsrik status är 4 (underpaid); vid mottagande av denna status är det möjligt att ladda om saldot med det belopp som faktiskt mottagits. Denna status kan dock inte betraktas som framgångsrik för försäljning av varor/tjänster.

Alla andra statusar - 0 (pending), 2 (error), 3 (canceled by customer) innebär fullständig frånvaro av betalning; vid mottagande av dessa bör inga åtgärder för påfyllning av saldo eller försäljning av varor/tjänster utföras.

Signaturkontroll

För att vara säker på att meddelandet skickas av AxtonPay exakt är det nödvändigt att verifiera signaturen på den mottagna notifikationen innan man litar på den. Verifikationen är liknande som att signera dina egna förfrågningar, bara att det sista steget läggs till, då du bör jämföra den beräknade signaturen med den mottagna HTTP-headern 'Sign'.

De viktigaste stegen efter att ha fått meddelande om den ändrade betalningsstatusen är följande:

• ta hela argumentsträngen (QUERY_STRING) från den mottagna notifikationen,
• ta hela POST data (REQUEST_BODY) från den mottagna aviseringen,
• beräkna signaturen med hjälp av dessa QUERY_STRING + REQUEST_BODY och den lämpliga 'Secret key',
• jämför den beräknade signaturen med den som tas emot i HTTP-headern 'Sign',
• om signaturerna är desamma, kom meddelandet verkligen från AxtonPay;
• Om signaturerna är olika kan det vara ett försök att fuska av betalaren.

Exempel på en rad för signaturgenerering:

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

Bekräftelse på att butiken har behandlat betalningsinformationen: /api/v1/private/checkout/payment/confirm/{PID}

Denna förfrågan skickas till AxtonPay som svar på ett meddelande som mottagits från den. Funktionellt är det en bekräftelse på att butiken framgångsrikt har tagit emot och behandlat det mottagna meddelandet.

För att skicka en förfrågan, anropa metoden /api/v1/private/checkout/payment/confirm/{PID}, genom att ange fakturans pid i slutet av URL:en.

Begärans parametrar:

• time (obligatoriskt) - POSIX timestamp (Unix time)
• status (obligatoriskt, heltal) - betalningsstatusnummer för vilket butiken skickar bekräftelse

Om den överförda statusen matchar den aktuella statusen för denna faktura i systemet, kommer AxtonPay att svara med 'OK' och om den inte matchar, kommer det att svara med ett fel.

Exempel på en rad för signaturgenerering:

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

Exempel på ett svar om den aktuella betalningsstatusen är densamma:

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

Exempel på ett svar om den aktuella betalningsstatusen skiljer sig från den som skickades i förfrågan:

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

Valutakoder

De valutor som kan användas för att skapa en faktura.

De flesta använda valutakoder tillhör fiatvalutor, och de är lika med ISO 4217. Listan innehåller också flera kryptovalutor.