Платёжный провайдер
Что такое merchant of record и как Paddle Billing моделирует то, что продаёт, свои окружения API и вебхуки.
Как это описывает Paddle
Предметная область в том виде, в каком её публикует Paddle. Эта страница не описывает какое-либо конкретное приложение; каждое утверждение пересказывает публичную документацию из раздела Источники.
Коротко
- Paddle выступает merchant of record: покупатель покупает у Paddle.
- Paddle Billing моделирует продукты, цены, покупателей, транзакции, подписки и корректировки.
- Песочница и боевой режим — отдельные аккаунты со своими ключами, данными и панелями.
- Paddle отправляет подписанные уведомления; доставка успешна, только если получатель ответил HTTP 200 в течение пяти секунд.
Merchant of record
- Merchant of record — юридический продавец в сделке.
- Paddle выступает им: покупатель покупает у Paddle, который перепродаёт программный продукт от имени вендора.
- Поэтому Paddle рассчитывает, собирает и перечисляет налог с продаж и НДС, проводит платёж, выставляет инвойс, обрабатывает возвраты, чарджбэки и мошенничество и выплачивает вендору деньги за вычетом своих комиссий.
Модель Paddle Billing
- Product — что продаётся, с налоговой категорией (например standard или software as a service), от которой зависит применение налога.
- Price — сумма и валюта для продукта, разовая или периодическая.
- Customer — покупатель, с адресами и компаниями.
- Transaction — один checkout или инвойс: позиции, итоги с налогом и платежи по нему.
- Subscription — периодическое соглашение, которое создаёт транзакции в каждом расчётном цикле.
- Adjustment — изменение завершённой транзакции: возврат или кредит.
Checkout работает в браузере через Paddle.js (overlay или встроенный фрейм) и открывается для транзакции.
До первой транзакции
Прежде чем создавать транзакции, в настройках checkout нужно задать ссылку оплаты по умолчанию (default payment link), а домены, на которых работает checkout, должны быть одобрены.
API и окружения
- REST API аутентифицируется API-ключом, который передаётся как bearer token. Права ключа задаются по сущностям.
- Песочница и боевой режим — отдельные аккаунты со своими ключами, данными и панелями: API песочницы —
sandbox-api.paddle.com, боевой API —api.paddle.com. - В песочнице тестовые карты Paddle проводят checkout без движения денег.
Вебхуки
- Paddle отправляет уведомления о событиях, например
transaction.completedилиadjustment.updated, в назначения уведомлений (notification destinations), настроенные в аккаунте; у каждого назначения свой секретный ключ. - Каждое уведомление несёт заголовок
Paddle-Signatureс меткой времени и подписью HMAC-SHA256 от метки времени и сырого тела запроса, сделанной секретным ключом назначения. Получатель пересчитывает её и отклоняет несовпадение или устаревшую метку времени. - Неудачное уведомление можно повторно отправить из панели.
Ответ за пять секунд
Доставка считается успешной, только если получатель ответил HTTP 200 в течение пяти секунд; любой другой исход повторяется по расписанию (несколько попыток за минуты в песочнице, много попыток за дни в боевом режиме).
В этом разделе
- Merchant of record — что такое merchant of record и какие обязательства он берёт на себя
- Факты о Paddle — предварительные условия, ключи и версии, песочница, транзакции, подписи и повторы вебхуков