Демоверсия

API платежей для туризма

API платёжного шлюза для бронирования путешествий: от оплаты до возврата

API платёжного шлюза позволяет сайту бронирования принимать деньги путешественника, не касаясь данных карты. На этой странице разобраны вызовы одного карточного платежа, статусы, через которые проходит платёж, чем платежи в туризме сложнее розничных и как PHPTRAVELS подключает ваш процесс бронирования к выбранному шлюзу.

  • Сессия, 3-D Secure, списание
  • Все статусы платежа
  • Карты, кошельки, банк, кредит
  • Данных карты нет на вашем сервере

Как работают вызовы

Один карточный платёж, вызов за вызовом

API платёжного шлюза — это набор веб-сервисов, которые платёжная компания открывает для мерчантов. Ваш сервер просит создать платёж на сумму в нужной валюте, путешественник вводит карту в форме самого шлюза, а шлюз общается с платёжной сетью и банком-эмитентом. Ваш сервер никогда не видит номер карты: он получает ID платежа и статус.

В процессе участвуют четыре стороны. На схеме они показаны колонками, а каждое сообщение — пронумерованной стрелкой. У разных шлюзов названия различаются (payment intent, session, order, charge), но последовательность одна и та же.

Путешественник оплачивает поездку онлайн, а сайт бронирования, платёжный шлюз и банк обмениваются платёжными сообщениями

Пунктирная стрелка — это вебхук: шлюз сам обращается к вашему серверу, поэтому платёж обновит бронирование, даже если путешественник закрыл браузер. Как каждый шаг связывается с бронированием в PHPTRAVELS, описано на странице «Интеграция платёжных шлюзов».

  • Путешественник
  • Ваш сайт
  • Шлюз
  • Платёжная сеть / банк

  1. 01ОформлениеПутешественник Ваш сайт

    Путешественник проверяет поездку и нажимает «Оплатить». Бронь удерживается у поставщика, но ещё не подтверждена.

  2. 02Создание payment intent или сессииВаш сайт Шлюз

    Ваш сервер отправляет сумму, валюту, номер брони и ключ идемпотентности вместе с секретным API-ключом. Шлюз возвращает ID платежа.

  3. 03Размещённые поля или редиректШлюз Путешественник

    Форму карты отдаёт шлюз, внутри вашей страницы или на отдельной, поэтому данные карты уходят прямо к нему.

  4. 043-D SecureПлатёжная сеть / банк Путешественник

    Если банк-эмитент требует, путешественник подтверждает платёж в банковском приложении или одноразовым кодом.

  5. 05АвторизацияШлюз Платёжная сеть / банк

    Шлюз через платёжную сеть просит эмитента одобрить сумму.

  6. 06Одобрено, средства заблокированыПлатёжная сеть / банк Шлюз

    Эмитент резервирует деньги на карте. Фактически ничего ещё не списано.

  7. 07Результат на ваш сайтШлюз Ваш сайт

    Путешественник возвращается на сайт с ID платежа. Сервер читает статус через API и подтверждает бронь у поставщика.

  8. 08СписаниеВаш сайт Шлюз

    Когда поставщик подтвердил, сервер списывает всю сумму или меньшую. Многие шлюзы умеют списывать и сразу.

  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 платёжного шлюза устроен так, чтобы этого и не требовалось.

  • Не храните номера карт

    Данные карты уходят шлюзу, который возвращает токен или ID платежа. В вашей базе лежит только эта ссылка, но не номер карты и не код безопасности.

  • Размещённые поля и редиректы сокращают область PCI DSS

    PCI DSS распространяется на всех, кто обрабатывает данные карт. Если форма карты — страница шлюза или его встроенные поля, в область попадает гораздо меньше вашей системы. Какой вариант самооценки вам подходит, подтвердит ваш эквайер.

  • Вебхуки проверяются по подписи

    Каждый вебхук содержит подпись, созданную на общем секрете. Сервер пересчитывает её и отклоняет любое событие с несовпадением, так что оплаченную бронь подделать нельзя.

  • Секретные ключи остаются на сервере

    Браузер получает только публичный ключ. Секретный ключ, который создаёт платежи и возвраты, хранится в настройках сервера, а каждый запрос несёт ключ идемпотентности, поэтому повтор не спишет деньги дважды.

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, которые подключает PHPTRAVELS, перечислены на странице «Travel API».

Попробовать живое демоСравнить тарифыЧитать документацию для разработчиков

FAQ

API платёжного шлюза: вопросы продавцов путешествий

Отдел продаж

Это набор веб-сервисов платёжной компании, с помощью которого сайт создаёт платежи, отправляет карту в банк на одобрение, списывает деньги, делает возвраты и получает уведомления о статусах через вебхуки, не храня данные карт у себя.

Шлюз — это часть, с которой общается ваш сайт: он безопасно собирает данные карты и передаёт запрос дальше. Процессор проводит транзакцию через платёжные сети к банку-эмитенту. Многие провайдеры предлагают оба в одном сервисе.

Тот, что одобрит ваш бизнес, поддерживает страны, валюты и способы оплаты ваших клиентов и умеет раздельную авторизацию и списание, а также частичные возвраты. Многие агентства сочетают глобальный карточный шлюз с региональным.

Авторизация резервирует сумму на карте путешественника, списание её забирает. Разделив их, вы берёте деньги только после подтверждения брони поставщиком и снимаете блокировку, если подтверждения нет.

Во многих регионах, включая Европейскую экономическую зону и Великобританию, для большинства онлайн-платежей картой требуется строгая аутентификация клиента, и карты соответствуют ей через 3-D Secure. Проверку выполняет API шлюза, а ваш процесс бронирования ждёт результата.

Само по себе нет. Размещённые поля или платёжная страница шлюза не пускают данные карт на ваш сервер и сокращают область PCI DSS, но оценку, которую требует эквайер, всё равно нужно пройти.

Да, если шлюз поддерживает частичные возвраты, а большинство карточных шлюзов их поддерживают. Вы отправляете возврат на меньшую сумму по исходному платежу, например стоимость за вычетом штрафа за отмену.

Нет. Мерчант-аккаунт вы открываете у выбранного шлюза и с ним же согласуете комиссии. PHPTRAVELS подключает вашу платформу бронирования к этому аккаунту по API-ключам, которые вы вводите в админке.

Да. Любой шлюз с документированным API можно добавить как индивидуальную интеграцию, а поскольку исходный код входит в поставку, ваши разработчики могут расширить и сам платёжный процесс.

Узнайте больше

Ещё о платформе