ما در یک دو سه پی سعی کردهایم تا محدودیت کمی در استفاده از وبسرویس ایجاد کنیم تا کار کردن با آن برای برنامهنویسان عزیز لذت بخش باشد.
برای دسترسی سریعتر می توانید از لینکهای زیر استفاده نمایید.
در این مرحله باید دادههای اولیه به آدرس زیر به صورت متد GET یا POST ارسال شود که توصیه ما استفاده از متد POST است.
https://123pay.ir/api/v1/create/payment
نام فیلد / داده | توضیحات | نوع داده | ضرورت ارسال |
---|---|---|---|
merchant_id | کدپذیرنده دریافتی از یک دو سه پی که در منوی «درگاههای پرداخت» در دسترس است | string | اجباری |
amount | مبلغ تراکنش | integer | اجباری |
callback_url | آدرس بازگشت | string | اجباری |
بعد از ارسال دادههای فوق در صورتی که دادههای ارسالی اشتباه باشد یا خطایی در فرآیند ایجاد تراکنش رخ دهد پاسخ زیر برای پذیرنده ارسال می گردد. برای مثال در نمونه زیر مقدار merchant_id ارسال نشده است.
{
"status": false,
"message": "فیلد کد پذیرنده الزامی است"
}
در صورتی که دادههای ارسالی صحیح باشد و درخواست تراکنش پذیرفته شود پاسخ زیر برای پذیرنده ارسال می گردد.
{
"status": true,
"message": "درخواست ایجاد تراکنش پذیرفته شد",
"RefNum" : 1,
"payment_url": "https://123pay.ir/checkout/invoice/1"
}
در صورتی که مقدار status برابر با true باشد، پذیرنده باید مقدار RefNum را ذخیره و کاربر را به payment_url هدایت کند. کاربر در این مرحله به صفحه پرداخت پیاسپی (بانک) هدایت می شود.
بعد از این که کاربر فرآیند پرداخت را در صفحه پرداخت پیاسپی (بانک) تکمیل نمود به سایت پذیرنده بازگشت داده خواهد شد. در این مرحله دادههای مذکور در جدول زیر به صورت GET یا POST به سایت پذیرنده ارسال می گردد.
نام فیلد / داده | توضیحات | نوع داده | ضرورت بررسی |
---|---|---|---|
State | وضعیت تراکنش که میتواند یکی از مقادیر OK یا NOK باشد | string | اجباری |
RefNum | شماره رسید که باید به عنوان شماره پیگیری ذخیره و به کاربر نمایش داده شود | integer | اجباری |
در صورتی که مقدار State برابر با OK باشد پذیرنده باید دادههای زیر در جدول زیر را جهت بررسی صحت تراکنش به آدرس زیر ارسال کند. در صورتی که مقدار State برابر با NOK باشد نیازی به فراخوانی تابع وریفای نیست.
https://123pay.ir/api/v1/verify/payment
نام فیلد / داده | توضیحات | نوع داده | ضرورت ارسال |
---|---|---|---|
merchant_id | کدپذیرنده دریافتی از یک دو سه پی که در منوی «درگاههای پرداخت» در دسترس است | string | اجباری |
RefNum | شماره رسید که در مرحله ارسال داده دریافت گردیده است یا موقع بازگشت از پیاسپی (بانک) دریافت می کنید | integer | اجباری |
در صورتی که دادههای ارسال اشتباه باشد یا تراکنش ناموفق باشد، پذیرنده پاسخ زیر را دریافت خواهد کرد.
{
"status": false,
"message": "تراکنش ناموفق است"
}
در صورتی که قبلاً تابع تایید / وریفای برای تراکنش فراخوانی شده باشد
{
"status": false,
"message": "تراکنش آرشیو شده است"
}
در صورتی که تراکنش موفق باشد
{
"status": true,
"message": "تراکنش موفق است",
"amount": 2000
}
نمونه کدهای PHP برای آشنایی شما قرار داده می شود تا فرآیند را در زمان کوتاهتری بررسی نمایید.
functions.php :
<?php
function create($merchant_id, $amount, $callback_url)
{
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://123pay.ir/api/v1/create/payment');
curl_setopt($ch, CURLOPT_POSTFIELDS, "merchant_id=$merchant_id&amount=$amount&callback_url=$callback_url");
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
curl_close($ch);
return $response;
}
function verify($merchant_id, $RefNum)
{
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://123pay.ir/api/v1/verify/payment');
curl_setopt($ch, CURLOPT_POSTFIELDS, "merchant_id=$merchant_id&RefNum=$RefNum");
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
curl_close($ch);
return $response;
}
create.php :
<?php
include_once('functions.php');
$merchant_id = 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx';
$amount = 1000;
$callback_url = urlencode('http://domain.ltd');
$response = create($merchant_id, $amount, $callback_url);
$result = json_decode($response);
if ($result->status) {
header('Location:' . $result->payment_url);
} else {
echo '<pre>';
print_r($result);
echo '<pre>';
}
verify.php :
<?php
include_once('functions.php');
$merchant_id = 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx';
$State = $_REQUEST['State'];
$RefNum = $_REQUEST['RefNum'];
if ($State == 'OK') {
$response = verify($merchant_id, $RefNum);
$result = json_decode($response);
if ($result->status) {
echo 'تراکنش موفق';
} else {
echo '<pre>';
print_r($result);
echo '<pre>';
}
} else {
echo 'تراکنش ناموفق - نیازی به ارسال متد وریفای نیست';
}
نام فیلد / داده | توضیحات | نوع داده | ضرورت ارسال |
---|---|---|---|
description | توضیحاتی در مورد تراکنش | string | اختیاری |
payer_first_name | نام پرداخت کننده | string | اختیاری |
payer_last_name | نام خانوادگی پرداخت کننده | string | اختیاری |
payer_email | ایمیل پرداخت کننده | string | اختیاری |
payer_mobile | موبایل پرداخت کننده | string | اختیاری |
payer_phone | تلفن پرداخت کننده | string | اختیاری |
payer_province | استان پرداخت کننده | string | اختیاری |
payer_city | شهر پرداخت کننده | string | اختیاری |
payer_address | آدرس پرداخت کننده | string | اختیاری |
payer_zip | کدپستی پرداخت کننده | string | اختیاری |
برای دریافت فعال سازی کلید API به پنل کاربر خود مراجعه و از بخش پروفایل دکمه فعال سازی API را فشار دهید تا این امکان برای شما فعال شود
با استفاده از کلید API می توانید امور زیر را انجام دهید
برای دریافت اطلاعات کاربری کافی است api_token را به صورت POST یا GET به آدرس زیر ارسال نمایید
https://123pay.ir/api/v1/getMe
<?php
$api_token = 'xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx';
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://123pay.ir/api/v1/getMe');
curl_setopt($ch, CURLOPT_POSTFIELDS, "api_token=$api_token");
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
curl_close($ch);
$result = json_decode($response);
echo '<pre>';
print_r($result);
echo '</pre>';
در صورتی که درخواست پذیرفته شود
{
"username": "username",
"first_name": "نام",
"last_name": "نام خانوادگی",
"national_id": "0000000000",
"serial_id": "000000",
"birthday": "0000-00-00",
"province": "استان",
"city": "آدرس",
"address": "آدرس پستی",
"zip": "0000000000",
"email": "[email protected]",
"mobile": "09000000000",
"phone": "02100000000",
"telegram_user_id": 00000000,
"income": 0,
"withdraw": 0,
"balance": 0,
"api_token": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"status": "فعال"
}
در صورتی که درخواست پذیرفته نشود
{
"status": false,
"message": "api token انتخاب شده، معتبر نیست"
}
برای ایجاد یک درگاه پرداخت جدید از طریق API دادههای موجود در جدول بعدی را باید به صورت متد POST یا GET به آدرس زیر ارسال نمایید
https://123pay.ir/api/v1/create/gateway
نام فیلد / داده | توضیحات | نوع داده | ضرورت ارسال |
---|---|---|---|
api_token | کلید API | string | اجباری |
name | نام درگاه پرداخت - فقط حروف و اعداد فارسی | string | اجباری |
domain | دامنه - بدون http(s) | string | اجباری |
<?php
$api_token = 'xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx';
$name = 'درگاه پرداخت شماره یک';
$domain = 'domainx.ltd';
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://123pay.ir/api/v1/create/gateway');
curl_setopt($ch, CURLOPT_POSTFIELDS, "api_token=$api_token&name=$name&domain=$domain");
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
curl_close($ch);
$result = json_decode($response);
echo '<pre>';
print_r($result);
echo '</pre>';
در صورتی که درخواست پذیرفته شود
{
"status": true
"message": "درگاه پرداخت جدید با موفقیت ثبت گردید"
"merchant_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}
در صورتی که درخواست با خطایی مواجه شود
{
"status": false,
"message": "فیلد نام الزامی است"
}
به منظور دریافت لیست درگاهها و مشخصات آن باید مقدار api_token با متد POST یا GET به آدرس زیر ارسال گردد
https://123pay.ir/api/v1/get/gateways
<?php
$api_token = 'xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx';
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://123pay.ir/api/v1/get/gateways');
curl_setopt($ch, CURLOPT_POSTFIELDS, "api_token=$api_token");
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
curl_close($ch);
$result = json_decode($response);
echo '<pre>';
print_r($result);
echo '</pre>';
در صورتی که درخواست پذیرفته شود
{
"status": true,
"gateways": [
{
"name": "درگاه پرداخت شماره یک",
"domain": "domainx.ltd",
"merchant_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"status": "فعال"
},
{
"name": "درگاه پرداخت شماره دو",
"domain": "domainz.ltd",
"merchant_id": "zzzzzzzz-zzzz-zzzz-zzzz-zzzzzzzzzzzz",
"status": "در انتظار تایید"
}
]
}
در صورتی که درخواست با خطایی مواجه شود
{
"status": false,
"message": "api token انتخاب شده، معتبر نیست"
}
برای ایجاد یک دکمه / لینک آسان پرداخت جدید از طریق API دادههای موجود در جدول بعدی را باید به صورت متد POST یا GET به آدرس زیر ارسال نمایید
https://123pay.ir/api/v1/create/button
نام فیلد / داده | توضیحات | نوع داده | ضرورت ارسال |
---|---|---|---|
api_token | کلید API | string | اجباری |
gateway | دامنه درگاه پرداخت - بدون http(s) | string | اجباری |
name | نام دکمه / لینک آسان پرداخت - فقط حروف و اعداد فارسی | string | اجباری |
amount | مبلغ | integer | اجباری |
success_callback_url | آدرس بازگشت موفق به صورت urlencode | string | اجباری |
cancel_callback_url | آدرس بازگشت ناموفق به صورت urlencode | string | اجباری |
get_full_info | نحوه دریافت اطلاعات کاربر(کامل(true) و جزئی(false)) | boolean | اجباری |
<?php
$api_token = 'xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx';
$gateway = 'domainx.ltd';
$name = 'لینک آسان پرداخت شماره یک';
$amount = 1000;
$success_callback_url = urlencode('http://domainx.ltd/success');
$cancel_callback_url = urlencode('http://domainx.ltd/cancel');
$get_full_info = false;
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://123pay.ir/api/v1/create/button');
curl_setopt($ch, CURLOPT_POSTFIELDS, "api_token=$api_token&gateway=$gateway&name=$name&amount=$amount&success_callback_url=$success_callback_url&cancel_callback_url=$cancel_callback_url&get_full_info=$get_full_info");
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
curl_close($ch);
$result = json_decode($response);
echo '<pre>';
print_r($result);
echo '</pre>';
در صورتی که درخواست پذیرفته شود
{
"status": true,
"message": "دکمه پرداخت با موفقیت ایجاد شد",
"button_id": 1,
"button_url": "https://123pay.ir/products/view/1"
}
در صورتی که درخواست با خطایی مواجه شود
{
"status": false,
"message": "فیلد نام الزامی است"
}
برای ایجاد یک فاکتور جدید از طریق API دادههای موجود در جدول بعدی را باید به صورت متد POST یا GET به آدرس زیر ارسال نمایید
https://123pay.ir/api/v1/create/invoice
نام فیلد / داده | توضیحات | نوع داده | ضرورت ارسال |
---|---|---|---|
api_token | کلید API | string | اجباری |
title | عنوان | string | اجباری |
description | توضیحات فاکتور | string | اجباری |
amount | مبلغ | integer | اجباری |
invoice_receiver_first_name | نام دریافت کننده فاکتور | string | اجباری |
invoice_receiver_last_name | نام خانوادگی دریافت کننده فاکتور | string | اجباری |
invoice_receiver_email | ایمیل دریافت کننده فاکتور | string | اجباری |
invoice_due_date | تاریخ سررسید فاکتور با فرمت Y-m-d | string | اجباری |
<?php
$api_token = 'xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx';
$title = 'عنوان فاکتور';
$description = 'توضیحات فاکتور';
$amount = 1000;
$invoice_receiver_first_name = 'نام';
$invoice_receiver_last_name = 'نام خانوادگی';
$invoice_receiver_email = '[email protected]';
$invoice_due_date = '1396-05-18';
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://123pay.ir/api/v1/create/invoice');
curl_setopt($ch, CURLOPT_POSTFIELDS, "api_token=$api_token&title=$title&description=$description&amount=$amount&invoice_receiver_first_name=$invoice_receiver_first_name&invoice_receiver_last_name=$invoice_receiver_last_name&invoice_receiver_email=$invoice_receiver_email&invoice_due_date=$invoice_due_date");
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
curl_close($ch);
$result = json_decode($response);
echo '<pre>';
print_r($result);
echo '</pre>';
در صورتی که درخواست پذیرفته شود
{
"status": true,
"message": "فاکتور با موفقیت ایجاد شد",
"invoice_id": 1
}
در صورتی که درخواست با خطایی مواجه شود
{
"status": false,
"message": "ایمیل دریافت کننده فاکتور باید یک ایمیل معتبر باشد"
}