مستند برقراری ارتباط با درگاه اینترنتی(IPG) از طریق API به منظور ایجاد تراکنش

آدرس پایه (Base URL):

/https://backend.sayment.ir/api/pardakht

به منظور ایجاد تراکنش پرداخت توسط API توسعه داده شده، ابتدا می بایست یک تراکنش ایجاد کنید. برای ایجاد تراکنش وبسرویس create را با استفاده از متد POST فراخوانی کنید و مقادیر ارسالی را در بدنه درخواست خود ست کنید.

فیلدهای مجاز در این وبسرویس شامل موارد زیر است :

 نام فیلدشرحاجباری / اختیاری
*amountمبلغ تراکنشاجباری
**order_idشناسه سفارشاجباری
 callbackآدرس برگشتاجباری
 nameنام پرداخت کنندهاختیاری
 phoneتلفن پرداخت کنندهاختیاری
 mailایمیل پرداخت کنندهاختیاری
 descriptionتوضیحات پرداختاختیاری
***card_numberشماره کارت پرداخت کنندهاختیاری

* مبلغ تراکنش می بایست به ریال باشد و حداقل 1,000 ريال و حداکثر 500,000,000 ریال است. همچنین با توجه به تنظیمات کارمزد پایانه، سهم کارمزد پرداخت کننده به مبلغ افزوده خواهد شد.

** یکتایی شناسه سفارش در سامانه بررسی نمی شود. بهتر است به منظور جلوگیری از بروز خطا از شناسه یکتا استفاده شود. طول شناسه سفارش حداقل 4 و حداکثر 19 کاراکتر و شامل حروف و اعداد می باشد.

*** تنها در صورتی که نیاز است در تراکنش پرداخت شماره کارتی که پرداخت را انجام میدهد بررسی شود این مقدار را در درخواست ایجاد تراکنش ارسال کنید. در صورتی که پرداخت با کارتی غیر از کارت ارسالی در هنگام ایجاد تراکنش انجام شود، وبسرویس به صورت خودکار تراکنش را ابطال می کند و مبلغ پرداختی پس از حداکثر 30 دقیقه برگشت داده می شود.

نکته مهم:

به منظور احراز هویت در Header در خواست خود ازBearer  استفاده کنید و مقدار شناسه ترمینال خود را به عنوان توکن بعد از Bearer قرار دهید.

مثال:

Authorization: Bearer kwmzl85o16kw3

درصورتی که نتیجه درخواست موفق باشد، وبسرویس یک توکن برمی‌گرداند.

نمونه درخواست ایجاد تراکنش:

نمونه کد php

<?php 

$curl 
curl_init();

curl_setopt_array($curl, array(
  
CURLOPT_URL => "https://backend.sayment.ir/api/pardakht/create",
  
CURLOPT_RETURNTRANSFER => true,
  
CURLOPT_ENCODING => "",
  
CURLOPT_MAXREDIRS => 10,
  
CURLOPT_TIMEOUT => 0,
  
CURLOPT_FOLLOWLOCATION => true,
  
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  
CURLOPT_CUSTOMREQUEST => "POST",
  
CURLOPT_POSTFIELDS => array(
'amount' => '50000',
'order_id' => '12356',
'callback' => 'http://mysite.com/callback',
'name' => 'Ali Akbari',
'phone' => '09123456789',
'mail' => 'email@site.com'
  
),
  
CURLOPT_HTTPHEADER => array(
    
"Authorization: Bearer 251zxkdooqld0ye"
  
),
));

$response curl_exec($curl);

curl_close($curl);
echo 
$response;

?>

نمونه کد Javascript

    var form = new FormData();
form.append("amount", "50000");
form.append("order_id", "123456");
form.append("callback", "http://site.com/callback");
form.append("name", "hosein");
form.append("phone", "09123456789");
form.append("mail", "demo@test.com");

var settings = {
  "url": "https://backend.sayment.ir/api/pardakht/create",
  "method": "POST",
  "timeout": 0,
  "headers": {
    "Authorization": "Bearer 251zxkdooqld0ye"
  },
  "processData": false,
  "mimeType": "multipart/form-data",
  "contentType": false,
  "data": form
};

$.ajax(settings).done(function (response) {
  console.log(response);
});

نمونه پاسخ ارسالی وبسرویس create:

نکات مهم:

  • مقدار ref_num کد یکتای پیگیری تراکنش میان پذیرنده و پرداختیار می باشد و در مراحل بعدی به منطور تایید فرآیند پرداخت از آن استفاده خواهد شد.
  • مقدار payment_amount مبلغ نهایی پرداختی کاربر (مبلغ پرداخت + کارمزد) می باشد.
پس از آنکه تراکنش ایجاد شد، باید کاربر را به همراه توکن به سمت وبسرویس payment هدایت کنید. به این صورت که مقدار توکن دریافتی را با کلید token با استفاده از متد POST به وبسرویس ارسال می‌کنید. مثال:
<input type="hidden" id="token" name="token" value="ds556hfhfg65aerf51vdf2xsdvc16" />

پس از آنکه عملیات پرداخت انجام شد، کاربر به همراه نتیجه تراکنش به صفحه بازگشت سایت شما هدایت می شود. برای دریافت اطلاعات می بایست مقادیر ارسالی متد POST را فراخوانی کنید.

در صورت موفق بودن تراکنش، مقادیر زیر برگشت داده می‌شود:

نام فیلد

شرح

status

کد وضعیت (موفق: 1)

order_id

شناسه سفارش

ref_num

کد یکتای پیگیری تراکنش

card_number

شماره کارتی که پرداخت توسط آن انجام شده است

tracking_code

کد تراکنش بانک

  • در صورتی که تراکنش ناموفق باشد مقدار tracking_code و card_number ارسال نخواهد شد.

پس از دریافت تراکنش موفق با فراخوانی وبسرویس verify، عملیات پرداخت را نهایی کنید. بدین منظور مقادیر زیر را در بدنه درخواست اضافه کنید و با استفاده از متد POST وبسرویس را فراخوانی کنید. توجه کنید برای استفاده از این وبسرویس همانند وبسرویس create می بایست از احراز هویت Bearer مطابق روش ذکر شده استفاده کنید.

نام فیلد

شرح

اجباری / اختیاری

ref_num

شناسه یکتای تراکنش

اجباری

amount

مبلغ

اجباری

* منظور از مبلغ، مبلغ اصلی تراکنش (بدون کارمزد) می‌باشد.

در صورتی که عملیات تایید پرداخت موفقیت آمیز باشد، وبسرویس مقادیر price و ref_num را به شما برمی‌گرداند.

توجه داشته باشید به ازای هر تراکنش تنها یکبار قادر خواهید بود وبسرویس verify را فراخوانی کنید.

چنانچه از سامانه های مدیریت فروشگاهی استفاده می کنید برای دریافت افزونه سیمنت اینجا کلیک کنید.
درصورت نیاز به راهنمایی با شماره ۴۲۴۷۳۰۰۰ تماس حاصل فرمایید.