PHP-магазин подарочных карт: интеграция FazerCards API с нуля

PHP остаётся языком длинного хвоста интернета — шаред-хостинг, бюджетные VPS, унаследованные стеки. Где бы реселлер ни запускал свой магазин сегодня, PHP, скорее всего, уже работает рядом. В этом руководстве мы шаг за шагом подключим FazerCards API к PHP-проекту с нуля: аутентифицируем запросы, получим живой каталог подарочных карт, разместим реальный заказ и проверим webhook-обратные вызовы, которые доставляют коды покупателям в момент завершения покупки. Пакеты Composer не нужны — каждый вызов использует встроенные функции cURL в PHP, что сводит зависимости к нулю. Если ваш магазин уже работает на WordPress, быстрее пойти по руководству для WooCommerce; этот разбор — для собственного PHP-кода.

Требования

Прежде чем писать первую строку PHP, убедитесь, что у вас есть:

• Аккаунт FazerCards с активным API-ключом. Бесплатный 5-дневный Gold-триал даёт полный доступ к API и реальному каталогу с первого дня — без банковской карты.
• PHP 8.0 или выше с расширениями curl и json (оба идут в стандартной поставке на большинстве шаред-хостингов и VPS).
• Публично доступный URL для получения webhook-событий. На этапе разработки подойдёт локальный туннель.
• API-ключ, сохранённый в переменной окружения или конфигурационном файле за пределами корневой директории сайта — никогда не в исходном коде.

Шаг 1: создайте вспомогательную функцию для API

Каждый запрос к FazerCards объединяют две константы: базовый URL https://api.fzr.cards/api/v2 и заголовок X-Api-Key с вашим секретным ключом. Одна вспомогательная функция, которая инкапсулирует их, сделает все остальные файлы чище.

Напишите функцию fzr_request, принимающую строку метода HTTP, строку пути, опциональный массив тела запроса и опциональный массив дополнительных заголовков — он понадобится для Idempotency-Key на шаге 3. Внутри инициализируйте дескриптор cURL, указывающий на конкатенацию базового URL с путём, включите CURLOPT_RETURNTRANSFER и прикрепите заголовки X-Api-Key и Content-Type: application/json. Для POST-запросов установите CURLOPT_POST, закодируйте тело через json_encode и передайте в CURLOPT_POSTFIELDS. Установите CURLOPT_TIMEOUT, чтобы зависший вызов не подвесил оформление заказа, выполните запрос, проверьте HTTP-статус, прежде чем доверять телу, затем декодируйте ответ через json_decode и верните массив.

Эта одна функция обрабатывает каждый эндпоинт из следующих шагов. Все ответы FazerCards — JSON; отдельного рукопожатия или обмена токенами для аутентификации не требуется.

Шаг 2: получите каталог подарочных карт

Каталог разделён по типам продуктов. Для подарочных карт начните с GET /giftcards — в ответе список категорий с category_id, названием и метаданными. Когда покупатель выбирает категорию (например, PlayStation или Google Play), вызовите GET /giftcards/cards с параметром category_id, чтобы получить доступные предложения. Каждое предложение содержит card_id, price_usd и количество в наличии.

Кешируйте список категорий на сервере — он меняется редко, а лишний запрос на каждую загрузку страницы заметно сказывается на скорости. PHP-файловый кеш или Redis-ключ с коротким TTL вполне подойдут; список предложений можно обновлять при каждом запросе, так как цены и остатки меняются быстрее. Отображайте категории в виде выпадающего списка, а предложения — в виде карточек или переключателей.

FazerCards охватывает подарочные карты, пополнения игровых счетов, игровые ключи и многое другое — 10 000+ продуктов. Тот же fzr_request работает с каталогом пополнений (GET /topups) и каталогом игровых ключей (GET /gamekeys) — просто смените путь.

Шаг 3: разместите заказ

Когда покупатель подтверждает выбор, вызовите POST /giftcards/order с тремя полями тела: category_id, card_id и quantity. В ответе — объект заказа с его id и status. Мгновенные продукты возвращают status: completed с кодами прямо в теле ответа — ждать не нужно. Немгновенные продукты начинаются со status: processing и завершаются через webhook-событие.

К каждому POST-запросу заказа добавляйте заголовок Idempotency-Key — ключ создавайте один раз на оформление заказа — UUID или хеш ID корзины — и храните вместе с корзиной, чтобы каждый повтор этого оформления отправлял тот же ключ. Если покупатель отправит форму дважды или сервер повторит запрос после сетевого сбоя, FazerCards вернёт исходный заказ, а не спишет деньги повторно. Ключи хранятся семь дней. Этот один заголовок устраняет целый класс ошибок с дублирующимися списаниями без дополнительного состояния на сервере.

Для пополнений и игровых ключей пути эндпоинтов отличаются (POST /topups/order, POST /gamekeys/order), но та же вспомогательная функция, тот же паттерн идемпотентности и те же четыре статуса применимы везде. Подробности — в документации API.

Шаг 4: доставьте коды и обработайте асинхронные заказы

Для мгновенных продуктов берите коды напрямую из ответа завершённого заказа. Для обрабатываемых вызывайте GET /orders/ с ID заказа, чтобы проверить текущий status. Возможные статусы — только четыре: processing, completed, failed и refund — не «pending» и не «delivered». Когда status меняется на completed, тот же эндпоинт возвращает коды.

Создайте простую страницу статуса для покупателя, которая раз в несколько секунд опрашивает эндпоинт заказа через JavaScript, или откажитесь от опроса в пользу webhook-событий — это шаг 5.

Шаг 5: проверяйте подписи webhook перед обработкой событий

Зарегистрируйте URL webhook в панели управления FazerCards. По заказам платформа отправляет два типа событий: order.created и order.status_changed. Тело события минимально — order_id, type, status и previous_status — и не содержит кодов. Когда status равен completed, запросите коды через эндпоинт заказов.

Перед обработкой любого входящего события проверьте его источник. FazerCards прикрепляет заголовок X-Webhook-Signature в формате sha256= и далее hex-значение. Воспроизведите его на сервере: вычислите HMAC-SHA256 от сырого тела запроса с вашим секретом webhook, закодируйте результат в hex и добавьте префикс sha256=. В PHP прочитайте сырое тело через file_get_contents('php://input') до того, как его разберёт фреймворк, вычислите дайджест через hash_hmac('sha256', $rawBody, $secret) и сравнивайте через hash_equals — сравнение за постоянное время предотвращает атаки по времени. При неверной подписи возвращайте HTTP 401 и не обрабатывайте событие.

Недоставленные события повторяются через 1, 5 и 30 минут с тем же event_id, поэтому обработчик должен быть идемпотентным: логируйте обработанные ID событий и пропускайте дубликаты. В документации по webhook — полная схема событий, в кулинарной книге API — рабочие примеры на curl, Node.js, Python и Go, которые один к одному переносятся на вызовы cURL в PHP. Подробнее о построении надёжных потоков доставки — в руководстве по интеграции API.

Что у вас теперь есть

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

Готовы к запуску? На странице тарифов FazerCards показано, что открывает каждый план, а бесплатный 5-дневный Gold-триал даёт полный API, полный каталог и мгновенную доставку — чтобы протестировать PHP-магазин в реальных условиях до первого платежа.