API до того, как он вышел.

Что уже решено

• Идемпотентность на каждой мутации

  Заголовок Idempotency-Key на всех публичных мутациях и идентификатор корреляции, который проходит от начала операции до вебхука, который вы получите. Повторить запрос всегда безопасно.

• Вебхуки, которые нельзя потерять

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

• Деньги в целых минорных единицах

  Суммы идут по проводу целыми числами с явным числом знаков для каждого токена. Никаких дробных чисел с плавающей точкой ни в одну сторону: ваша сторона форматирует, наша считает.

• Неудачные состояния — полноправные

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

• Источник правды — OpenAPI

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

• API-ключи не подписывают

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