AxtonPay API

Almindelig information

API-endpoint

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

Content-type

API accepterer HTTP-anmodninger med 2 indholdstyper: 'application/x-www-form-urlencoded', 'application/json'.

HTTP overskriften skal passe til indholdet af POST kroppen.

Forkortelser og definitioner

• {PID} - ID på fakturaen, det er normalt den unikke 8-cifrede alfanumeriske sekvens.
• Shop - Din hjemmeside, der accepterer betalinger gennem AxtonPay-tjenesten

Algoritme for arbejde med API

Sædvanlig rækkefølge af handlinger for at modtage betaling:

• opret en faktura ('/api/v1/private/checkout/payment/create'), API-svaret vil returnere fakturaens URL ('invoice_url'),
• send køberen til denne faktura for at foretage betaling,
• vent på AxtonPay servernotifikationer, som vil komme til 'server_notification_url',
• ved modtagelse af enhver meddelelse fra AxtonPay, skal du tjekke gyldigheden af dens underskrift og helst sende en kvittering for modtagelsen til AxtonPay ('/api/v1/private/checkout/payment/confirm/{PID}'),
• hvis status for en faktura ændres, udfør handlinger svarende til denne status (f.eks. anmod om fuld information om fakturaen, send varerne, opret en ticket til supportteamet osv.).

Hvis du angiver en tom eller ugyldig 'server_notification_url', når du opretter en faktura, kan tjenesten ikke sende notifikationer om statusændringer; i sådanne tilfælde bør du selv tjekke fakturaen med jævne mellemrum ('/api/v1/private/checkout/payment/get/{PID}').

Godkendelse af forespørgsler

For at godkende en forespørgsel er det nødvendigt at beregne en hash fra en streng dannet på en speciel måde. Strengen dannes ved at sammenkæde (lime sammen) URL-argumenterne (QUERY_STRING) og kroppen af POST-forespørgslen (REQUEST_BODY). Det er vigtigt, at alle komponenter tages nøjagtigt i den form, de vil blive sendt til serveren. URL-argumenterne (QUERY_STRING) skal tages fra URL'en som en enkelt linje, uden at ændre rækkefølgen af argumenterne og uden at udelade nogen elementer. POST-forespørgslens krop (REQUEST_BODY) skal også bruges uden nogen ændringer, inklusive ikke at fjerne citater, mellemrum, parenteser eller linjeskift.

I tilfælde af en tom POST anmodningskrop, og i tilfælde af tomme URL-argumenter, vil den komponent blot være en tom streng.

Sekvensen af data i underskriftsanmodningen: QUERY_STRING først, derefter POST data. Du bør ikke indsætte nogen forbindelsestegn mellem dem, blot sammenkæde de to tekststrenge.

Endnu en gang er hvert symbol vigtigt. Du bør ikke tilføje eller fjerne selv et mellemrum eller et linjeskift. Brug blot de rå data modtaget af serveren.

En SHA-256 hash med nøglen 'Secret key' tages fra den resulterende streng og bruges som det andet argument i funktionen hash_hmac().

Det er obligatorisk at afgive 'time'-parameteren, der indeholder den aktuelle POSIX timestamp (Unix time).

Denne signatur er gyldig i 24 timer. Hvis værdien af 'time'-parameteren afviger fra den nuværende servertid med mere end 24 timer (uanset om det er fremad eller bagud), vil anmodningen mislykkes, selvom signaturen er beregnet uden fejl.

Hvis handelsmandspanelet har accepteret en anmodning med en underskrift, kan den underskrift ikke bruges igen, selv ikke til at sende anmodningen med de samme parametre (dette inkluderer parameter 'time').

Den resulterende hash sendes i HTTP headeren 'Sign'.

Ud over den beregnede signatur skal forespørgslen også indeholde en 'Api-Key' header med den anvendte API-nøgle. Eksempel:

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

Du kan underskrive anmodningen, der blev sendt til AxtonPay, med enhver gyldig nøgle, der tilhører denne kasse. Dog bruger AxtonPay altid den nøgle, som du har valgt i handelspanelet.

Eksempel på beregning af signatur:

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

Vær opmærksom på mellemrum og linjeskift i et andet eksempel:

/* 
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 eksempel på at sammensætte strengen til signaturberegning:

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

Parametre

API'en accepterer alle parametre både i QUERY_STRING og i kroppen af POST-anmodningen.

Booleske variabler

API'en forventer at få '0' eller '1' i Booleske variabler, men på grund af implicit typekonvertering vil enhver tekststreng blive behandlet som en '1', selv ordet 'false'. Derfor, for eksplicit at sætte en 'FALSE'-værdi for en Boolesk variabel, skal du give den enten værdien '0' eller en tom streng.

Decimaltegn

Kun decimalpunktet bruges som decimalseparator i tal.

Tegn i parametre

Med få undtagelser er alle parametre store-/småbogstavsfølsomme.

Tilbagekaldelses-URL

I administrationspanelet for AxtonPay, på siden med betalingsindstillinger, er det muligt at indstille butik-URL'er til at modtage server-til-server-notifikationer fra AxtonPay, samt URL'er til omdirigering af køberen efter fakturabetaling eller dens annullering, samt i tilfælde af en fejl.

Disse URL'er kan overskrives i fakturaoprettelsesanmodningen.

Metoder af AxtonPay API

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

Metode /api/v1/private/checkout/payment/create igangsætter oprettelsen af fakturaen.

Hvis metoden lykkes, returnerer den et link ('invoice_url'), som du skal sende kunden til for betaling.

Egne fakturaparametre:

• time (påkrævet) - POSIX timestamp (Unix time)
• amount (påkrævet) - beløb der skal betales (prisen på produktet eller tjenesten, som butikken ønsker at modtage)
• currency (påkrævet) - 3-bogstavs valutakode ifølge ISO 4217-alpha, ikke-følsom over for store og små bogstaver
• pms (påkrævet) - betalingsmetoder vist på fakturasiden. Hvis du vil tillade alle betalingsmetoder, er værdien 'all'; hvis du kun vil tillade nogle af dem, skal du liste deres kommaseparerede numeriske identifikatorer.
• pm - identifikator for den valgte betalingsmetode. Det er vigtigt, at hvis 'pm'-parameteren sendes, vil fakturaen blive oprettet i 'transparent tilstand', dvs. køberen vil ikke se fakturasiden, men vil gå direkte til betalingssystemet.
• extra_data - en associativ array, der indeholder yderligere data; disse data returneres til butikken i deres helhed
• shop_user_id - brugeridentifikator i butikken, den returneres til butikken i uændret form
• shop_payment_id - betalingsidentifikator i butikken, den returneres til butikken i uændret form
• shop_name - butiksnavn (vist på fakturasiden)
• shop_payment_desc - ordrebekrivelse (vist på fakturasiden)
• shop_payment_remark - dine noter om denne betaling (dette er et felt til eventuelle noter, du har om betalingen, som AxtonPay ikke videregiver nogen steder; det er kun synligt i listen over betalinger; det går ikke tilbage til butikken)
• valid_time - tidsintervallet, hvori fakturaen kan betales; i sekunder
• view_time - tidsinterval, hvor fakturaen er tilgængelig for visning via ekstern link; i sekunder; nedtælling starter efter 'valid_time' perioden slutter
• server_notification_method - metode til at sende server-server notifikationer om betalingsstatus til butikken; gyldige værdier: POST, GET

Nogle indstillinger for fakturaen er indstillet på kassesideindstillingerne. Men de værdier, der sendes i forespørgslen, vil have forrang over disse indstillinger.

Checkout-parametre, der kan overskrives for denne faktura:

• customer_success_url - et link, som køberen vil blive omdirigeret til, hvis fakturaen er betalt succesfuldt (dvs. hvis fakturaens status er 'paid' eller 'overpaid').
• customer_cancel_url - et link, som køberen vil blive omdirigeret til, hvis betalingen annulleres
• customer_fail_url - et link, som køberen vil blive omdirigeret til, hvis betalingen ender i en fejl
• server_notification_url - link til at sende server-server notifikationer om betalingsstatusser til butikken

Bemærk: For at overholde din egen privatlivspolitik er det normalt ikke nødvendigt at inkludere dine kunders personlige oplysninger i fakturaegenskaberne. For eksempel er det i "shop_user_id"-parameteren bedre at angive et abstrakt kunde-ID i stedet for deres e-mail eller telefonnummer. Også i "shop_payment_desc" er det bedre slet ikke at inkludere kundedata, da de allerede kender alt om sig selv; i stedet kan du skrive nogle oplysninger om de betalte varer eller tjenester, eller endda bare skrive typen af handling, for eksempel "Køb" eller "Saldoopfyldning".

Alle referencer overføres nødvendigvis med protokollen.

Eksempel på anmodning:

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

Eksempel på et vellykket svar ved anmodning om oprettelse af 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"
}

Hentning af fakturainformation: /api/v1/private/checkout/payment/get/{PID}

For at få de oplysninger, du har brug for, skal du kalde metoden /api/v1/private/checkout/payment/get/{PID} ved at angive fakturaens PID i slutningen af URL'en.

Forespørgselsparametre:

• time (påkrævet) - POSIX timestamp (Unix time)

Eksempel på en linje til at komponere en signatur:

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

// String for signature calculation: 
time=1766837343

Eksempel på et 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"
    }
}

Sammenligning af anmodet beløb og udbetalt beløb

Svaret indeholder flere forskellige beløb (i den valuta, som fakturaen blev udstedt i):

• "amount" - faktureret beløb,
• "filled" - betalte en del af fakturaen,
• "total_filled" - hvor meget klienten betalte i alt, inklusive provisioner.

Hvis "filled = amount", så betales det præcis så meget, som det skal.

Hvis "filled > amount", er der en overbetaling.

Hvis "filled < amount", har fakturaen ikke været betalt fuldt ud (underbetaling).

Faktura: behandling af meddelelse fra AxtonPay om statusændring

Hver gang status for en faktura ændres, sender AxtonPay en notifikation til server_notification_url (ved hjælp af server_notification_method)

Eksempeldata:

{
    "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å denne meddelelse forventer AxtonPay at modtage HTTP code 200, som bekræfter dens vellykkede modtagelse. Ellers vil AxtonPay prøve igen 12 gange mere med gradvist stigende intervaller, og derefter ændres meddelelsens status til 'error' (men dette påvirker ikke fakturaens status i sig selv).

Mulige statusværdier:

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

Succesfulde betalingsstatusser er 1 (paid) og 5 (overpaid); i tilfælde af modtagelsen heraf kan du overføre det betalte køb til kunden eller påfylde saldoen. For betalinger med status 5 (overpaid), i tilfælde af saldoopfyldning kan du påfylde saldoen med det faktisk modtagne betalingsbeløb, men i tilfælde af salg af varer/tjenester og et væsentligt beløb af overbetaling anbefales det at kontakte betaleren og aftale med ham, hvordan man håndterer overbetalingen.

Delvist succesfuld status er 4 (underpaid); i tilfælde af at modtage denne status er det muligt at genoplade saldoen med det faktisk modtagne beløb. Denne status kan dog ikke betragtes som succesfuld for salg af varer/tjenester.

Alle andre statusser - 0 (pending), 2 (error), 3 (canceled by customer) betyder fuldstændig manglende betaling; i tilfælde af deres modtagelse bør der ikke udføres handlinger vedrørende saldoopfyldelse eller salg af varer/tjenester.

Signaturkontrol

For at være sikker på, at notifikationen sendes af AxtonPay nøjagtigt, er det nødvendigt at verificere signaturen af den modtagne notifikation, før man stoler på den. Verifikationen ligner at signere dine egne forespørgsler, kun det sidste trin er tilføjet, hvor du skal sammenligne den beregnede signatur med den modtagne HTTP-header 'Sign'.

De vigtigste trin efter modtagelse af meddelelse om den ændrede betalingsstatus er følgende:

• tag hele rækken af argumenter (QUERY_STRING) fra den modtagne meddelelse,
• tag hele POST data (REQUEST_BODY) fra den modtagne meddelelse,
• beregn signaturen ved hjælp af disse QUERY_STRING + REQUEST_BODY og den passende 'Secret key',
• sammenlign den beregnede signatur med den, der modtages i HTTP-headeren 'Sign',
• hvis underskrifterne er de samme, kom meddelelsen virkelig fra AxtonPay;
• Hvis underskrifterne er forskellige, kan det være et forsøg på at snyde fra betalerens side.

Eksempel på en linje til 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å, at butikken har behandlet betalingsinformationen: /api/v1/private/checkout/payment/confirm/{PID}

Denne anmodning sendes til AxtonPay som svar på en meddelelse modtaget fra den. Funktionelt set er det en bekræftelse på, at butikken har modtaget og behandlet den modtagne meddelelse korrekt.

For at sende en anmodning skal du kalde metoden /api/v1/private/checkout/payment/confirm/{PID} ved at angive fakturaens pid i slutningen af URL’en.

Forespørgselsparametre:

• time (påkrævet) - POSIX timestamp (Unix time)
• status (påkrævet, heltal) - betalingsstatusnummer, som butikken sender bekræftelse for

Hvis den overførte status matcher den aktuelle status for denne faktura i systemet, vil AxtonPay svare med 'OK', og hvis den ikke matcher, vil det svare med en fejl.

Eksempel på en linje til 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"}

Eksempel på et svar, hvis den nuværende betalingsstatus er den samme:

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

Eksempel på et svar, hvis den aktuelle betalingsstatus adskiller sig fra den, der blev sendt i anmodningen:

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

Valutakoder

De valutaer, der kan bruges til oprettelse af en faktura.

De fleste af de anvendte valutakoder tilhører fiat-valutaer, og de er lig med ISO 4217. Listen indeholder også flere kryptovalutaer.