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

با استفاده از سرویس تسهیم تراکنش قادر خواهید بود پول یک تراکنش رو به یک یا چند حساب مختلف در شبکه پرداخت پی منتقل کنید. استفاده از این سرویس دقیقا مثل سرویس اتصال به درگاه پرداخت هستش و چند پارامتر اضافه تر در مرحله ارسال اطلاعات داره

مرحله اول : ارسال دیتا

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

method: Post 
URL: https://pay.ir/pg/share/send 

پارامترهای مجاز

نام فیلد	نوع	توضیحات
api	String	API Key دریافتی از پنل کاربری شما که بعد از تایید درخواست درگاه صادر میشه
amount	Integer	مبلغ تراکنش به صورت ریال و بدون رقم اعشار. بزرگتر یا مساوی 10,000 ریال
redirect	String	آدرس بازگشتی که باید به صورت urlencode ارسال بشه و باید با آدرس درگاه پرداخت تایید شده در شبکه پرداخت پی در یک ادرس باشه
mobile	String	شماره موبایل ( اختیاری ، جهت نمایش شماره کارت Mask شده به کاربر )
factorNumber	String	شماره فاکتور شما ( اختیاری )
description	String	توضیحات تراکنش ( اختیاری ، حداکثر 255 کاراکتر )
merchants	String	آرایه ای از آبجکت JSON که حاوی فیلد های mobile ( شماره موبایل دریافت کننده سهم ) و share_percent ( درصد سهم دریافتی به صورت عدد صحیح )
validCardNumber	String	اعلام شماره کارت مجاز برای انجام تراکنش ( اختیاری، بصورت عددی (لاتین) و چسبیده بهم در 16 رقم. مثال 6219861012345678 )

HTTP/1.1 200 OK

{
  "status" : 1,
  "token" : "توکن پرداخت"
}

HTTP/1.1 422 Error

{
  "status" : 0,
  "errorCode" : "کد خطا",
  "errorMessage" : "متن پیام خطا"
}

مرحله دوم : انتقال کاربر به صفحه پرداخت

در صورتی که در مرحله ارسال دیتا ، اطلاعات ارسالی شما درست باشه در پاسخ دو مقدار status و token رو دریافت میکنید و می بایست کابر رو به شیوه زیر به درگاه ریدایرکت کنید. برای اینکار باید توکن دریافت شده در مرحله قبل رو {token} دریافت کردید رو در اخر ادرس زیر قرار بدید و کاربر رو به URL ایجاد شده ریدایرکت کنید. اگر موارد رو درست انجام بدید چند ثانیه بعد صفحه پرداخت وجه رو میتونید ببینید.

method: Get
URL: https://pay.ir/pg/{token}

نکته

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

مرحله سوم : بازگشت به سایت پذیرنده

مرحله سوم زمانی انجام میشه که کاربر از درگاه پرداخت بر میگرده. در این مرحله با توجه به نتیجه و وضعیت تراکنش، کاربر رو به آدرس کالبکی که در مرحله اول با پارامتر redirect ارسال کرده بودید هدایت میکنیم. در این مرحله دیتاهای موجود رو با متد Get باید بخونید و در دیتابیس تون ذخیره کنید.

method: Get
URL:  https://Your-CallBack-URL?status={transaction_status}&token={token}

نکته

اگر مقدار پارامتر status برابر 1 بود یعنی تراکنش موفقه و باید مرحله چهارم ( وریفای تراکنش ) رو حتما باید انجام بدید. درصورتی که تراکنش رو وریفای نکنید بعد از ۳۰ دقیقه به حساب مبدا برگشت میخوره.

مرحله چهارم : وریفای تراکنش

در مرحله قبل گفتیم که اگر مقدار فیلد status برابر عدد 1 بود حتما این مرحله رو انجام بدید و تراکنش رو وریفای کنید.

method: Post 
URL: https://pay.ir/pg/verify 

پارامترهای مجاز

نام فیلد	نوع	توضیحات
api	String	API Key دریافتی از پنل کاربری شما که بعد از تایید درخواست درگاه صادر میشه
token	String	token دریافت شده از مرحله سوم

مهم

در صورت موفق بودن تراکنش هر بار که درخواست وریفای تراکنش ارسال کنید ما به شما وضعیت موفق رو برمیگردونیم. چون ممکنه در لحظه انجام تراکنش مشکل ارتباطی به وجود بیاد و ما پاسخ صحیح رو هر بار که درخواست کنید به شما اعلام میکنیم. برای پیشگیری از بروز تقلب، حتما باید قبل از ارائه محصول یا خدمات شماره تراکنش ( transId ) رو یکبار در دیتابیس تون جستجو کنید و اگر وجود نداشت خدمات رو ارائه کنید. طبیعتا اگه مقدار transId در دیتابیس تون باشه یعنی این تراکنش قبلا انجام شده و کاربر سعی داره حسابش رو بیشتر شارژ کنه یا بدون پرداخت پول خدمات بگیره که در این حالت می بایست خطا برگردونید و خدماتی ارائه نکنید.

HTTP/1.1 200 OK

{
  "status" : 1,
  "amount" : "مبلغ تراکنش",
  "transId" : "شماره تراکنش",
  "factorNumber" : "شماره فاکتور",
  "mobile" : "شماره موبایل",
  "description" : "توضیحات",
  "cardNumber" : "شماره کارت",
  "message" : "OK",
}

HTTP/1.1 422 Error

{
  "status" : 0,
  "errorCode" : "کد خطا",
  "errorMessage" : "متن پیام خطا"
}

Test API

جهت تست درگاه در لوکال و بدون نیاز به API Key عملیاتی فقط کافیه بعد از پیاده سازی وب سرویس درگاه پرداخت، مقدار فیلد api رو برابر با عبارت test قرار بدید. همین !

api = test

نمونه کد PHP

<?php

include_once("functions.php");
$api = 'YOUR-API-KEY';
$amount = "مبلغ به ریال";
$mobile = "شماره موبایل";
$factorNumber = "شماره فاکتور";
$description = "توضیحات";
$redirect = 'http://YOUR-CALLBACK-URL';
$result = send($api, $amount, $redirect, $mobile, $factorNumber, $description);
$result = json_decode($result);
if($result->status) {
	$go = "https://pay.ir/pg/$result->token";
	header("Location: $go");
} else {
	echo $result->errorMessage;
}

<?php

include_once("functions.php");
$api = 'YOUR-API-KEY';
$token = $_GET['token'];
$result = json_decode(verify($api,$token));
if(isset($result->status)){
	if($result->status == 1){
		echo "<h1>تراکنش با موفقیت انجام شد</h1>";
	} else {
		echo "<h1>تراکنش با خطا مواجه شد</h1>";
	}
} else {
	if($_GET['status'] == 0){
		echo "<h1>تراکنش با خطا مواجه شد</h1>";
	}
}

<?php

function send($api, $amount, $redirect, $mobile = null, $factorNumber = null, $description = null) {
	return curl_post('https://pay.ir/pg/share/send', [
		'api'          => $api,
		'amount'       => $amount,
		'redirect'     => $redirect,
		'mobile'       => $mobile,
		'factorNumber' => $factorNumber,
		'description'  => $description,
		'merchants'    => [
			[
				'mobile'        => '0912XXXXXXX',
				'share_percent' => 50
			],
			[
				'mobile'        => '0937XXXXXXX',
				'share_percent' => 50
			],
		]
	]);
}

function verify($api, $token) {
	return curl_post('https://pay.ir/pg/verify', [
		'api' 	=> $api,
		'token' => $token,
	]);
}

function curl_post($url, $params)
{
	$ch = curl_init();
	curl_setopt($ch, CURLOPT_URL, $url);
	curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($params));
	curl_setopt($ch, CURLOPT_SSL_VERIFYHOST, false);
	curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);
	curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
	curl_setopt($ch, CURLOPT_TIMEOUT, 12000);
	curl_setopt($ch, CURLOPT_CONNECTTIMEOUT, 0);
	curl_setopt($ch, CURLOPT_HTTPHEADER, [
		'Content-Type: application/json',
	]);
	$res = curl_exec($ch);
	curl_close($ch);

	return $res;
}

جدول خطاها

HTTP/1.1 422 Error

{
'0':'درحال حاضر درگاه بانکی قطع شده و مشکل بزودی برطرف می شود',
'-1':'API Key ارسال نمی شود',
'-2':'Token ارسال نمی شود',
'-3':'API Key ارسال شده اشتباه است',
'-4':'امکان انجام تراکنش برای این پذیرنده وجود ندارد',
'-5':'تراکنش با خطا مواجه شده است',
'-6':'تراکنش تکراریست یا قبلا انجام شده',
'-7':'مقدار Token ارسالی اشتباه است',
'-8':'شماره تراکنش ارسالی اشتباه است',
'-9':'زمان مجاز برای انجام تراکنش تمام شده',
'-10':'مبلغ تراکنش ارسال نمی شود',
'-11':'مبلغ تراکنش باید به صورت عددی و با کاراکترهای لاتین باشد',
'-12':'مبلغ تراکنش می بایست عددی بین 10,000 و 500,000,000 ریال باشد',
'-13':'مقدار آدرس بازگشتی ارسال نمی شود',
'-14':'آدرس بازگشتی ارسالی با آدرس درگاه ثبت شده در شبکه پرداخت پی یکسان نیست',
'-15':'امکان وریفای وجود ندارد. این تراکنش پرداخت نشده است',
'-16':'یک یا چند شماره موبایل از اطلاعات پذیرندگان ارسال شده اشتباه است',
'-17':'میزان سهم ارسالی باید بصورت عددی و بین 1 تا 100 باشد',
'-18':'فرمت پذیرندگان صحیح نمی باشد',
'-19':'هر پذیرنده فقط یک سهم میتواند داشته باشد',
'-20':'مجموع سهم پذیرنده ها باید 100 درصد باشد',
'-21':'Reseller ID ارسالی اشتباه است',
'-22':'فرمت یا طول مقادیر ارسالی به درگاه اشتباه است',
'-23':'سوییچ PSP ( درگاه بانک ) قادر به پردازش درخواست نیست. لطفا لحظاتی بعد مجددا تلاش کنید',
'-24':'شماره کارت باید بصورت 16 رقمی، لاتین و چسبیده بهم باشد',
'-25':'امکان استفاده از سرویس در کشور مبدا شما وجود نداره',
'-26':'امکان انجام تراکنش برای این درگاه وجود ندارد',
'-27':'در انتظار تایید درگاه توسط شاپرک',
'-28':'امکان تسهیم تراکنش برای این درگاه وجود ندارد',
}