AxtonPay API

Vanlig informasjon

API-endepunkt

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

Content-type

API aksepterer HTTP forespørsler med 2 innholdstyper: 'application/x-www-form-urlencoded', 'application/json'.

HTTP overskriften bør passe til innholdet i POST kroppen.

Forkortelser og definisjoner

• {PID} - ID-en til fakturaen, vanligvis er det den unike 8-tegns alfanumeriske sekvensen.
• Shop - Nettstedet ditt som aksepterer betalinger gjennom AxtonPay-tjenesten

Algoritme for arbeid med API

Vanlig rekkefølge av handlinger for å motta betaling:

• opprett en faktura ('/api/v1/private/checkout/payment/create'), API-responsen vil returnere faktura-URLen ('invoice_url'),
• send kjøperen til denne fakturaen for å foreta betaling,
• vent på AxtonPay servervarsler, som vil komme til 'server_notification_url',
• ved mottak av enhver melding fra AxtonPay, sjekk gyldigheten av signaturen og send helst en bekreftelse på mottak til AxtonPay ('/api/v1/private/checkout/payment/confirm/{PID}'),
• hvis statusen til en faktura endres, utfør handlinger som tilsvarer denne statusen (f.eks. be om full informasjon om fakturaen, sende varene, opprette en sak til supportteamet, osv.).

Hvis du setter en tom eller ugyldig 'server_notification_url' når du oppretter en faktura, kan ikke tjenesten sende varsler om statusendringer; i slike tilfeller bør du sjekke fakturaen selv med jevne mellomrom ('/api/v1/private/checkout/payment/get/{PID}').

Godkjenning av forespørsler

For å autorisere en forespørsel er det nødvendig å beregne en hash fra en streng som er dannet på en spesiell måte. Strengen settes sammen ved å sette sammen (lime sammen) URL-argumentene (QUERY_STRING) og kroppen til POST-forespørselen (REQUEST_BODY). Det er viktig at alle komponentene tas nøyaktig i den formen de vil bli sendt til serveren. URL-argumentene (QUERY_STRING) skal tas fra URL-en som én enkelt linje, uten å endre rekkefølgen på argumentene og uten å utelate noen elementer. POST-forespørselskroppen (REQUEST_BODY) skal også brukes uten noen modifikasjoner, inkludert at man ikke fjerner anførselstegn, mellomrom, klammeparenteser eller linjeskift.

I tilfeller med en tom POST forespørselskropp, og i tilfelle med tomme URL-argumenter, vil den komponenten ganske enkelt være en tom streng.

Sekvensen av data i signeringsforespørselen: QUERY_STRING først, deretter POST data. Du bør ikke sette inn noen koblingstegn mellom dem, bare sett sammen de to tekststrengene.

Nok en gang, hvert symbol er betydningsfullt. Du bør ikke legge til eller fjerne selv et mellomrom eller linjeskift. Bruk bare de rådataene som er mottatt av serveren.

En SHA-256 hash med nøkkelen 'Secret key' tas fra den resulterende strengen og brukes som det andre argumentet til funksjonen hash_hmac().

Det er obligatorisk å sende parameteren 'time' som inneholder den nåværende POSIX timestamp (Unix time).

Denne signaturen er gyldig i 24 timer. Hvis verdien av 'time'-parameteren avviker fra gjeldende servertid med mer enn 24 timer (enten fremover eller bakover), vil forespørselen mislykkes selv om signaturen beregnes uten feil.

Hvis handelsmannspanelet har akseptert en forespørsel med en eller annen signatur, kan ikke den signaturen brukes igjen, selv ikke for å sende forespørselen med de samme parameterne (dette inkluderer parameter 'time').

Den resulterende hashen sendes i HTTP-headeren 'Sign'.

I tillegg til den beregnede signaturen, må forespørselen også inneholde en 'Api-Key'-overskrift som inneholder den brukte API-nøkkelen. Eksempel:

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

Du kan signere forespørselen sendt til AxtonPay med hvilken som helst gyldig nøkkel som tilhører denne kassen. Imidlertid bruker AxtonPay alltid nøkkelen som du har valgt i merchant-panelet.

Eksempel på signaturberegning:

/* 
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 oppmerksom på mellomrom og linjeskift i et annet 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"
}' 
*/

Python eksempelet på å komponere strengen for signaturberegning:

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

Parametere

API-en aksepterer alle parametere både i QUERY_STRING og i kroppen av POST forespørselen.

Boolske variabler

APIen forventer å få '0' eller '1' i Boolske variabler, men på grunn av implisitt typekonvertering vil enhver tekststreng bli behandlet som en '1', selv ordet 'false'. Derfor, for å eksplisitt sette en 'FALSE'-verdi for en Boolsk variabel, må du sende til den enten verdien '0' eller en tom streng.

Desimalskille

Bare desimalpunktet brukes som desimalskille i tall.

Tegnsett i parametere

Med noen få unntak er alle parametere små- og storbokstav-sensitive.

Tilbakeropps-URL

I administrasjonspanelet til AxtonPay, på siden for utsjekkingsinnstillinger, er det mulig å sette butikk-URLer for å motta server-server-varsler fra AxtonPay, samt URLer for å omdirigere kjøperen etter fakturabetaling eller kansellering, samt i tilfelle en feil.

Disse URL-ene kan overstyres i forespørselen om opprettelse av faktura.

Metoder for AxtonPay API

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

Metode /api/v1/private/checkout/payment/create starter opprettelsen av fakturaen.

Hvis vellykket, returnerer metoden en lenke ('invoice_url') som du bør sende kunden til for betaling.

Egne fakturaparametere:

• time (påkrevd) - POSIX timestamp (Unix time)
• amount (påkrevd) - beløp som skal betales (prisen på produktet eller tjenesten butikken ønsker å motta)
• currency (påkrevd) - 3-bokstavers valutakode i henhold til ISO 4217-alpha, ikke små-/storebokstavfølsom
• pms (påkrevd) - betalingsmetoder vist på fakturasiden. Hvis du vil tillate alle betalingsmetoder, er verdien 'all'; hvis du vil tillate bare noen av dem, oppgi deres komma-separerte numeriske identifikatorer.
• pm - identifikator for den valgte betalingsmetoden. Det er viktig at hvis 'pm'-parameteren sendes, vil fakturaen bli opprettet i 'transparent modus', dvs. at kjøperen ikke vil se fakturasiden, men gå direkte til betalingssystemet.
• extra_data - en assosiativ matrise som inneholder eventuelle tilleggsdata; disse dataene returneres til butikken i sin helhet
• shop_user_id - brukeridentifikator i butikken, den returneres til butikken i uendret form
• shop_payment_id - betalingsidentifikator i butikken, den returneres til butikken i uendret form
• shop_name - butikknavn (vist på fakturasiden)
• shop_payment_desc - ordrebeskrivelse (vist på fakturasiden)
• shop_payment_remark - dine notater om denne betalingen (dette er et felt for eventuelle notater du har om betalingen, som AxtonPay ikke sender videre noe sted; det er kun synlig i listen over betalinger; det går ikke tilbake til butikken)
• valid_time - tidsintervallet hvor fakturaen kan betales; i sekunder
• view_time - tidsintervall hvor fakturaen er tilgjengelig for visning via ekstern lenke; i sekunder; nedtelling starter etter at 'valid_time' perioden er over
• server_notification_method - metode for å sende server-til-server-varsler om betalingsstatus til butikken; gyldige verdier: POST, GET

Noen innstillinger for fakturaen er satt på siden for kasseinnstillinger. Men verdiene som sendes i forespørselen vil ha forrang over disse innstillingene.

Betalingsparametere som kan overskrives for denne fakturaen:

• customer_success_url - en lenke som kjøperen vil bli omdirigert til hvis fakturaen blir betalt (dvs. hvis fakturastatusen er 'paid' eller 'overpaid').
• customer_cancel_url - en lenke som kjøperen vil bli videresendt til dersom betalingen avbrytes
• customer_fail_url - en lenke som kjøperen vil bli omdirigert til hvis betalingen ender i en feil
• server_notification_url - lenke for å sende server-server-varsler om betalingsstatus til butikken

Merk: For å overholde din egen personvernpolicy, er det vanligvis ikke nødvendig å inkludere kundens personlige data i fakturaegenskapene. For eksempel, i "shop_user_id"-parameteren er det bedre å spesifisere en abstrakt kunde-ID i stedet for deres e-post eller telefonnummer. Også i "shop_payment_desc" er det bedre å ikke inkludere kundedata i det hele tatt, fordi de allerede vet alt om seg selv; i stedet kan du skrive noe informasjon om de betalte varene eller tjenestene, eller til og med bare skrive type handling, for eksempel "Kjøp" eller "Saldo påfyll".

Alle referanser overføres nødvendigvis med protokollen.

Eksempel på forespørsel:

<?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 når man ber om opprettelse 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"
}

Henter fakturainformasjon: /api/v1/private/checkout/payment/get/{PID}

For å få informasjonen du trenger, kall metoden /api/v1/private/checkout/payment/get/{PID} ved å spesifisere PID til fakturaen på slutten av URL-en.

Forespørselsparametere:

• time (påkrevd) - POSIX timestamp (Unix time)

Eksempel på en linje for å 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 av forespurt beløp og utbetalt beløp

Svaret inneholder flere forskjellige beløp (i valutaen fakturaen ble utstedt i):

• "amount" - fakturert beløp,
• "filled" - betalte en del av fakturaen,
• "total_filled" - hvor mye klienten betalte totalt, inkludert provisjoner.

Hvis "filled = amount", da betales det akkurat så mye som det trenger å være.

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

Hvis "filled < amount", har fakturaen ikke blitt betalt i sin helhet (underbetaling).

Faktura: behandling av melding fra AxtonPay om statusendring

Hver gang statusen til en faktura endres, sender AxtonPay en melding til server_notification_url (ved bruk av 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 varslingen forventer AxtonPay å motta HTTP code 200, som bekrefter at den er mottatt. Ellers vil AxtonPay prøve 12 ganger til med gradvis økende intervaller, og deretter endres varslingsstatusen til 'error' (men dette påvirker ikke statusen til selve fakturaen).

Mulige statusverdier:

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

Vellykkede betalingsstatus er 1 (paid) og 5 (overpaid); ved mottak av disse kan du overføre det betalte kjøpet til kunden eller fylle på saldoen. For betalinger med status 5 (overpaid), ved påfylling av saldo kan du fylle på saldoen med beløpet av den faktisk mottatte betalingen, men ved salg av varer/tjenester og et betydelig beløp av overbetaling anbefales det å kontakte betaleren og bli enige med ham om hvordan man skal håndtere overbetalingen.

Delvis vellykket status er 4 (underpaid); i tilfelle man mottar denne statusen, er det mulig å fylle på saldoen med beløpet som faktisk er mottatt betaling. Denne statusen kan imidlertid ikke betraktes som vellykket for salg av varer/tjenester.

Alle andre status - 0 (pending), 2 (error), 3 (canceled by customer) betyr fullstendig fravær av betaling; ved mottak av disse skal ingen handlinger på saldoopplading eller salg av varer/tjenester utføres.

Signatursjekking

For å være sikker på at varslingen er sendt av AxtonPay, er det nødvendig å verifisere signaturen til den mottatte varslingen før man stoler på den. Verifiseringen ligner på å signere dine egne forespørsler, bare at det siste trinnet er lagt til, der du skal sammenligne den beregnede signaturen med den mottatte HTTP-headeren 'Sign'.

Hovedtrinnene etter å ha mottatt varsel om endret betalingsstatus er som følger:

• ta hele streng av argumenter (QUERY_STRING) fra den mottatte varslingen,
• ta hele POST data (REQUEST_BODY) fra den mottatte meldingen,
• beregn signaturen ved å bruke de der QUERY_STRING + REQUEST_BODY og den passende 'Secret key',
• sammenlign beregnet signatur med den som mottas i HTTP-headeren 'Sign',
• hvis signaturene er de samme, kom varslingen virkelig fra AxtonPay;
• Hvis signaturene er forskjellige, kan det være et forsøk på å jukse fra betalerens side.

Eksempel på en linje for 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

Bekreftelse på at butikken har behandlet betalingsinformasjonen: /api/v1/private/checkout/payment/confirm/{PID}

Denne forespørselen sendes til AxtonPay som svar på en melding mottatt fra den. Funksjonelt er det en bekreftelse på at butikken har mottatt og behandlet den mottatte meldingen.

For å sende en forespørsel, kall metoden /api/v1/private/checkout/payment/confirm/{PID}, ved å spesifisere pid-en til fakturaen på slutten av URL-en.

Forespørselsparametere:

• time (påkrevd) - POSIX timestamp (Unix time)
• status (påkrevd, heltall) - betalingsstatusnummer som butikken sender bekreftelse for

Hvis den overførte statusen samsvarer med den nåværende statusen for denne fakturaen i systemet, vil AxtonPay svare med 'OK', og hvis den ikke samsvarer, vil den svare med en feil.

Eksempel på en linje for 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 nåværende betalingsstatusen er den samme:

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

Eksempel på et svar hvis den nåværende betalingsstatusen skiller seg fra den som ble sendt i forespørselen:

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

Valutakoder

Valutaene som kan brukes for opprettelse av en faktura.

De fleste brukte valutakoder tilhører fiat-valutaer, og de er lik ISO 4217. Listen inneholder også flere kryptovalutaer.