راهنمای برنامه نویسان

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

ارسال داده‌ها و درخواست پرداخت

در این مرحله باید داده‌های اولیه به آدرس زیر به صورت متد 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($chCURLOPT_URL'https://123pay.ir/api/v1/create/payment');
    
curl_setopt($chCURLOPT_POSTFIELDS"merchant_id=$merchant_id&amount=$amount&callback_url=$callback_url");
    
curl_setopt($chCURLOPT_SSL_VERIFYPEERfalse);
    
curl_setopt($chCURLOPT_RETURNTRANSFERtrue);
    
$response curl_exec($ch);
    
curl_close($ch);

    return 
$response;
}

function 
verify($merchant_id$RefNum)
{
    
$ch curl_init();
    
curl_setopt($chCURLOPT_URL'https://123pay.ir/api/v1/verify/payment');
    
curl_setopt($chCURLOPT_POSTFIELDS"merchant_id=$merchant_id&RefNum=$RefNum");
    
curl_setopt($chCURLOPT_SSL_VERIFYPEERfalse);
    
curl_setopt($chCURLOPT_RETURNTRANSFERtrue);
    
$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 می توانید امور زیر را انجام دهید

  1. دریافت مشخصات حساب کاربری
  2. ثبت درگاه پرداخت جدید
  3. دریافت لیست درگاه‌های پرداخت و مشخصات آن‌ها
  4. ایجاد لینک / دکمه آسان پرداخت
  5. ایجاد فاکتور

دریافت اطلاعات کاربری

برای دریافت اطلاعات کاربری کافی است api_token را به صورت POST یا GET به آدرس زیر ارسال نمایید

https://123pay.ir/api/v1/getMe

نمونه کد دریافت اطلاعات کاربری

                        
<?php
$api_token 
'xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx';

$ch curl_init();
curl_setopt($chCURLOPT_URL'https://123pay.ir/api/v1/getMe');
curl_setopt($chCURLOPT_POSTFIELDS"api_token=$api_token");
curl_setopt($chCURLOPT_SSL_VERIFYPEERfalse);
curl_setopt($chCURLOPT_RETURNTRANSFERtrue);
$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($chCURLOPT_URL'https://123pay.ir/api/v1/create/gateway');
curl_setopt($chCURLOPT_POSTFIELDS"api_token=$api_token&name=$name&domain=$domain");
curl_setopt($chCURLOPT_SSL_VERIFYPEERfalse);
curl_setopt($chCURLOPT_RETURNTRANSFERtrue);
$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($chCURLOPT_URL'https://123pay.ir/api/v1/get/gateways');
curl_setopt($chCURLOPT_POSTFIELDS"api_token=$api_token");
curl_setopt($chCURLOPT_SSL_VERIFYPEERfalse);
curl_setopt($chCURLOPT_RETURNTRANSFERtrue);
$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($chCURLOPT_URL'https://123pay.ir/api/v1/create/button');
curl_setopt($chCURLOPT_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($chCURLOPT_SSL_VERIFYPEERfalse);
curl_setopt($chCURLOPT_RETURNTRANSFERtrue);
$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($chCURLOPT_URL'https://123pay.ir/api/v1/create/invoice');
curl_setopt($chCURLOPT_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($chCURLOPT_SSL_VERIFYPEERfalse);
curl_setopt($chCURLOPT_RETURNTRANSFERtrue);
$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": "ایمیل دریافت کننده فاکتور باید یک ایمیل معتبر باشد"
}