اتصال درگاه پرداخت به سایت؛ وردپرس، PHP و تست قبل از فروش

سایت آماده است، محصول ها بالا رفته اند و دکمه «پرداخت» هنوز به هیچ جا وصل نیست. اتصال درگاه پرداخت به سایت از بیرون کار یک افزونه به نظر میرسد، و برای خیلی از سایت ها هم همین است. ولی جایی که پول واقعاً گم میشود افزونه نیست؛ لحظه ای است که سایت تصمیم میگیرد سفارش پرداخت شده یا نه.

این مقاله برای همان لحظه نوشته شده. اول اینکه پیش از اتصال چه چیزی دستتان باشد، بعد سه قدمی که هر درگاهی دارد، راه وردپرس، راه کدنویسی با PHP یا هر زبان دیگر، و آزمایشی که باید پیش از اولین خریدار واقعی انجام بدهید.

خلاصه ۳۰ ثانیه ای هر درگاهی، شاپرکی یا کارت به کارت، با سه قدم به سایت وصل میشود: سرور سایت درخواست پرداخت میسازد، خریدار به صفحه پرداخت میرود، و سرور سایت پرداخت را از خود درگاه تأیید میکند. در وردپرس این سه قدم را افزونه انجام میدهد و شما فقط کلیدها را میچسبانید. در سایت اختصاصی خودتان مینویسیدشان. برگشت خریدار به سایت مدرک پرداخت نیست.

پیش از وصل کردن، چه چیزی باید دستتان باشد؟

اول خود درگاه. حسابی که کلید اتصال میدهد، پیش از هر خط کدی باید باز شده باشد، و هر نوع درگاه شرط خودش را دارد. درگاه شاپرکی، چه از یک PSP و چه از یک پرداخت یار، معمولاً نماد اعتماد الکترونیکی و کد رهگیری مالیاتی میخواهد. اگر هنوز ندارید، درگاه بدون اینماد و درگاه پرداخت بدون کد مالیاتی را بخوانید، و برای انتخاب بین شرکت ها بهترین درگاه پرداخت را. درگاه کارت به کارت هیچ کدام از این دو را نمیخواهد و حسابش همان روز باز میشود.

حساب که باز شد، چند چیز تحویل میگیرید و هر کدام جای مشخصی در سایت دارد:

چیزی که از درگاه میگیرید	کجای سایت میرود	نکته اش
کلید API یا شناسه پذیرنده	تنظیمات افزونه، یا متغیر محیطی سرور	هیچ وقت در کد سمت مرورگر
کلید امضای وب هوک	فقط سرور	با آن میفهمید پیام واقعاً از درگاه آمده
آدرس وب هوک	در درخواست پرداخت یا پنل درگاه	معمولاً HTTPS میخواهد
آدرس برگشت خریدار	صفحه «سفارش ثبت شد»	مدرک پرداخت نیست
کلید یا حالت تست	محیط آزمایشی سایت	پیش از کلید واقعی

اتصال درگاه پرداخت به سایت سه قدم دارد، با هر درگاهی

اسم ها فرق میکند ولی ترتیب همیشه یکی است.

اول، سرور سایت از درگاه درخواست پرداخت میسازد: مبلغ، شماره سفارش خودتان و آدرسی که خبر پرداخت باید به آن برسد. درگاه یک شناسه و یک نشانی صفحه پرداخت پس میدهد. این کار باید از سرور انجام شود، نه از مرورگر خریدار، چون کلید API فقط روی سرور است.

بعد خریدار را به همان صفحه میفرستید. در درگاه شاپرکی آنجا صفحه بانکی است با شماره کارت، CVV2 و رمز دوم پویا. در درگاه کارت به کارت صفحه ای است که شماره کارت شما و مبلغ دقیق را نشان میدهد و خریدار از اپ بانک خودش انتقال میدهد.

و آخر، سرور شما پرداخت را از خود درگاه تأیید میکند و فقط بعد از آن سفارش را جلو میبرد. دو راه دارد: درگاه با پیام امضا شده خبر میدهد، که اسمش وب هوک یا کال بک است، یا سرور شما خودش میپرسد. در درگاه کارت به کارت آبان گیت وی این خبر وقتی میرسد که پیامک واریز بانک با فاکتور تطبیق خورده؛ روشش را در تأیید خودکار کارت به کارت نوشته ایم.

قدم سوم را جا نیندازید. برگشت خریدار به سایت جای آن را نمیگیرد.

در وردپرس و ووکامرس، وصل کردن درگاه چقدر کار دارد؟

کمتر از آنچه فکر میکنید، چون هر سه قدم را افزونه انجام میدهد. افزونه درگاه را نصب و فعال میکنید، در تنظیمات پرداخت ووکامرس روشش را روشن میکنید و کلید API و کلید امضای وب هوک را از پنل درگاه میچسبانید. بعد یک سفارش آزمایشی میزنید و پرداختش میکنید تا ببینید وضعیت سفارش خودش عوض میشود.

یک فروشگاه میتواند چند روش پرداخت کنار هم داشته باشد و خریدار در صفحه تسویه انتخاب کند؛ مثلاً درگاه شاپرکی برای کسی که به صفحه بانک عادت دارد و کارت به کارت برای بقیه. جزئیات افزونه کارت به کارت، از آپلود فیش تا تأیید خودکار، و اشتباه ریال و تومان که مبلغ را ده برابر میکند، در افزونه کارت به کارت ووکامرس آمده.

سایت اختصاصی دارید؟ وصل کردن با API در PHP یا هر زبانی

در سایت اختصاصی همان سه قدم را خودتان مینویسید و زبانش فرقی نمیکند. در آبان گیت وی شکلش این است.

قدم اول یک درخواست از سرور است. مبلغ به ریال میرود، شماره سفارش خودتان برای پیدا کردنش در خبر بعدی، آدرس وب هوک که HTTPS باشد، و آدرسی که خریدار بعد از پرداخت به آن برمیگردد:

curl -X POST https://api.abangateway.ir/api/v1/invoices \
  -H "Authorization: Bearer ag_test_..." \
  -H "Content-Type: application/json" \
  -d '{"amount_rial": 4800000, "order_id": "ORD-1043",
       "callback_url": "https://shop.example/hook",
       "return_url": "https://shop.example/thanks"}'

پاسخ یک payment_url دارد. خریدار را به آن بفرستید. اگر مبلغ را جایی خودتان نشان میدهید، payable_rial را نشان بدهید، چون ممکن است چند ریال با مبلغی که خواسته اید فرق داشته باشد و همان فرق است که واریز این خریدار را از خریدار همزمان دیگری جدا میکند.

قدم سوم دو قسمت است. وقتی خبر پرداخت به آدرس وب هوک رسید، اول امضایش را با کلید امضا روی بایت های خام بدنه چک کنید:

<?php
$raw  = file_get_contents('php://input');
$sent = $_SERVER['HTTP_X_SIGNATURE'] ?? '';
$mine = hash_hmac('sha256', $raw, ABANGATE_WEBHOOK_SECRET);
if (!hash_equals($mine, $sent)) { http_response_code(401); exit; }

بعد سفارش را با درخواست verify همان فاکتور تحویل بدهید. این درخواست را طوری ساختیم که فقط یک بار موفق شود؛ اگر دو خبر همزمان برسند، یکی موفق میشود و دیگری جواب «قبلاً تأیید شده» میگیرد، که باید آن را موفقیت حساب کنید نه خطا. دلیلش ساده است: درگاه اگر جواب شما گم شود دوباره خبر میفرستد، و سفارش نباید دو بار ارسال شود. خبرهای ناموفق تا پنج بار تکرار میشوند، با فاصله هایی از ده ثانیه تا یک ساعت.

اشتباه رایج: سفارش را از روی برگشت خریدار تأیید نکنید

این خطا را در سایت های زیادی میشود دید. خریدار بعد از پرداخت به آدرس برگشت میآید، سایت میبیند او برگشته و سفارش را «پرداخت شده» میکند. ولی آن آدرس را هر کسی میتواند خودش باز کند، با یا بدون پرداخت. سفارش فقط وقتی پرداخت شده است که سرور شما از خود درگاه شنیده باشد: یا با وب هوکی که امضایش درست است، یا با پرسیدن وضعیت از درگاه.

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

قبل از فروش واقعی، درگاه را چطور تست کنیم؟

با کلید تست. در آبان گیت وی کلیدی که با ag_test_ شروع میشود فاکتور میسازد، صفحه پرداخت را باز میکند و وب هوک میفرستد، ولی پولی جابجا نمیشود و کارمزدی کم نمیشود. یک درخواست جدا هم دارد که پرداخت را بدون واریز واقعی شبیه سازی میکند. درگاه های دیگر هم معمولاً محیط آزمایشی دارند؛ اسم و شکلش را از راهنمای همان درگاه بپرسید.

یه نکته ریز: فقط پرداخت موفق را تست نکنید. این حالت ها را هم یک بار ببینید:

• فاکتوری که مهلتش تمام میشود و سفارشی که باید باز بماند؛
• فاکتوری که لغو میشود؛
• خبری که دو بار میرسد و سفارشی که نباید دو بار ارسال شود؛
• خبری با امضای غلط، که سایت باید ردش کند.

پنج حالتی که پیش از اولین خریدار واقعی باید دیده باشید.

بعد کلید تست را با کلید واقعی عوض کنید و یک خرید کوچک واقعی بزنید. همین یک خرید چیزهایی را نشان میدهد که تست نشان نمیدهد، مثل پیامکی که به گوشی متصل نمیرسد.

یک درگاه کافی است یا دو تا؟

راستش برای بیشتر سایت های تازه، درگاهی که همین امروز باز میشود بهتر از درگاهی است که دو ماه بعد میرسد. کارت به کارت اینماد و کد رهگیری نمیخواهد و پول همان لحظه روی کارت خودتان مینشیند. ولی محدودیت هایش را هم باید گفت. خریدار باید از اپ بانک خودش انتقال بدهد، نه از روی صفحه سایت. سقف کارت به کارت روزانه ۱۵ میلیون تومان برای هر کارت است. و گوشی ای لازم دارید که پیامک واریز را بگیرد.

وقتی اینماد و کد رهگیری آمد، درگاه شاپرکی را کنارش اضافه کنید. پولش با تسویه میرسد، معمولاً در چرخه بامداد روز کاری بعد، ولی خریداری که فقط صفحه بانک را میشناسد هم گزینه دارد. هزینه هر دو را، از کارمزد درصدی تا ثابت، در درگاه پرداخت رایگان کنار هم گذاشته ایم.

سؤالات متداول

برای وصل کردن درگاه به سایت برنامه نویس لازم دارم؟

برای وردپرس و ووکامرس نه؛ افزونه و چند دقیقه تنظیم کافی است. برای سایت اختصاصی، کسی که کد سرور را میشناسد باید سه قدم بالا را بنویسد. بخش سختش نه ساختن درخواست است، نه فرستادن خریدار؛ چک کردن امضا و تحویل یک باره سفارش است.

تغییر درگاه پرداخت سایت چطور است؟

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

میشود روی یک سایت دو درگاه پرداخت داشت؟

بله. در ووکامرس هر درگاه یک روش پرداخت جداست و خریدار انتخاب میکند. در سایت اختصاصی هم هر درگاه آدرس وب هوک و کلید خودش را دارد؛ آن ها را قاطی نکنید.

آدرس وب هوک حتماً باید HTTPS باشد؟

در آبان گیت وی بله، و در بیشتر درگاه ها هم همین است. خبر پرداخت نباید روی ارتباط باز رد و بدل شود. اگر سایت گواهی SSL ندارد، اول همین را درست کنید.

برای سایت شخصی هم درگاه وصل میشود؟

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

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