API, IPN і вебхуки: посібник з інтеграції платежів

Що ти отримаєш

Серверний платіжний процес із захистом повторних спроб і від дублікатів.

1. Підготуй ID і доступ

Почни з увімкненого магазину й перевірених способів оплати. У Налаштування → Доступ API, створи облікові дані читання/запису, обмежені потрібним проєктом. Тримай токен на сервері, ніколи не в коді браузера або публічному репозиторії.

Скопіюй API ID проєкту і API ID магазину із блоку магазину Основне → API ID . Це UUID, а не зрозумілий ідентифікатор проєкту або номер твого замовлення. Використовуй власне ім’я хоста API.

У Магазин → IPN, створи секрет підписання перед передаванням ipn_url. Твій HTTPS-отримувач має бути доступним із VPS мерчанта.

2. Створи рахунок

Заміни заповнювачі й надішли цей запит зі свого серверного застосунку. Суми - десяткові рядки, а не обчислення з рухомою комою.

curl --fail-with-body --request POST \
  'https://api.example.com/v1/projects/YOUR_PROJECT_ID/stores/YOUR_STORE_ID/invoices' \
  --header 'Authorization: Bearer YOUR_MERCHANT_API_TOKEN' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: order-1042-attempt-1' \
  --data '{
  "amount": "10.00",
  "currency": "EUR",
  "order_id": "order-1042",
  "description": "Example order",
  "ipn_url": "https://shop.example.com/payments/wholly-ipn",
  "metadata": {
    "cart_id": "cart-1042"
  }
}'

Збережи data.invoice_id разом із замовленням, а потім переспрямуй клієнта на links.checkout. Використовуй унікальний ключ ідемпотентності для нової спроби оплати. За тайм-ауту повтори запит із тими самими обліковими даними, ключем і точними байтами тіла.

Якщо не вказати payment_methods використовуються прийняті способи магазину. Їх можна звузити для кожного рахунку за slug мереж і тикерами; це ніколи не вмикає неприйнятий актив. Усі поля запиту й приклади відповідей →

3. Обери IPN, вебхуки або обидва

IPN відстежує життєвий цикл рахунку. Установи стандартний URL IPN магазину або перевизнач його через ipn_url для окремого рахунку. Вебхуки підписують кінцеву точку на обрані події, наприклад invoice.settled.

Вони використовують однаковий формат підпису, але різні секрети: IPN використовує секрет IPN магазину; кожна кінцева точка вебхука має власний секрет. Жоден не використовує bearer-токен API для підписання.

Якщо обидва доставляють у твій застосунок, очікуй сповіщень, що перекриваються. Не зараховуй оплату замовлення двічі.

4. Перевір і збережи сповіщення

Прочитай точне сире тіло запиту перед розбором JSON. Перевір Wholly-Signature із відповідним секретом і перевірками часової позначки/повторного відтворення. Офіційні SDK надають засоби перевірки.
Перевір ідентичність проєкту, магазину, рахунку й події в підписаному тілі. Непідписані заголовки доставки не є джерелом автентифікації.
Надійно збережи подію з унікальним event_id, а потім швидко поверни HTTP 2xx. Обробляй замовлення у фоновому обробнику.
Отримуй поточний рахунок із налаштованого хоста API, а не довільного хоста, переданого в запиті. Порівняй збережені проєкт, магазин, суму, валюту й посилання на замовлення.

PHP · Python · JavaScript / TypeScript · Специфікація підпису й приклади отримувача

5. Виконай замовлення один раз після розрахунку

Для подієвого отримувача обробляй event_type = invoice.settled, а потім перевір поточний status = settled і свою політику винятків. Виконуй замовлення один раз у межах транзакції бази даних/обмеження унікальності замовлення.

Тип події й статус - різні речі

Мережа зі швидкою фінальністю може надіслати обидва payment.received і invoice.settled з status = settled. В іншій мережі payment.received може все ще містити processing. Жоден варіант не є помилкою.

Усувай дублікати подій за event_id, а не лише за послідовністю: різні типи подій можуть мати спільну послідовність. Натомість обробники SDK на основі стану об’єднують ревізії рахунку й перевіряють стан незалежно від типу події. Не поєднуй таке об’єднання з фільтром типу події. Обидва підходи все одно потребують захисту від дублікатів на рівні замовлення.

Перевіряй requires_review і ручні рішення перед виконанням замовлення. amount_status = paid сам по собі не доводить підтвердження. Поля оплаченого активу верхнього рівня підсумовують розрахунок; payment_info містить докладні надходження й дані котирування. Усі статуси, події й правила винятків →

6. Перевір повторні спроби й відновлення

Перевір невеликий платіж, повторну доставку, прострочений рахунок і тимчасово недоступного отримувача. Повторне відтворення події не повинно повторно зараховувати оплату замовлення. Обробляй події не за порядком без перезапису новішого стану.

Перевіряй Магазин → IPN / Вебхуки → Історія → Подробиці, або розділи доставки в деталях рахунку. Повторне надсилання використовує записану подію, а не новий розрахунок.

Низький баланс коштів на обробку призупиняє IPN/вебхуки, поки платежі продовжуються. Звіряй незавершені замовлення через API й обробляй збережені доставки після відновлення. Ніколи не виконуй замовлення на підставі переспрямування браузера або знімка екрана клієнта.