مستندات تترا
پرداخت کالابرگ

پرداخت کالابرگ

رابط مستقیم با سامانهٔ بالادست کالابرگ برای خرید کالابرگ کارتی

مقدمه

در جریان خرید کالابرگ کارتی، کسب‌وکار اطلاعات تراکنش بانکی (RRN، STAN، کد ملی رمزشده) را به همراه اقلام سفارش مستقیماً به سامانهٔ بالادست کالابرگ می‌فرستد. پاکت پاسخ این سرویس با پاکت استاندارد گیت‌وی تترا فرق دارد — خروجی عیناً همان چیزی است که سامانهٔ بالادست برمی‌گرداند.

توجه:

برای خرید با رمز یک‌بارمصرف (OTP) به مستندات پرداخت کالابرگ با رمز مراجعه کنید.

هشدار:

فیلد nationalCode باید به‌صورت رمزشده (ciphertext) ارسال شود — کد ملی خام به هیچ وجه پذیرفته نمی‌شود.

هشدار:

این سرویس هدر Idempotency-Key نمی‌خواهد و هیچ محافظ تکراری ندارد. ارسال دوبارهٔ یک درخواست خرید، سفارش را دوباره ثبت می‌کند.

    1. احراز هویت (authenticate)
      توکن کوتاه‌مدت کالابرگ را می‌گیرید و در هدر Authorization همهٔ درخواست‌های بعدی قرار می‌دهید. توکن ۲۴ ساعت اعتبار دارد و با غیرفعال‌شدن یا تغییر کلید API باطل می‌شود.
      text
      POST /api/Authentication/authenticate
      
    2. ثبت خرید (item-order)
      اطلاعات کارت (RRN، STAN)، کد ملی رمزشده و اقلام سفارش را می‌فرستید. اعتبار خریدار همان لحظه کسر می‌شود. پاسخ orderTrace می‌دهد — بلافاصله ذخیره کنید؛ بدون آن هیچ مرحلهٔ بعدی ممکن نیست.
      text
      POST /inquiry/itemorder
      
    3. استعلام سفارش (purchase-inquiry)
      وضعیت سفارش را می‌پرسید و هیچ تغییری در سیستم ایجاد نمی‌شود. این مرحله اجباری است — پیش از تأیید نهایی باید اطمینان حاصل شود سفارش در وضعیت درست است. اگر تصمیم به ادامه ندارید، مراحل ۵ یا ۶ را ببینید.
      text
      POST /inquiry/purchaseinquiry
      
    4. تأیید نهایی (confirm-order)
      تراکنش را قطعی می‌کنید. پس از این مرحله، برگشت از طریق API غیرممکن است.
      text
      POST /payment/confirmorder
      
    5. برگشت (reverse-order)
      اگر به هر دلیلی confirm-order انجام نشد، این سرویس اجباری است. برخلاف لغو، هیچ آزادسازی خودکاری وجود ندارد — بدون این فراخوانی، اعتبار خریدار به حسابش برنمی‌گردد.
      text
      POST /payment/reverseorder
      
    6. لغو (order-cancelation)
      پس از item-order و پیش از confirm-order، در صورت انصراف مشتری یا خطای داخلی. اگر صدا نزنید، اعتبار حدود ۲ دقیقه بعد خودبه‌خود آزاد می‌شود — اما برای تجربهٔ بهتر خریدار همیشه صدایش بزنید.
      text
      POST /payment/ordercancelation
      

ساختار کلی API

  • Base URL: https://back.tetra.land
  • پیشوند مسیر: payment
  • احراز هویت: برخی درخواست‌ها بدون نیاز به توکن و برخی نیازمند هدر Authorization: Bearer {sfara_token} — به بخش هر endpoint مراجعه کنید
  • فرمت درخواست: application/json
  • فرمت پاسخ: application/json
  • ساختار پاسخ‌ها:
    • ساختار دقیق پاسخ‌ها را از نمونه‌های زیر استخراج کنید

۱. احراز هویت (authenticate)

Endpoint

text
POST {{base_url}}/api/Authentication/authenticate

مثال:

text
POST https://back.tetra.land/api/Authentication/authenticate

Headers

کلیدمقدار
Acceptapplication/json
Content-Typeapplication/json

Body

پارامترنوعالزامیتوضیح
usernamestringبلهکلید API که از پنل خود دریافت کرده‌اید
passwordstringبلهکلید محرمانهٔ همان کلید API

نمونه درخواست:

json
{
  "username": "xxxx",
  "password": "xxxx"
}

نمونه کد

php
<?php
$payload = json_encode([
    'username' => 'xxxx',
    'password' => 'xxxx',
]);

$ch = curl_init('https://back.tetra.land/api/Authentication/authenticate');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $payload);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Accept: application/json',
    'Content-Type: application/json',
]);

$response = curl_exec($ch);
curl_close($ch);

$data = json_decode($response, true);
print_r($data);

امتحان کنید

POST/api/Authentication/authenticateامتحان کنید
username*
password*
نمایش JSON ارسالی
{
  "username": "xxxx",
  "password": "xxxx"
}

پارامترهای پاسخ

پارامترنوعنمونه مقدارتوضیح
jwtTokenstring-توکن دسترسی، در result.data قرار دارد
idstring-شناسهٔ کلید API
usernamestring-همان کلید API
firstnamestring-نام دارندهٔ کسب‌وکار
lastnamestring-نام خانوادگی دارندهٔ کسب‌وکار
isActiveboolean-فعال بودن کلید API
هشدار:

توکن ۲۴ ساعت اعتبار دارد. اگر کلید محرمانه را عوض کنید یا کلید را غیرفعال کنید، تمام توکن‌های صادرشده بلافاصله باطل می‌شوند و باید دوباره احراز هویت کنید.

پاسخ‌ها

json
{
  "message": "POST Request successful.",
  "statusCode": 200,
  "result": {
    "status": true,
    "responseCode": 0,
    "data": {
      "id": 1,
      "firstname": "Kala",
      "lastname": "Kala",
      "username": "YOUR_API_KEY",
      "jwtToken": "YOUR_SFARA_TOKEN",
      "isActive": true
    }
  },
  "isError": false
}

۲. ثبت خرید (item-order)

Endpoint

text
POST {{base_url}}/inquiry/itemorder

مثال:

text
POST https://back.tetra.land/inquiry/itemorder

Headers

کلیدمقدار
Acceptapplication/json
AuthorizationBearer {sfara_token}
Content-Typeapplication/json

Body

پارامترنوعالزامیتوضیح
rrnstringبلهشمارهٔ مرجع تراکنش بانکی
stanstringبلهشمارهٔ پیگیری ترمینال
nationalCodestringبلهکد ملی خریدار، از قبل رمزنگاری‌شده توسط کارت‌خوان
cardNumberstringخیرشمارهٔ کارت به‌صورت ماسک‌دار
terminalNumberstringبلهترمینالی که خرید روی آن انجام می‌شود؛ باید لایسنسِ معتبر داشته باشد
channelTypestringبله"2" — پرداخت کارتی
requestDateintegerبلهتاریخ و ساعت شمسی به شکل YYYYMMDDHHmmss
amountintegerبلهمبلغ کل فاکتور به ریال
orderItemsarrayبلهاقلام سبد خرید

هر قلم در orderItems

پارامترنوعالزامیتوضیح
commodityCodestringبلهبارکد کالا
quantityintegerبلهتعداد واحد از این کالا
amountintegerبلهمبلغ این قلم به ریال
unitCodestringبلهرشته است نه عدد. مقادیر مشاهده‌شده «۱» و «۵»
هشدار:

مجموع amount اقلام باید دقیقاً با amount کل درخواست برابر باشد.

نمونه درخواست:

json
{
  "rrn": "123456789012",
  "stan": "123456",
  "nationalCode": "5Aud7J8/UpL4****w5W5p5Mwrh1CSM9rUs=",
  "terminalNumber": "TERM-XXXXXXXX",
  "channelType": "2",
  "requestDate": 14050628114746,
  "amount": 10000,
  "orderItems": [
    {
      "commodityCode": "6260371001295",
      "quantity": 1,
      "amount": 10000,
      "unitCode": "5"
    }
  ]
}

نمونه کد

php
<?php
$token = 'YOUR_SFARA_TOKEN';

$payload = json_encode([
    'rrn'           => '123456789012',
    'stan'          => '123456',
    'nationalCode'  => '5Aud7J8/UpL4****w5W5p5Mwrh1CSM9rUs=',
    'terminalNumber'=> 'TERM-XXXXXXXX',
    'channelType'   => '2',
    'requestDate'   => 14050628114746,
    'amount'        => 10000,
    'orderItems'    => [
        ['commodityCode' => '6260371001295', 'quantity' => 1, 'amount' => 10000, 'unitCode' => '5'],
    ],
]);

$ch = curl_init('https://back.tetra.land/inquiry/itemorder');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $payload);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Accept: application/json',
    'Content-Type: application/json',
    "Authorization: Bearer {$token}",
]);

$response = curl_exec($ch);
curl_close($ch);

$data = json_decode($response, true);
print_r($data);

امتحان کنید

POST/inquiry/itemorderامتحان کنید
rrn*
stan*
nationalCode*
cardNumber
terminalNumber*
channelType*
requestDate*
amount*
orderItems*
نمایش JSON ارسالی
{
  "rrn": "123456789012",
  "stan": "123456",
  "nationalCode": "5Aud7J8/UpL4****w5W5p5Mwrh1CSM9rUs=",
  "terminalNumber": "12345678",
  "channelType": "2",
  "requestDate": "14040205115507",
  "amount": "7000000",
  "orderItems": "{}"
}
هشدار:

گارد لایسنس: تنها شرطی که این میرور خودش بررسی می‌کند این است که برای همین terminalNumber یک لایسنسِ منقضی‌نشده وجود داشته باشد. مالکیت بی‌اثر است. اگر بیش از یک لایسنس با این شماره وجود داشته باشد، درخواست رد می‌شود.

پارامترهای پاسخ

فیلدنوعتوضیح
orderTracestringشناسهٔ سفارش؛ در سه متد بعدی لازم است
rrnstringشمارهٔ مرجع تراکنش بانکی
stanstringشمارهٔ پیگیری ترمینال
terminalNumberstringشمارهٔ ترمینال (ممکن است با ورودی متفاوت باشد)
amountintegerمبلغ کل
creditAmountintegerمبلغ اعتبار تخصیص‌یافته
balanceMarketTypeintegerنوع بازار — معنی مقادیرش نامعلوم است
orderItemsstringفهرست اقلام به‌صورت رشتهٔ قالب‌بندی‌شده (با `
assignedCreditsarrayریز اعتبار تخصیص‌یافته به هر قلم

پاسخ‌ها

json
{
  "message": "POST Request successful.",
  "statusCode": 200,
  "result": {
    "status": true,
    "responseCode": 0,
    "data": {
      "creditAmount": 6000000,
      "terminalNumber": "12355679",
      "amount": 7000000,
      "orderTrace": "1046300323242",
      "stan": "123456",
      "rrn": "100011002374",
      "balanceMarketType": 0,
      "assignedCredits": [
        {
          "commodityCode": "06265086100790",
          "quantity": 1,
          "amount": 3000000,
          "unitCode": "5",
          "assignedCredit": 3000000,
          "currentCredit": 0,
          "isBalanceMarket": 0
        },
        {
          "commodityCode": "6260719900013",
          "quantity": 1,
          "amount": 3000000,
          "unitCode": "5",
          "assignedCredit": 3000000,
          "currentCredit": 0,
          "isBalanceMarket": 0
        },
        {
          "commodityCode": "6260100500280",
          "quantity": 1,
          "amount": 1000000,
          "unitCode": "5",
          "assignedCredit": 0,
          "currentCredit": 0,
          "isBalanceMarket": 0
        }
      ]
    }
  },
  "isError": false
}

۳. استعلام سفارش (purchase-inquiry)

Endpoint

text
POST {{base_url}}/inquiry/purchaseinquiry

مثال:

text
POST https://back.tetra.land/inquiry/purchaseinquiry

Headers

کلیدمقدار
Acceptapplication/json
AuthorizationBearer {sfara_token}
Content-Typeapplication/json

Body

پارامترنوعالزامیتوضیح
orderTracestringبلهشناسهٔ سفارش که در پاسخ ثبت خرید برگشته بود
channelTypestringبله"2" — پرداخت کارتی
rrnstringبلهشمارهٔ مرجع تراکنش بانکی، همان مقدار ثبت خرید
stanstringبلهشمارهٔ پیگیری ترمینال، همان مقدار ثبت خرید
nationalCodestringبلهکد ملی خریدار، از قبل رمزنگاری‌شده توسط کارت‌خوان
cardNumberstringخیرشمارهٔ کارت به‌صورت ماسک‌دار
terminalNumberstringبلهترمینالی که خرید روی آن انجام شده؛ باید لایسنسِ معتبر داشته باشد
creditAmountintegerخیرمبلغ اعتباری که در پاسخ ثبت خرید برگشته بود
amountintegerبلهمبلغ کل فاکتور به ریال

نمونه درخواست:

json
{
  "orderTrace": "1046300323242",
  "channelType": "2",
  "rrn": "100011002374",
  "stan": "123456",
  "nationalCode": "5Aud7J8/UpL4****w5W5p5Mwrh1CSM9rUs=",
  "terminalNumber": "TERM-XXXXXXXX",
  "amount": 10000
}

🔴 این نُه فیلد همهٔ ورودی این متد است. orderItems و requestDate در این مرحله فرستاده نمی‌شوند.

هشدار:

گارد لایسنس: تنها شرطی که این میرور خودش بررسی می‌کند این است که برای همین terminalNumber یک لایسنسِ منقضی‌نشده وجود داشته باشد. مالکیت بی‌اثر است.

خروجی

فیلدنوعتوضیح
databooleanدر پاسخ موفق مقدار true است و جزئیات دیگری ندارد

نمونه کد

php
<?php
$token = 'YOUR_SFARA_TOKEN';

$payload = json_encode([
    'orderTrace'    => '1046300323242',
    'channelType'   => '2',
    'rrn'           => '100011002374',
    'stan'          => '123456',
    'nationalCode'  => '5Aud7J8/UpL4****w5W5p5Mwrh1CSM9rUs=',
    'terminalNumber'=> 'TERM-XXXXXXXX',
    'amount'        => 10000,
]);

$ch = curl_init('https://back.tetra.land/inquiry/purchaseinquiry');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $payload);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Accept: application/json',
    'Content-Type: application/json',
    "Authorization: Bearer {$token}",
]);

$response = curl_exec($ch);
curl_close($ch);

$data = json_decode($response, true);
print_r($data);

امتحان کنید

POST/inquiry/purchaseinquiryامتحان کنید
orderTrace*
channelType*
rrn*
stan*
nationalCode*
cardNumber
terminalNumber*
creditAmount
amount*
نمایش JSON ارسالی
{
  "orderTrace": "1046300323242",
  "channelType": "2",
  "rrn": "100011002374",
  "stan": "123456",
  "nationalCode": "5Aud7J8/UpL4****w5W5p5Mwrh1CSM9rUs=",
  "terminalNumber": "12355679",
  "amount": "7000000"
}

پارامترهای پاسخ

پارامترنوعنمونه مقدارتوضیح
datastring-در پاسخ موفق مقدار true است و جزئیات دیگری ندارد

پاسخ‌ها

json
{
  "message": "POST Request successful.",
  "statusCode": 200,
  "result": {
    "status": true,
    "responseCode": 0,
    "data": true
  },
  "isError": false
}

۴. تأیید نهایی (confirm-order)

Endpoint

text
POST {{base_url}}/payment/confirmorder

مثال:

text
POST https://back.tetra.land/payment/confirmorder

Headers

کلیدمقدار
Acceptapplication/json
AuthorizationBearer {sfara_token}
Content-Typeapplication/json

Body

پارامترنوعالزامیتوضیح
orderTracestringبلهشناسهٔ سفارش که در پاسخ ثبت خرید برگشته بود
channelTypestringبله"2" — پرداخت کارتی
rrnstringبلهشمارهٔ مرجع تراکنش بانکی، همان مقدار ثبت خرید
stanstringبلهشمارهٔ پیگیری ترمینال، همان مقدار ثبت خرید
nationalCodestringبلهکد ملی خریدار، از قبل رمزنگاری‌شده توسط کارت‌خوان
cardNumberstringخیرشمارهٔ کارت به‌صورت ماسک‌دار
terminalNumberstringبلهترمینالی که خرید روی آن انجام شده؛ در این مرحله لایسنسش بررسی نمی‌شود
creditAmountintegerخیرمبلغ اعتباری که در پاسخ ثبت خرید برگشته بود
amountintegerبلهمبلغ کل فاکتور به ریال

نمونه درخواست:

json
{
  "orderTrace": "1046300323242",
  "channelType": "2",
  "rrn": "100011002374",
  "stan": "123456",
  "nationalCode": "5Aud7J8/UpL4****w5W5p5Mwrh1CSM9rUs=",
  "terminalNumber": "TERM-XXXXXXXX",
  "amount": 10000
}

🔴 این نُه فیلد همهٔ ورودی این متد است. orderItems و requestDate در این مرحله فرستاده نمی‌شوند.

توجه:

گارد لایسنس روی این متد اعمال نمی‌شود. گارد فقط روی اولین اکشن چرخه (ثبت خرید) است. این متد ادامهٔ چرخه است و حتی با لایسنسِ منقضی‌شده هم کار می‌کند — پولی که جابه‌جا شده باید قابل تأیید باشد.

خروجی

فیلدنوعتوضیح
databooleanدر پاسخ موفق مقدار true است و جزئیات دیگری ندارد

نمونه کد

php
<?php
$token = 'YOUR_SFARA_TOKEN';

$payload = json_encode([
    'orderTrace'    => '1046300323242',
    'channelType'   => '2',
    'rrn'           => '100011002374',
    'stan'          => '123456',
    'nationalCode'  => '5Aud7J8/UpL4****w5W5p5Mwrh1CSM9rUs=',
    'terminalNumber'=> 'TERM-XXXXXXXX',
    'amount'        => 10000,
]);

$ch = curl_init('https://back.tetra.land/payment/confirmorder');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $payload);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Accept: application/json',
    'Content-Type: application/json',
    "Authorization: Bearer {$token}",
]);

$response = curl_exec($ch);
curl_close($ch);

$data = json_decode($response, true);
print_r($data);

امتحان کنید

POST/payment/confirmorderامتحان کنید
orderTrace*
channelType*
rrn*
stan*
nationalCode*
cardNumber
terminalNumber*
creditAmount
amount*
نمایش JSON ارسالی
{
  "orderTrace": "1046300323242",
  "channelType": "2",
  "rrn": "100011002374",
  "stan": "123456",
  "nationalCode": "5Aud7J8/UpL4****w5W5p5Mwrh1CSM9rUs=",
  "terminalNumber": "12355679",
  "amount": "7000000"
}

پارامترهای پاسخ

پارامترنوعنمونه مقدارتوضیح
datastring-در پاسخ موفق مقدار true است و جزئیات دیگری ندارد

پاسخ‌ها

json
{
  "message": "POST Request successful.",
  "statusCode": 200,
  "result": {
    "status": true,
    "responseCode": 0,
    "data": true
  },
  "isError": false
}

۵. برگشت خرید (reverse-order)

Endpoint

text
POST {{base_url}}/payment/reverseorder

مثال:

text
POST https://back.tetra.land/payment/reverseorder

Headers

کلیدمقدار
Acceptapplication/json
AuthorizationBearer {sfara_token}
Content-Typeapplication/json

Body

پارامترنوعالزامیتوضیح
orderTracestringبلهشناسهٔ سفارش که در پاسخ ثبت خرید برگشته بود
channelTypestringبله"2" — پرداخت کارتی
rrnstringبلهشمارهٔ مرجع تراکنش بانکی، همان مقدار ثبت خرید
stanstringبلهشمارهٔ پیگیری ترمینال، همان مقدار ثبت خرید
nationalCodestringبلهکد ملی خریدار، از قبل رمزنگاری‌شده توسط کارت‌خوان
cardNumberstringخیرشمارهٔ کارت به‌صورت ماسک‌دار
terminalNumberstringبلهترمینالی که خرید روی آن انجام شده؛ در این مرحله لایسنسش بررسی نمی‌شود
creditAmountintegerخیرمبلغ اعتباری که در پاسخ ثبت خرید برگشته بود
amountintegerبلهمبلغ کل فاکتور به ریال

نمونه درخواست:

json
{
  "orderTrace": "1046300323242",
  "channelType": "2",
  "rrn": "100011002374",
  "stan": "123456",
  "nationalCode": "5Aud7J8/UpL4****w5W5p5Mwrh1CSM9rUs=",
  "terminalNumber": "TERM-XXXXXXXX",
  "amount": 10000
}

🔴 این نُه فیلد همهٔ ورودی این متد است. orderItems و requestDate در این مرحله فرستاده نمی‌شوند.

توجه:

گارد لایسنس روی این متد اعمال نمی‌شود. گارد فقط روی اولین اکشن چرخه (ثبت خرید) است. این متد ادامهٔ چرخه است و حتی با لایسنسِ منقضی‌شده هم کار می‌کند — پولی که جابه‌جا شده باید قابل برگشت باشد.

خروجی

فیلدنوعتوضیح
databooleanدر پاسخ موفق مقدار true است و جزئیات دیگری ندارد

نمونه کد

php
<?php
$token = 'YOUR_SFARA_TOKEN';

$payload = json_encode([
    'orderTrace'    => '1046300323242',
    'channelType'   => '2',
    'rrn'           => '100011002374',
    'stan'          => '123456',
    'nationalCode'  => '5Aud7J8/UpL4****w5W5p5Mwrh1CSM9rUs=',
    'terminalNumber'=> 'TERM-XXXXXXXX',
    'amount'        => 10000,
]);

$ch = curl_init('https://back.tetra.land/payment/reverseorder');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $payload);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Accept: application/json',
    'Content-Type: application/json',
    "Authorization: Bearer {$token}",
]);

$response = curl_exec($ch);
curl_close($ch);

$data = json_decode($response, true);
print_r($data);

امتحان کنید

POST/payment/reverseorderامتحان کنید
orderTrace*
channelType*
rrn*
stan*
nationalCode*
cardNumber
terminalNumber*
creditAmount
amount*
نمایش JSON ارسالی
{
  "orderTrace": "1046300323242",
  "channelType": "2",
  "rrn": "100011002374",
  "stan": "123456",
  "nationalCode": "5Aud7J8/UpL4****w5W5p5Mwrh1CSM9rUs=",
  "terminalNumber": "12355679",
  "amount": "7000000"
}

پارامترهای پاسخ

پارامترنوعنمونه مقدارتوضیح
datastring-در پاسخ موفق مقدار true است و جزئیات دیگری ندارد

پاسخ‌ها

json
{
  "message": "POST Request successful.",
  "statusCode": 200,
  "result": {
    "status": true,
    "responseCode": 0,
    "data": true
  },
  "isError": false
}

۶. لغو سفارش (order-cancelation)

Endpoint

text
POST {{base_url}}/payment/ordercancelation

مثال:

text
POST https://back.tetra.land/payment/ordercancelation

Headers

کلیدمقدار
Acceptapplication/json
AuthorizationBearer {sfara_token}
Content-Typeapplication/json

Body

پارامترنوعالزامیتوضیح
orderTracestringبلهشناسهٔ سفارش که در پاسخ ثبت خرید برگشته بود
channelTypestringبله"2" — پرداخت کارتی
nationalCodestringبلهکد ملی خریدار، از قبل رمزنگاری‌شده توسط کارت‌خوان

نمونه درخواست:

json
{
  "orderTrace": "1662883620924",
  "channelType": "2",
  "nationalCode": "5Aud7J8/UpL4****w5W5p5Mwrh1CSM9rUs="
}

🔴 این سه فیلد همهٔ ورودی این متد است؛ برخلاف متدهای دیگر، شمارهٔ ترمینال گرفته نمی‌شود.

توجه:

گارد لایسنس روی این متد اعمال نمی‌شود. گارد فقط روی اولین اکشن چرخه (ثبت خرید) است. این متد ادامهٔ چرخه است و حتی با لایسنسِ منقضی‌شده هم کار می‌کند.

خروجی

فیلدنوعتوضیح
databooleanدر پاسخ موفق مقدار true است و جزئیات دیگری ندارد

نمونه کد

php
<?php
$token = 'YOUR_SFARA_TOKEN';

$payload = json_encode([
    'orderTrace' => '1662883620924',
    'channelType' => '2',
    'nationalCode' => '5Aud7J8/UpL4****w5W5p5Mwrh1CSM9rUs=',
]);

$ch = curl_init('https://back.tetra.land/payment/ordercancelation');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $payload);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Accept: application/json',
    'Content-Type: application/json',
    "Authorization: Bearer {$token}",
]);

$response = curl_exec($ch);
curl_close($ch);

$data = json_decode($response, true);
print_r($data);

امتحان کنید

POST/payment/ordercancelationامتحان کنید
orderTrace*
channelType*
nationalCode*
نمایش JSON ارسالی
{
  "orderTrace": "1662883620924",
  "channelType": "2",
  "nationalCode": "5Aud7J8/UpL4****w5W5p5Mwrh1CSM9rUs="
}

پارامترهای پاسخ

پارامترنوعنمونه مقدارتوضیح
datastring-در پاسخ موفق مقدار true است و جزئیات دیگری ندارد

پاسخ‌ها

json
{
  "message": "POST Request successful.",
  "statusCode": 200,
  "result": {
    "status": true,
    "responseCode": 0,
    "data": true
  },
  "isError": false
}

قوانین اعتبارسنجی

توجه:

توکن (sfara_token) باید در هدر Authorization به فرمت Bearer {token} ارسال شود. بدون توکن معتبر، درخواست‌های نیازمند آن با خطای ۴۰۱ رد می‌شوند.

پارامترقانون
usernameالزامی — کلید API که از پنل خود دریافت کرده‌اید
passwordالزامی — کلید محرمانهٔ همان کلید API
rrnالزامی — شمارهٔ مرجع تراکنش بانکی
stanالزامی — شمارهٔ پیگیری ترمینال
nationalCodeالزامی — کد ملی خریدار، از قبل رمزنگاری‌شده توسط کارت‌خوان
cardNumberاختیاری — شمارهٔ کارت به‌صورت ماسک‌دار
terminalNumberالزامی — ترمینالی که خرید روی آن انجام می‌شود؛ باید لایسنسِ معتبر داشته باشد
channelTypeالزامی — "2" برای پرداخت کارتی
requestDateالزامی — تاریخ و ساعت شمسی به شکل YYYYMMDDHHmmss (عدد صحیح)
amountالزامی — مبلغ کل فاکتور به ریال
orderItemsالزامی — اقلام سبد خرید
orderTraceالزامی — شناسهٔ سفارش که در پاسخ ثبت خرید برگشته بود
creditAmountاختیاری — مبلغ اعتباری که در پاسخ ثبت خرید برگشته بود