مستندات فنی - وب سرویس درگاه پرداخت

وب سرویس اتصال به درگاه پرداخت

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

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

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

عنوان فیلد نوع توضیحات
apiKey string کلید وب سرویس، که پس از ثبت درخواست درگاه و تایید برای شما صادر می شود
amount integer مبلغ تراکنش به ریال
callbackUrl string آدرس بازگشت به سایت پذیرنده، که کاربر پس از انجام تراکنش به این آدرس هدایت می شود و نتیجه تراکنش هم به این آدرس ارسال می شود
invoiceNumber string شماره فاکتور
payerName string نام پرداخت کننده که به صورت اختیاری می باشد
payerMobile string شماره موبایل پرداخت کننده که به صورت اختیاری می باشد
payerEmail string پست الکترونیکی پرداخت کننده که به صورت اختیاری می باشد
description string توضیحات مربوط به تراکنش که به صورت اختیاری می باشد
affiliateCode string کد معرف، در صورتی که این کد ارسال شود بخشی از کارمزد تراکنش به معرف تعلق میگیرد
آدرس
Method: POST
URL: https://sepal.ir/api/request.json
پاسخ
{
    "status": true,
    "message": "",
    "paymentNumber": 412843002512
}

مرحله دوم: هدایت به درگاه پرداخت

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

آدرس
Method: GET
URL: https://sepal.ir/payment/{paymentNumber}

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

پس از انجام تراکنش در درگاه پرداخت کاربر به آدرس بازگشتی (callbackUrl) که در مرحله اول ارسال شده است، ریدایرکت می شود و نتیجه تراکنش هم به صورت POST به این آدرس ارسال می گردد.

عنوان فیلد نوع توضیحات
status string نتیجه تراکنش را مشخص می کند در صورتی که برابر 1 باشد به معنای انجام موفق تراکنش است در غیر این صورت به معنای ناموفق بودن تراکنش است
paymentNumber string شماره پرداخت که در مرحله اول پس از دریافت پاسخ صحیح توسط سیستم ایجاد شده است
invoiceNumber string شماره فاکتوری است که در مرحله اول برای انجام تراکنش به سیستم ارسال شده است

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

پس از بازگشت کاربر به آدرس callbackUrl و دریافت وضعیت status برابر با 1 باید صحت انجام تراکنش از طریق وب سرویس استعلام شود. برای این کار پارامترهای زیر را به آدرس وب سرویس ارسال کنید

عنوان فیلد نوع توضیحات
apiKey string کلید وب سرویس، که پس از ثبت درخواست درگاه و تایید برای شما صادر می شود
paymentNumber string شماره پرداخت در که در مرحله اول دریافت شده است
invoiceNumber string شماره فاکتوری است که در مرحله اول برای انجام تراکنش به سیستم ارسال شده است
آدرس
Method: POST
URL: https://sepal.ir/api/verify.json
پاسخ
{
    "status": true,
    "message": "",
    "cardNumber": "6037********8955"
}

نمونه کد PHP

ارسال درخواست انجام تراکنش
$params = array(
    'apiKey' => 'YOUR-API-KEY',
    'amount' => 'مبلغ به ریال',
    'callbackUrl' => 'http://YOUR-CALLBACK-URL',
    'invoiceNumber' => 'شماره فاکتور',
    'payerName' => 'نام پرداخت کننده',
    'payerMobile' => 'موبایل پرداخت کننده',
    'payerEmail' => 'پست الکترونیکی پرداخت کننده',
    'description' => 'توضیحات',
);
$curl = curl_init();
curl_setopt($curl, CURLOPT_URL, 'https://sepal.ir/api/request.json');
curl_setopt($curl, CURLOPT_HTTPHEADER, array('Content-Type' => 'application/json'));
curl_setopt($curl, CURLOPT_POSTFIELDS, json_encode($params));
curl_setopt($curl, CURLOPT_SSL_VERIFYPEER, false);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
$response = json_decode(curl_exec($curl));
curl_close($curl);
if(isset($response->status) && $response->status == 1 ){
    $paymentUrl = 'https://sepal.ir/payment/'.$response->paymentNumber;
    header('Location: '.$paymentUrl);
    exit;
}else{
    echo $response->message;
}
دریافت تایید تراکنش
$params = array(
    'apiKey' => 'YOUR_API_KEY',
    'paymentNumber' => 'شماره پرداخت دریافت شده در مرحله اول',
);
$curl = curl_init();
curl_setopt($curl, CURLOPT_URL, 'https://sepal.ir/api/verify.json');
curl_setopt($curl, CURLOPT_HTTPHEADER, array('Content-Type' => 'application/json'));
curl_setopt($curl, CURLOPT_POSTFIELDS, json_encode( $params ));
curl_setopt($curl, CURLOPT_SSL_VERIFYPEER, false);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
$response = json_decode(curl_exec($curl));
curl_close($curl);
if(isset($response->status) && $response->status == 1){
    echo 'تراکنش با موفقیت انجام شد';
}else{
    echo 'خطا در انجام تراکنش - '.$response->message;
}

API آزمایشی

جهت تست درگاه سپال بعد از پیاده سازی وب سرویس درگاه پرداخت می توانید با جایگزین آدرس های ذیل و جاگذاری apiKey با مقدار test ، صحت اتصال به درگاه سپال را تست بفرمائید:
کلید وب سرویس

    apiKey = test
            
آدرس ارسال درخواست تراکنش

    URL: https://sepal.ir/api/sandbox/request.json
آدرس هدایت به درگاه پرداخت

    URL: https://sepal.ir/sandbox/payment
آدرس دریافت تاییدیه تراکنش

    URL: https://sepal.ir/api/sandbox/verify.json