Факты о Paddle
Поведение Paddle Billing, которое интеграция должна учесть в точности: предварительные условия аккаунта, API-ключи и версии, отличия песочницы, транзакции и вебхуки.
Как это описывает Paddle
Каждое утверждение на этой странице пересказывает публичную документацию Paddle для разработчиков; источник каждого раздела указан в нём самом и в разделе Источники.
Коротко
- Без default payment link нельзя создать ни одну транзакцию.
- API-ключи — bearer-токены;
Paddle-Version: 1закрепляет запрос за версией API 1. - Массив
paymentsтранзакции отсортирован от самой свежей попытки; корректировки возвращаются только сinclude=adjustments. - Доставка вебхука успешна, только если получатель отвечает HTTP 200 в течение пяти секунд.
Предварительные условия аккаунта
Default payment link
Без ссылки нет транзакций
Без default payment link нельзя создать ни одну транзакцию, включая транзакции с ручной оплатой (счета). (Default payment link)
- Чтобы задать default payment link, сначала должен быть одобрен сайт (Paddle › My account › Settings › Website approval).
- В live-аккаунтах default payment link должен подключать Paddle.js и проходить проверку домена; в песочнице это может быть
localhostили тестовый домен. - Песочница и live настраиваются отдельно. (Default payment link)
Налоговые категории
- У каждого товара есть налоговая категория, например
standard,digital-goodsилиsaas. - Категории, кроме доступной по умолчанию, должны быть одобрены для аккаунта (Paddle › Catalog › Taxable categories).
- Категория, не одобренная для аккаунта, отклоняется ошибкой
product_tax_category_not_approved. (Tax category not approved, Paddle Billing: what you need to know)
API-ключи и версии
Формат ключа
API-ключ передаётся как bearer-токен: Authorization: Bearer <key>. Ключи начинаются с pdl_, содержат live_ или sdbx_ по окружению и apikey_ и имеют длину 69 символов. (Authentication)
Права и срок действия
- Ключ можно ограничить конкретными правами; Paddle рекомендует минимум, нужный интеграции.
- Срок действия необязателен, но рекомендуется: по умолчанию 90 дней, максимум один год с момента создания.
- Истёкший ключ нельзя использовать повторно. (Authentication)
Версии
Paddle-Version: 1закрепляет запрос за версией API 1 — текущей.- Без заголовка действует версия аккаунта по умолчанию; интеграции никогда не обновляются автоматически.
- У адресатов вебхуков своя настроенная версия. (Versioning)
Песочница и live
| Песочница | Live | |
|---|---|---|
| Базовый URL API | https://sandbox-api.paddle.com | https://api.paddle.com |
| Учётные данные, данные, панель | Отдельные | Отдельные |
| Карты | Только тестовые; настоящие отклоняются | Только настоящие; тестовые не работают |
| Одобрение домена checkout | Проверка не требуется | Требуется одобрение |
| Возвраты | Одобряются автоматически примерно каждые 10 минут | Большинство требует одобрения Paddle |
| Повторы вебхуков | 3 за 15 минут | 60 за 3 дня |
(Sandbox)
Транзакции и корректировки
- Массив
paymentsтранзакции отсортирован поcreated_atпо убыванию: первой идёт самая свежая попытка оплаты. (Get a transaction) - Связанные сущности возвращаются только по запросу через
include; допустимые значения —address,adjustments,adjustments_totals,available_payment_methods,business,customerиdiscount. (Get a transaction)
Корректировкам нужен include
Поэтому корректировки — возвраты и кредиты по завершённой транзакции — возвращаются только с include=adjustments. (Get a transaction)
Вебхуки
Подпись
- Каждое уведомление несёт заголовок
Paddle-Signatureвидаts=<unix timestamp>;h1=<signature>. - Подпись — это HMAC-SHA256 от
<ts>:<raw body>, сделанный секретным ключом адресата уведомлений; у каждого адресата свой ключ. (Signature verification)
Проверка подписи
Получатель пересчитывает подпись по неизменённому сырому телу, сравнивает за постоянное время и сверяет метку времени с текущим временем; рекомендуемый Paddle допуск, который соблюдают его SDK, — пять секунд. (Signature verification)
Доставка
- Доставка успешна, только если получатель отвечает HTTP 200 в течение пяти секунд, поэтому обработчик отвечает до своей обработки.
- Любой другой исход повторяется с экспоненциальной задержкой (база 60 секунд, множитель 1,1): 3 раза за 15 минут в песочнице, 60 раз за 3 дня в live (20 попыток в первый час, 47 в первые сутки).
- Когда попытки исчерпаны, статус уведомления становится
failed. (Respond to webhooks)
Повторная отправка
- Уведомление в статусе
failedилиdeliveredможно отправить заново операцией replay notification. - Уведомления хранятся не больше 90 дней. (Respond to webhooks, Replay a notification)