1. Как всё устроено

1. Как всё устроено

ShiftPay принимает оплату от покупателей и зачисляет деньги на баланс вашего магазина. Вы работаете двумя способами:

• **Кабинет** — для людей: смотреть платежи, запрашивать возвраты и выводы, выпускать ключи, настраивать вебхуки, оформление и домены.

• **API** — для вашего сервера: создавать платёжные ссылки, получать статусы, читать баланс.

Путь платежа:

1. Ваш сервер вызывает `POST /payments` и получает `checkout_url`.

1. Вы отправляете покупателя на `checkout_url`. Он выбирает способ оплаты (СБП, карта, криптовалюта и т. д., **зависит от магазина**) и платит.

1. ShiftPay получает подтверждение от платёжного провайдера, записывает проводки и отправляет вам вебхук `payment.succeeded`. Статус платежа становится `paid`.

1. Деньги сначала идут в **холд** (удержание на срок, заданный магазином), затем становятся **доступными**. Часть может уходить в **резерв**.

1. Из доступных средств вы создаёте **вывод**. При необходимости запрашиваете **возврат** покупателю.

Главное правило интеграции: **заказ оплачен только после подтверждённого вебхука `payment.succeeded` и сверки с `GET /payments/{id}`.** Возврат покупателя на ваш сайт после оплаты — не доказательство оплаты.

Основные понятия:

| Понятие | Значение | | --- | --- | | Магазин (проект) | Отдельная настройка: ключи, вебхуки, комиссия, способы оплаты, баланс. Один аккаунт может видеть несколько магазинов. | | Среда | `test` (песочница) или `live` (боевая). Задаётся магазином и ключом, не параметром запроса. | | Ключ API | Пара: ID ключа и секрет. Секрет подписывает запросы. Показывается один раз. | | Секрет вебхука | Отдельный секрет для проверки входящих уведомлений. Не равен секрету API-ключа. | | Idempotency-Key | Ключ повторяемой операции. Один и тот же ключ даёт тот же результат, а не второй платёж. | | Холд / резерв | Удержания на балансе, см. [раздел 10](#10-деньги-баланс-холд-резерв-комиссия). |

---