راهنمای اتصال به درگاه اینترنتی فینوپال
جهت استفاده از خدمات وبسرویس فینوپال باید از آدرسهای وبسرویس، متد ها و پارامترهای ذکر شده استفاده نمایید.
ارسال اطلاعات
در مرحله اول پذیرندگان باید پارامترهای موجود در جدول زیر را ، با توجه به نوع دادهها و نام فیلد، با متدPOSTبه آدرس مشخص شده ارسال نمایند.
POST
https://payment.finopal.ir/api/v1/payment/request
جدول مقادیر ارسالی
| نام | نوع | الزام | توضیحات |
|---|---|---|---|
| merchant_id | String | بله | كد 24 كاراكتری اختصاصی پذیرنده |
| amount | Integer | بله | مبلغ تراکنش(ریال) |
| callback_url | String | بله | صفحه بازگشت مشتري، پس از انجام عمل پرداخت |
| order_id | string | بله | شماره سفارش |
| description | String | خیر | توضیحات مربوط به تراکنش |
| mobile | String | خیر | شماره تماس خریدار |
| String | خیر | آدرس ایمیل خریدار | |
| metadata | Array | خیر | دارای مقدار های user_id و product_id |
نمونه کد ارسال درخواست
PHP
<?php
$curl = curl_init();
curl_setopt_array($curl, array(
CURLOPT_URL => 'https://payment.finopal.ir/api/v1/payment/request',
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 =>'{
"merchant_id": "fino-xxxx-xxxx-xxxx-xxxx",
"amount": 1100,
"order_id": "invoice-123",
"callback_url": "http://example.com/verify",
"description": "Transaction description.",
"mobile": "09121234567",
"email": "eample@example.com,
"metadata": {
"product_id": "123",
"user_id": "960"
}
}',
CURLOPT_HTTPHEADER => array(
'Content-Type: application/json',
'Accept: application/json'
),
));
$response = curl_exec($curl);
curl_close($curl);
echo $response;نمونه پاسخ دریافنی
JSON
{
"success": true,
"code" : 100,
"data": {
"authority": "FP_636E4A5CBBCE0F222B46829BD74AB4A9",
"payment_url": "https://pna.shaparak.ir/mhui/home/index/SANDBOX_MTAwMTAwXzE3NzE0MTMwMjU="
},
"message": "درخواست پرداخت با موفقیت ایجاد شد"
}
انتقال خریدار به صفحه پرداخت اینترنتی
در صورتی که در مرحله ارسال دیتا اولیه، اطلاعات ارسالی صحیح باشد و سه مقدار success و authority و code را دریافت کرده باشید، باید خریدار را به درگاه پرداخت انتقال دهید.
توجه داشته باشید که در صورتی که درخواست ارسالی موفقیت آمیز باشد باید کد 100 را در فیلد code دریافت کرده باشید.
برای این منظور باید مقدار payment_url را دریافت و کاربر را به این مسیر هدایت کنید
بازگشت به وبسایت پذیرنده
بعد از پایان عملیات در سمت فینوپال، خریدار از درگاه پرداخت اینترنتی باز میگردد. در این مرحله با توجه به نتیجه تراکنش و وضعیت آن، فینوپال خریدار را به آدرس درخواستی پذیرنده که در ارسال اطلاعات با پارامتر callback_url مشخص شده است، هدایت میکند.
توجه داشته باشید كه یك Status به صورت QueryString به سایت پذیرنده ارسال میشود كه دارای دو مقدار ثابت”OK“ و”NOK“ است؛ در صورتی كه این مقدار برابر ”NOK“ باشد، به این معنا است كه تراكنش ناموفق بوده یا توسط خریدار لغو شده است؛ درنتیجه متد verify باید در صورتی استفاده شود كه در QueryString مقدار Status برابر با ”OK“ باشد.
GET
http://www.yoursite.ir/?Authority=A0000000000000000000000000000wwOGYpd&Status=OK
اعتبارسنجی
برای استفاده از این متد، باید ابتدا در صفحه بازگشت، با استفاده از متدverify اطلاعات ارسالی را چک کرده و در صورت موفق بودن پرداخت، آن را ثبت و شماره تراکنش را به کاربر نمایش دهید. در غیر اینصورت موظف هستید بـا توجه به كد خطایی كه توسط متد verify دریافت میكنید كاربر را از خطای رخ داده مطلع سازید.
در این مرحله اگر مقدار پارامتر code برابر 100 باشد به معنای موفق بودن تراکنش است و میتوانید با پارامتر ref_id شماره تراکنش را به کاربر نمایش دهد.
درصورت موفقیت آمیز بودن تراکنش، با فراخوانی متدverify ، تنها یکبار کد100 رخ میدهد و در دفعات بعدی verify همان تراکنش، کد 101 اتفاق میافتد. در نتیجه کد 101 به معنای آن است که تراکنش موفق بوده و یکبار قبلا عملیات verifyبر روی آن انجام شده است. لطفا در نظر داشته باشید که در دفعات بعدی verify همان تراکنش نیز کد 101 نشان داده میشود.
POST
https://payment.finopal.ir/api/v1/payment/verify
نمونه کد ارسال درخواست
PHP
<?php
$curl = curl_init();
curl_setopt_array($curl, array(
CURLOPT_URL => 'https://payment.finopal.ir/api/v1/payment/verify',
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 =>'{
"merchant_id": "fino-xxxx-xxxx-xxxx-xxxx",
"amount": "1000",
"authority": "A0000000000000000000000000000wwOGYpd"
}',
CURLOPT_HTTPHEADER => array(
'Content-Type: application/json',
'Accept: application/json'
),
));
$response = curl_exec($curl);
curl_close($curl);
echo $response;نمونه پاسخ دریافنی
JSON
{
"success": true,
"data": {
"code": 100,
"ref_id": "xxxx-xxxx-xxxx",
"amount": "1000.00"
},
"message": "پرداخت با موفقیت تایید شد"
}