دموی زنده

API پرداخت سفر

API درگاه پرداخت برای رزرو سفر: از تسویه تا بازپرداخت

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

  • نشست، 3-D Secure، برداشت
  • همه وضعیت‌های پرداخت
  • کارت، کیف پول، بانک، اعتبار
  • بدون داده کارت روی سرور شما

فراخوانی‌ها چگونه کار می‌کنند

یک پرداخت با کارت، فراخوانی به فراخوانی

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

چهار طرف در کار هستند. نمودار آن‌ها را به صورت ستون و هر پیام را به صورت پیکانی شماره‌دار نشان می‌دهد. نام‌ها از درگاهی به درگاه دیگر فرق می‌کند (payment intent، نشست، سفارش، charge) اما ترتیب یکی است.

مسافری که آنلاین هزینه سفر را می‌پردازد، در حالی که سایت رزرو، درگاه پرداخت و بانک پیام‌های پرداخت رد و بدل می‌کنند

پیکان خط‌چین یک وب‌هوک است: درگاه خودش به سرور شما زنگ می‌زند، پس حتی اگر مسافر مرورگر را ببندد پرداخت رزرو را به‌روز می‌کند. صفحه یکپارچه‌سازی درگاه پرداخت توضیح می‌دهد هر مرحله در PHPTRAVELS چگونه به رزرو گره می‌خورد.

  • مسافر
  • سایت شما
  • درگاه
  • شبکه کارت / بانک
  1. 01تسویهمسافر سایت شما

    مسافر سفر را مرور می‌کند و پرداخت را می‌زند. رزرو نزد تأمین‌کننده نگه داشته می‌شود، هنوز تأیید نشده است.

  2. 02ایجاد payment intent یا نشستسایت شما درگاه

    سرور شما مبلغ، ارز، شناسه رزرو و یک کلید idempotency را با کلید API محرمانه‌اش می‌فرستد. درگاه شناسه پرداخت را برمی‌گرداند.

  3. 03فیلدهای میزبانی‌شده یا تغییر مسیردرگاه مسافر

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

  4. 043-D Secureشبکه کارت / بانک مسافر

    اگر بانک صادرکننده بخواهد، مسافر پرداخت را در اپ بانکی یا با رمز یک‌بارمصرف تأیید می‌کند.

  5. 05تأیید (Authorise)درگاه شبکه کارت / بانک

    درگاه از صادرکننده می‌خواهد از طریق شبکه کارت مبلغ را تأیید کند.

  6. 06تأیید شد، مبلغ مسدود شدشبکه کارت / بانک درگاه

    صادرکننده پول را روی کارت رزرو می‌کند. هنوز چیزی جابه‌جا نشده است.

  7. 07نتیجه به سایت شمادرگاه سایت شما

    مسافر با شناسه پرداخت به سایت شما برمی‌گردد. سرور شما وضعیت را از API می‌خواند و رزرو را نزد تأمین‌کننده تأیید می‌کند.

  8. 08برداشت (Capture)سایت شما درگاه

    وقتی تأمین‌کننده تأیید کرد، سرور شما کل مبلغ یا مبلغی کمتر را برداشت می‌کند. بسیاری از درگاه‌ها می‌توانند بلافاصله هم برداشت کنند.

  9. 09وب‌هوکدرگاه سایت شماخود درگاه ارسال می‌کند

    درگاه رویدادی امضاشده (پرداخت برداشت شد، بازپرداخت شد، اعتراض شد) به نقطه پایانی شما می‌فرستد. سرور شما امضا را بررسی و رزرو را به‌روز می‌کند.

وضعیت‌های پرداخت

چرخه عمر پرداخت به‌صورت ماشین حالت

هر API درگاه برای هر پرداخت یک وضعیت گزارش می‌کند. واژه‌ها فرق می‌کنند اما همگی به همان چند حالت برمی‌گردند و منطق رزرو شما باید به هریک واکنش نشان دهد.

  1. created

    ایجادشده

    پرداخت با مبلغ و ارز وجود دارد و منتظر مسافر است.

    failedنهایی

    ناموفق

    رد شده، 3-D Secure کامل نشده یا رها شده است. هیچ مبلغی کسر نمی‌شود.

  2. authorized

    تأییدشده

    صادرکننده مبلغ را تأیید کرده و روی کارت نگه داشته است.

    voidedنهایی

    ابطال‌شده

    مسدودی پیش از برداشت لغو می‌شود، پس مسافر هرگز پولی نمی‌پردازد.

  3. captured

    برداشت‌شده

    پول برداشت شده و به حساب پذیرنده شما تسویه می‌شود.

    partially_refundedنهایی

    بازپرداخت جزئی

    بخشی از مبلغ برداشت‌شده برمی‌گردد، مثلاً پس از کسر جریمه لغو.

    refundedنهایی

    بازپرداخت‌شده

    کل مبلغ برداشت‌شده به کارت برمی‌گردد.

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

چرا سفر دشوارتر است

چرا پرداخت‌های سفر فرق می‌کنند

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

  • 01

    حالا تأیید، بعداً برداشت

    هتل‌های «بر اساس درخواست»، نرخ گروهی و تورها ساعت‌ها یا روزها پس از سفارش تأیید می‌شوند. اول تأیید و هنگام تأیید رزرو برداشت یعنی برای رزروی که انجام نمی‌شود پولی کسر نمی‌شود.

  • 02

    تأمین‌کننده هنوز می‌تواند نه بگوید

    ممکن است نرخی بین پرداخت و صدور بلیت تمام شود. با تأیید اولیه، پول با ابطال آزاد می‌شود؛ پس از برداشت، به بازپرداخت تبدیل می‌شود.

  • 03

    بازپرداخت جزئی پس از جریمه لغو

    لغو اقامت یا بلیت معمولاً جریمه‌ای دارد. فراخوانی بازپرداخت مبلغی کمتر را در برابر پرداخت اصلی می‌فرستد، هر چند بار که قوانین ایجاب کند.

  • 04

    چندارزی

    مسافران به ارز خود می‌پردازند در حالی که تأمین‌کنندگان به ارز خود صورتحساب می‌دهند. درگاه باید ارز نمایش را پشتیبانی کند و سوابق شما باید هر دو مبلغ را نگه دارد.

  • 05

    بررسی تقلب برای مبالغ بالا

    بلیت برای فردا، برای شخصی دیگر، با کارتی جدید: الگوی کلاسیک تقلب. 3-D Secure، امتیازدهی ریسک درگاه و صف بررسی دستی از سفارش‌های پرارزش محافظت می‌کنند.

  • 06

    چارج‌بک ماه‌ها بعد

    اعتراض‌ها اغلب پس از سفر می‌رسند. نتیجه احراز هویت، مدارک رزرو و رویدادهای درگاه را کنار هم نگه دارید تا بتوانید با مدرک پاسخ دهید.

روش‌های پرداخت

API درگاه پرداخت کدام راه‌های پرداخت را پوشش می‌دهد

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

روشچیستپول کی می‌رسدبازپرداخت
کارت‌هاکارت‌های نقدی و اعتباری از طریق درگاه، با 3-D Secure در جایی که صادرکننده بخواهد.هنگام تسویه تأیید می‌شود؛ بلافاصله یا وقتی تأمین‌کننده تأیید کرد برداشت می‌شود.بازپرداخت کامل یا جزئی به همان کارت از طریق API.
کیف پول‌های دیجیتالحساب‌های کیف پولی که درگاه پشتیبانی می‌کند، مثل PayPal یا کیف پول موبایلی که کارت توکنی‌شده دارد.هنگام تسویه، پس از تأیید مسافر در کیف پول.از طریق درگاه به کیف پول یا کارت پشت آن برمی‌گردد.
حواله بانکیمسافر یا آژانس پول را به حساب بانکی شما واریز می‌کند و پرداخت روی رزرو ثبت می‌شود.چند روز بعد؛ رزرو منتظر می‌ماند تا تیم شما دریافت را تأیید کند.با حواله و خارج از درگاه بازپرداخت می‌شود.
پرداخت بعدیرزرو همین حالا انجام می‌شود و بعداً پرداخت می‌شود؛ تیم شما پرداخت را وقتی رسید ثبت می‌کند.پس از رزرو، وقتی مسافر می‌پردازد.فقط آنچه واقعاً پرداخت شده برمی‌گردد.
کیف پول یا اعتبار آژانس B2Bزیرآژانس‌ها از موجودی‌ای که از قبل شارژ کرده‌اند یا از سقف اعتباری که شما می‌دهید می‌پردازند.هنگام رزرو کسر می‌شود؛ بیعانه و اعتبار طبق شرایط شما تسویه می‌شود.به موجودی آژانس برمی‌گردد.

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

آماده در PHPTRAVELS

API درگاه‌های پرداخت که از قبل متصل شده‌اند

این درگاه‌ها از قبل به PHPTRAVELS متصل‌اند. نزد ارائه‌دهنده حساب پذیرنده باز می‌کنید، کلیدهای API را در پنل مدیریت وارد می‌کنید، در محیط آزمایشی آن تست می‌کنید و راه‌اندازی می‌شوید. فهرست، همان فهرست زنده دایرکتوری یکپارچه‌سازی‌های ماست.

کارمزدها و تأیید پذیرنده با شرکت پرداخت توافق می‌شود، نه با PHPTRAVELS. درگاهی که اینجا نیست به صورت یکپارچه‌سازی API سفارشی قابل افزودن است و صفحه یکپارچه‌سازی درگاه پرداخت توضیح می‌دهد هر کدام چگونه راه‌اندازی می‌شود.

امنیت

داده کارت را از سیستم خود دور نگه دارید

امن‌ترین شماره کارت شماره‌ای است که سرور شما هرگز دریافت نمی‌کند. API درگاه پرداخت درست برای همین ساخته شده است.

  • هرگز شماره کارت ذخیره نکنید

    اطلاعات کارت به درگاه می‌رود و درگاه توکن یا شناسه پرداخت برمی‌گرداند. پایگاه داده شما فقط همین مرجع را نگه می‌دارد، نه شماره کارت و نه کد امنیتی.

  • فیلدهای میزبانی‌شده و تغییر مسیر دامنه PCI DSS را کوچک می‌کنند

    PCI DSS برای هر کسی که با داده کارت سروکار دارد اعمال می‌شود. وقتی فرم کارت صفحه خود درگاه یا فیلدهای جاسازی‌شده آن باشد، بخش بسیار کمتری از سیستم شما در دامنه قرار می‌گیرد. پذیرنده/بانک شما (acquirer) تأیید می‌کند کدام خوداظهاری برای شما لازم است.

  • وب‌هوک‌ها با امضا راستی‌آزمایی می‌شوند

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

  • کلیدهای محرمانه روی سرور می‌مانند

    مرورگر فقط کلید عمومی می‌گیرد. کلید محرمانه‌ای که پرداخت و بازپرداخت ایجاد می‌کند در پیکربندی سرور شماست و هر درخواست یک کلید idempotency دارد تا تلاش مجدد هرگز دو بار کسر نکند.

webhook.php
 1$payload   = file_get_contents("php://input"); 2$signature = $_SERVER["HTTP_X_SIGNATURE"] ?? ""; 3$expected  = hash_hmac("sha256", $payload, $webhookSecret); 4 5if (!hash_equals($expected, $signature)) { 6    http_response_code(400); exit;      // reject 7} 8$event = json_decode($payload, true); 9if (alreadyHandled($event["id"])) exit; // repeat delivery10updateBooking($event["data"]["metadata"]["booking_ref"], $event["type"]);

نمونه عمومی. نام هدرها و روش امضا به درگاهی که انتخاب می‌کنید بستگی دارد.

PHPTRAVELS نرم‌افزار خودمیزبان است، بنابراین انطباق با PCI DSS برای کسب‌وکار و سرور شما ارزیابی می‌شود، نه فقط برای نرم‌افزار.

ببینید رزروی پرداخت، برداشت و بازپرداخت می‌شود

در دموی زنده یک سفر رزرو کنید و پرداخت را در پنل مدیریت دنبال کنید. در طرح Enterprise، PHPTRAVELS REST API و وب‌هوک اختصاصی هم برای اپ‌ها و شرکای شما فراهم می‌کند.

پرواز هم در برنامه دارید؟ صفحه API پرواز سمت تأمین‌کننده را توضیح می‌دهد و APIهای سفر همه APIهایی را که PHPTRAVELS وصل می‌کند فهرست کرده است.

پرسش‌های متداول

API درگاه پرداخت: پرسش‌های فروشندگان سفر

گفتگو با فروش

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

درگاه بخشی است که سایت شما با آن گفت‌وگو می‌کند: کارت را امن جمع می‌کند و درخواست را پیش می‌برد. پردازشگر تراکنش را از شبکه‌های کارت به بانک صادرکننده می‌رساند. بسیاری از ارائه‌دهندگان هر دو را یک‌جا عرضه می‌کنند.

درگاهی که کسب‌وکار شما را بپذیرد، کشورها، ارزها و روش‌های پرداخت مشتریانتان را پشتیبانی کند و تأیید و برداشت جداگانه و بازپرداخت جزئی داشته باشد. بسیاری از آژانس‌ها یک درگاه کارت جهانی را با یک درگاه منطقه‌ای ترکیب می‌کنند.

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

در بسیاری از مناطق، از جمله منطقه اقتصادی اروپا و بریتانیا، احراز هویت قوی مشتری برای بیشتر پرداخت‌های آنلاین با کارت الزامی است و 3-D Secure راهی است که کارت‌ها با آن این الزام را برآورده می‌کنند. API درگاه چالش را مدیریت می‌کند و جریان رزرو شما منتظر نتیجه می‌ماند.

به‌تنهایی نه. استفاده از فیلدهای میزبانی‌شده یا صفحه پرداخت درگاه، داده کارت را از سرور شما دور نگه می‌دارد و دامنه PCI DSS را کوچک می‌کند، اما باید همچنان ارزیابی‌ای را که بانک پذیرنده می‌خواهد کامل کنید.

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

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

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