AxtonPay API

عام معلومات

اے پی آئی اینڈ پوائنٹ

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

Content-type

API دو قسم کے مواد کے ساتھ HTTP درخواستیں قبول کرتی ہے: '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}') پر خود انوائس چیک کرنی چاہیے۔

درخواستوں کی منظوری

کسی درخواست کو منظوری دینے کے لیے ضروری ہے کہ ایک خاص طریقے سے بنائی گئی سٹرنگ سے ہیش نکالا جائے۔ سٹرنگ بنانے کے لیے URL کے دلائل (QUERY_STRING) اور POST درخواست کے باڈی (REQUEST_BODY) کو آپس میں جوڑا جاتا ہے (چپکا دیا جاتا ہے)۔ یہ اہم ہے کہ تمام اجزاء بالکل اسی فارم میں لیے جائیں جیسا کہ وہ سرور کو بھیجے جائیں گے۔ URL کے دلائل (QUERY_STRING) URL سے ایک ہی لائن میں لیے جائیں، بغیر دلائل کے ترتیب کو بدلے اور بغیر کسی عنصر کو چھوڑے۔ POST درخواست کے باڈی (REQUEST_BODY) کو بھی بغیر کسی تبدیلی کے استعمال کرنا چاہیے، جس میں اس سے اقتباسات، خالی جگہیں، بریکٹ، لائن بریک نکالنا شامل نہیں ہے۔

خالی POST درخواست کے جسم کی صورت میں، اور خالی URL دلائل کی صورت میں، وہ جزو بس خالی سٹرنگ ہوگا۔

سائننگ ریکویسٹ میں ڈیٹا کی ترتیب: QUERY_STRING پہلے، پھر POST ڈیٹا۔ آپ کو ان کے درمیان کوئی کنیکٹنگ نشان شامل نہیں کرنا چاہیے، بس دو ٹیکسٹ سٹرنگز کو ملا دیں۔

ایک بار پھر، ہر علامت اہم ہے۔ آپ کو ایک سفید جگہ یا نئی لائن کے علامت کو بھی شامل یا حذف نہیں کرنا چاہیے۔ صرف سرور سے موصول ہونے والے خام ڈیٹا کا استعمال کریں۔

ایک SHA-256 ہیش کلید 'Secret key' کے ساتھ حاصل شدہ سلسلے سے لیا گیا ہے اور فنکشن hash_hmac() کے دوسرے دلیل کے طور پر استعمال کیا جاتا ہے۔

یہ لازمی ہے کہ موجودہ POSIX timestamp (Unix time) کو شامل کرنے والا 'time' پیرامیٹر پاس کیا جائے۔

یہ دستخط 24 گھنٹے کے لیے درست ہے۔ اگر 'time' پیرامیٹر کی قیمت موجودہ سرور کے وقت سے 24 گھنٹے سے زیادہ مختلف ہے (چاہے آگے ہو یا پیچھے)، تو درخواست ناکام ہو جائے گی چاہے دستخط بغیر کسی غلطی کے بھی حساب کیا گیا ہو۔

اگر مرچنٹ پینل نے کسی دستخط کے ساتھ درخواست قبول کی ہے تو وہ دستخط دوبارہ استعمال نہیں کیا جا سکتا، حتیٰ کہ اسی پیرامیٹرز کے ساتھ درخواست بھیجنے کے لیے بھی (اس میں پیرامیٹر 'time' شامل ہے)۔

حاصل شدہ ہیش 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 درخواست کے باڈی میں قبول کرتا ہے۔

بولین متغیرات

API توقع کرتا ہے کہ Boolean متغیرات میں '0' یا '1' حاصل کریں، لیکن ضمنی قسم کے تبدیلی کی وجہ سے، کوئی بھی متن کا سلسلہ '1' کے طور پر سمجھا جائے گا، حتی کہ لفظ 'false' بھی۔ لہٰذا، Boolean متغیر کے لیے واضح طور پر 'FALSE' ویلیو مقرر کرنے کے لیے، آپ کو اسے یا تو '0' کی ویلیو یا خالی سلسلہ دینا ہوگا۔

اعشاریہ جدا کنندہ

اعشاری اعداد میں اعشاریہ کے طور پر صرف اعشاری نقطہ استعمال ہوتا ہے۔

پیرامیٹرز میں حرف کی صورت

چند استثناؤں کے ساتھ، تمام پیرامیٹرز کیس سینسیٹو ہیں۔

کال بیک یو آر ایل

AxtonPay کے ایڈمن پینل میں، چیک آؤٹ سیٹنگز کے صفحے پر، یہ ممکن ہے کہ اسٹور URLs مقرر کی جائیں تاکہ AxtonPay سے سرور-سرور نوٹیفیکیشن وصول کی جا سکیں، نیز URLs بھی مقرر کی جا سکتی ہیں تاکہ خریدار کو انوائس کی ادائیگی یا اس کی منسوخی کے بعد ری ڈائریکٹ کیا جا سکے، اور اس کے علاوہ کسی غلطی کی صورت میں بھی۔

ان یو آر ایل کو انوائس بنانے کی درخواست میں اووررائیڈ کیا جا سکتا ہے۔

AxtonPay API کے طریقے

انوائس کی تخلیق: /api/v1/private/checkout/payment/create

طریقہ /api/v1/private/checkout/payment/create انوائس کی تخلیق شروع کرتا ہے۔

اگر کامیاب ہو جائے، تو طریقہ ایک لنک ('invoice_url') واپس کرتا ہے جس پر آپ کو صارف کو ادائیگی کے لیے بھیجنا چاہیے۔

اپنے انوائس کے پیرامیٹرز:

• time (ضروری) - POSIX timestamp (Unix time)
• amount (ضروری) - ادا کی جانے والی رقم (پروڈکٹ یا سروس کی قیمت جو اسٹور وصول کرنا چاہتا ہے)
• currency (ضروری) - ISO 4217-alpha کے مطابق 3 حرفی کرنسی کوڈ، حروف کی چھوٹی یا بڑی صورت سے بے نیاز
• 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" پیرامیٹر میں، ان کے ای میل یا فون نمبر کے بجائے ایک خلاصہ گاہک کا آئی ڈی درج کرنا بہتر ہے۔ اسی طرح "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} طریقہ کو کال کریں، URL کے آخر میں انوائس کا PID بتا کر۔

درخواست کے پیرامیٹرز:

• 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} طریقہ کار کو کال کریں، URL کے آخر میں انوائس کا pid بتا کر۔

درخواست کے پیرا میٹر:

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

کرنسی کوڈز

وہ کرنسیاں جو انوائس بنانے کے لیے استعمال کی جا سکتی ہیں۔

زیادہ تر استعمال شدہ کرنسی کوڈز فیاٹ کرنسیوں سے تعلق رکھتے ہیں، اور وہ ISO 4217 کے برابر ہیں۔ اس فہرست میں کچھ کریپٹو کرنسیاں بھی شامل ہیں۔