اگر فروشگاه شما سایتی دارد و می‌خواهید کارت‌به‌کارت را هم به روش‌های پرداخت اضافه کنید، اتصال از طریق API و وب‌هوک انجام می‌شود. این صفحه جریان اتصال را برای صاحب سایت و توسعه‌دهنده شرح می‌دهد.
خیلی از فروشگاه‌های اینترنتی ایرانی، به‌ویژه آن‌هایی که تازه راه افتاده‌اند یا هنوز درگاه بانکی نگرفته‌اند، در صفحه‌ی پرداخت یک متن ساده دارند: «مبلغ را به این شماره کارت واریز کنید و رسید را در واتساپ بفرستید». این روش کار می‌کند، ولی سفارش و پرداخت را از هم جدا می‌کند. سفارش در سایت ثبت می‌شود، رسید در پیام‌رسان می‌رود و کسی باید دستی این دو را به هم برساند.
اتصال کارت‌به‌کارت از طریق API این شکاف را می‌بندد. سفارش در سایت ساخته می‌شود، پرداخت در کارت پی، و وقتی پرداخت تأیید شد، سایت خودش خبردار می‌شود و سفارش را نهایی می‌کند. هیچ رسیدی در پیام‌رسان گم نمی‌شود و هیچ سفارشی بی‌دلیل در انتظار پرداخت نمی‌ماند.
اگر درگاه بانکی دارید، کارت‌به‌کارت می‌تواند یک روش پرداخت دوم باشد برای مشتری‌هایی که آن را ترجیح می‌دهند. اگر ندارید، تا وقتی درگاه بگیرید، همین روش فروش را منظم نگه می‌دارد. در هر دو حالت، کارت پی پول را نگه نمی‌دارد و واریز مستقیم به کارت شما انجام می‌شود.
بک‌اند سایت شما مبلغ، عنوان و نشانی بازگشت را به کارت پی می‌فرستد و شناسه‌ی تراکنش و نشانی صفحه‌ی پرداخت را می‌گیرد.
مشتری مبلغ و شماره کارت را می‌بیند، کارت‌به‌کارت می‌کند و رسید را ثبت می‌کند.
پس از ثبت رسید، مرورگر به نشانی بازگشت سایت شما هدایت می‌شود. اینجا فقط پیام مناسب نشان می‌دهید.
شما یا همکارتان رسید را از پنل یا ربات تأیید می‌کنید.
پیامی امضاشده از تغییر وضعیت به سرور شما می‌رسد و سفارش را نهایی یا لغو می‌کنید.
ثبت‌نام با شماره موبایل و کد تأیید انجام می‌شود.
در بخش توسعه‌دهندگان پنل کلید می‌سازید و آن را فقط در سرور نگه می‌دارید.
با ارسال عنوان و مبلغ و نشانی بازگشت، تراکنشی با وضعیت «در انتظار پرداخت» ساخته می‌شود و نشانی پرداخت برمی‌گردد. اگر نشانی وب‌هوک را هم بدهید، تغییرات به آن ارسال می‌شود.
مشتری را به نشانی پرداخت می‌فرستید. لازم نیست در کارت پی حساب داشته باشد.
پس از ثبت رسید، مشتری به نشانی بازگشت شما برمی‌گردد.
هر تغییر وضعیت با بدنه‌ی امضاشده به سرور شما می‌رسد و سفارش را نهایی یا لغو می‌کنید.
بیشتر فروشگاه‌های ایرانی روی PHP اجرا می‌شوند، پس نمونه‌ها به PHP است. منطق در هر زبان دیگری هم همین است. کلید API را در متغیر محیطی یا فایل تنظیمات خارج از پوشه‌ی عمومی نگه دارید.
$payload = [
'amount' => $order_total,
'title' => 'سفارش ' . $order_id,
'callback_url' => 'https://shop.example.com/checkout/return?order=' . $order_id,
'api_callback_url' => 'https://shop.example.com/kartpay/webhook',
];
$ch = curl_init('https://kartpy.ir/api/v1/open/payment/request/');
curl_setopt_array($ch, [
CURLOPT_POST => true,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['X-API-KEY: ' . getenv('KARTPAY_API_KEY'),
'Content-Type: application/json'],
CURLOPT_POSTFIELDS => json_encode($payload),
]);
$res = json_decode(curl_exec($ch), true);
$tx = $res['data'][0];
save_transaction_id($order_id, $tx['transaction_id']);
header('Location: ' . $tx['payment_url']);$raw = file_get_contents('php://input');
$given = $_SERVER['HTTP_X_KARTPAY_SIGNATURE'] ?? '';
$expected = 'sha256=' . hash_hmac('sha256', $raw, getenv('KARTPAY_API_KEY'));
if (!hash_equals($expected, $given)) {
http_response_code(401);
exit;
}
$event = json_decode($raw, true);
// سفارش را با transaction_id پیدا کنید و فقط اگر هنوز نهایی نشده، به‌روز کنید.
http_response_code(200);این نمونه‌ها برای فهم جریان است و باید با ساختار سایت شما تطبیق داده شود: مدیریت خطا، لاگ و جلوگیری از پردازش تکراری را هم اضافه کنید. فهرست کامل فیلدها در Swagger آمده است.
کلید API را در جاوااسکریپت صفحه یا اپلیکیشن موبایل قرار ندهید. هرکس آن را داشته باشد، می‌تواند به نام شما پرداخت بسازد و تراکنش‌ها را بخواند.
قبل از باور کردن وب‌هوک، امضای HMAC را روی بدنه‌ی خام بررسی کنید و درخواست بی‌امضا یا با امضای غلط را رد کنید.
یک رویداد ممکن است بیش از یک بار برسد؛ اگر سفارش قبلاً نهایی شده، دوباره کاری نکنید.
پارامترهای نشانی بازگشت قابل دستکاری‌اند و فقط برای نمایش پیام به کاربرند. وضعیت واقعی را از وب‌هوک یا API بخوانید.
صفحه‌ای که مشتری پس از پرداخت به آن برمی‌گردد مهم‌تر از آن است که به نظر می‌رسد. در درگاه بانکی، مشتری در این صفحه «پرداخت موفق» می‌بیند. در کارت‌به‌کارت، در این لحظه پرداخت هنوز تأیید نشده است؛ رسید ثبت شده و منتظر بررسی شماست.
پس پیش از نمایش پیام، یک بار وضعیت تراکنش را از API بپرسید و بر اساس آن پیام بدهید:
این پیام‌ها مشتری را آرام نگه می‌دارند و تعداد پیام‌های «پولم رسید؟» را کم می‌کنند.
در درگاه بانکی، فاصله‌ی سفارش تا تأیید پرداخت چند ثانیه است. در کارت‌به‌کارت، این فاصله ممکن است چند دقیقه یا چند ساعت باشد؛ تا وقتی که شما رسید را تأیید کنید. برای فروشگاهی که موجودی محدود دارد، این فاصله یک سؤال طراحی ایجاد می‌کند: کالا را از چه لحظه‌ای برای مشتری کنار بگذاریم؟
موجودی را با ثبت سفارش برای مدت کوتاهی رزرو کنید. اگر وب‌هوکی رسید که نشان می‌داد رسید ثبت شده (در انتظار بررسی)، رزرو را تا تصمیم شما نگه دارید. اگر مشتری در مهلت معقول پرداخت نکرد یا پرداخت رد شد، رزرو را آزاد کنید. به این ترتیب کالایی که پولش در راه است به نفر دیگری فروخته نمی‌شود و کالای سفارش‌های رهاشده هم تا ابد قفل نمی‌ماند.
هر چه رسیدها را سریع‌تر تأیید کنید، این مسئله کوچک‌تر می‌شود. برای همین بسیاری از فروشگاه‌ها اعلان ربات تلگرام یا بله را روشن نگه می‌دارند تا رسیدها در ساعت کاری ظرف چند دقیقه بررسی شوند.
اگر درگاه بانکی هم دارید، می‌توانید هر دو را در صفحه‌ی تسویه‌ی سفارش نمایش دهید. چند نکته کمک می‌کند مشتری روش مناسب را انتخاب کند:
بعضی مشتری‌ها کارت‌به‌کارت را ترجیح می‌دهند چون رمز دوم ندارند یا سقف درگاه را پر کرده‌اند. داشتن هر دو روش، فروشی را که به‌خاطر یک مانع کوچک از دست می‌رفت حفظ می‌کند.
کارت پی افزونه‌ی آماده برای وردپرس یا ووکامرس ارائه نمی‌کند. اگر سایت شما وردپرسی است، اتصال با کد اختصاصی یا افزونه‌ای که توسعه‌دهنده‌ی شما با همین API و وب‌هوک بنویسد انجام می‌شود. نمونه‌ی PHP بالا نقطه‌ی شروع خوبی برای چنین کدی است.
برای فروشگاه‌های ساخته‌شده با فریم‌ورک‌های دیگر، مثل لاراول، جنگو یا نود، هم جریان همین است، چون API مستقل از پلتفرم است و فقط HTTP و JSON می‌خواهد. سایت‌سازهای آماده‌ای که اجازه‌ی کد سمت سرور نمی‌دهند معمولاً نمی‌توانند وب‌هوک بگیرند؛ برای آن‌ها لینک پرداخت ساده‌تر است.
| موضوع | دکمه‌ی لینک پرداخت در سایت | اتصال با API و وب‌هوک |
|---|---|---|
| نیاز به برنامه‌نویس | ندارد | دارد |
| مبلغ سفارش | مشتری خودش وارد می‌کند یا خدمت ثابت است | از سبد خرید سایت فرستاده می‌شود |
| اتصال سفارش و پرداخت | دستی | با شناسه‌ی تراکنش |
| نهایی کردن سفارش | خودتان در پنل سایت | سایت با وب‌هوک خبردار می‌شود |
| مناسب برای | سایت‌های معرفی و فروش کم | فروشگاه با سبد خرید و سفارش‌های زیاد |
فروشگاهی که هنوز درگاه بانکی نگرفته، از برنامه‌نویس خود خواسته روش پرداخت «کارت‌به‌کارت» را با API کارت پی اضافه کند. با ثبت سفارش، مشتری به صفحه‌ی پرداخت می‌رود، رسید را ثبت می‌کند و برمی‌گردد. مدیر فروشگاه رسید را در بله تأیید می‌کند و سفارش در پنل وردپرس خودش «در حال پردازش» می‌شود. دیگر کسی رسیدها را از واتساپ به سایت منتقل نمی‌کند.
کارگاهی که سایتش فقط معرفی محصولات است و سبد خرید ندارد، کنار هر محصول یک دکمه‌ی «خرید» گذاشته که به لینک خدمت همان محصول در کارت پی می‌رود. نیازی به برنامه‌نویسی نبود و پرداخت‌ها در پنل کارت پی جمع می‌شوند.
رسیدن مشتری به صفحه‌ی بازگشت یعنی رسید ثبت شده، نه اینکه پول تأیید شده. منتظر وب‌هوک یا وضعیت تأییدشده بمانید.
اگر شناسه‌ی تراکنش را کنار سفارش ذخیره نکنید، وقتی وب‌هوک برسد نمی‌دانید مال کدام سفارش است.
نشانی وب‌هوک باید از اینترنت در دسترس و با HTTPS باشد. پشت ورود یا فایروال نگذارید.
وقتی رسید رد می‌شود، سفارش را به مشتری نشان دهید تا دوباره پرداخت کند؛ آن را بی‌خبر لغو نکنید.
مستندات کامل، Swagger و فایل OpenAPI در دسترس‌اند. پاسخ‌ها ساختار ثابتی دارند (status و message و data) و می‌توانید با Swagger هر اندپوینت را مستقیم امتحان کنید. محیط جداگانه‌ای با پول مجازی ادعا نشده است؛ برای آزمایش از حساب خودتان و مبلغ‌های کوچک استفاده کنید و پرداخت آزمایشی را بعد از تست رد یا لغو کنید.
جزئیات اندپوینت‌ها، ساختار پاسخ و رفتار وب‌هوک را در API پرداخت کارت به کارت می‌خوانید. اگر تأیید را بیشتر از پیام‌رسان انجام می‌دهید، تأیید پرداخت از تلگرام و بله را هم ببینید.
اتصال پرداخت معمولاً کار دو نفر است: صاحب فروشگاه که می‌داند فروش چطور باید پیش برود، و توسعه‌دهنده‌ای که کد را می‌نویسد. بخش زیادی از تأخیرهای این پروژه‌ها از اینجا می‌آید که این دو تصمیم‌های غیرفنی را از هم نپرسیده‌اند.
ساخت درخواست پرداخت هنگام ثبت سفارش، ذخیره‌ی شناسه‌ی تراکنش، دریافت و بررسی امضای وب‌هوک، به‌روزرسانی سفارش و ساخت پیام درست در صفحه‌ی بازگشت. اگر تصمیم‌های بالا از قبل روشن باشد، این بخش فنی معمولاً کوتاه و بی‌دردسر است.
اتصال که راه افتاد، چند هفته‌ی اول ارزش دارد چند شاخص ساده را زیر نظر بگیرید تا اگر جایی گیر دارد، زود پیدا شود.
مورد آخر مهم‌ترین است. اگر سفارشی بدون تأیید پرداخت در سایت نهایی شده، یعنی جایی از کد به نشانی بازگشت مرورگر اعتماد کرده است. همان را اصلاح کنید.
خیر. اتصال وردپرس با کدنویسی روی API انجام می‌شود؛ نمونه‌ی PHP این صفحه نقطه‌ی شروع است.
نه. مشتری از سایت شما به صفحه‌ی پرداخت می‌آید و لازم نیست حساب بسازد.
وب‌هوک مستقل از مرورگر ارسال می‌شود، پس تغییر وضعیت بعداً هم به سرور شما می‌رسد.
شما از پنل یا ربات تأیید می‌کنید و سایت‌تان با وب‌هوک مطلع می‌شود.
برای تست می‌توانید از Swagger و حساب خودتان با مبلغ‌های کوچک استفاده کنید. محیط جداگانه‌ی sandbox در این صفحه ادعا نشده است.
خیر. فقط کارت‌به‌کارت.
ارسال چند بار با فاصله‌های افزایشی تکرار می‌شود. برای اطمینان بیشتر، سفارش‌های معلق را دوره‌ای با اندپوینت بررسی وضعیت چک کنید.
اختیاری است. اگر بفرستید، در پنل کنار پرداخت دیده می‌شود.
باید با http:// یا https:// شروع شود. برای سایت واقعی از https استفاده کنید.
مستندات کامل اندپوینت‌ها، نمونه درخواست‌ها و Swagger پس از ورود به پنل پذیرنده، در بخش «توسعه‌دهندگان» در دسترس است.
حساب بسازید، کارت بانکی را وصل کنید و اولین پرداخت را دریافت کنید.