Платёжные коннекторы
Приём оплат и сделок из внешних систем: готовые коннекторы и собственный вебхук.
Вознаграждение партнёру начисляется за оплаченный заказ, а не за заявку. Recca узнаёт об оплате двумя путями: подключённым коннектором платёжной системы (сейчас это ЮKassa) или вашим собственным вебхуком. Оба сводятся к одной цепочке: оплата сопоставляется с заявкой или реферальным кодом, начисление идемпотентно, возврат отменяет начисление.
Что подключено сегодня
| Путь | Что это | Подлинность |
|---|---|---|
| Коннектор ЮKassa | POST /hooks/connectors/yookassa/{public_id} | сверка факта по API ЮKassa |
| Собственный вебхук, POST | POST /hooks/payments | токен интеграции в заголовке |
| Собственный вебхук, GET | GET /hooks/payments/{public_id} | производный токен secure в адресе |
Коннекторы amoCRM и Битрикс24 в тип провайдеров заложены, но не подключены: запрос на них вернёт 404 NOT_FOUND. Пока используйте собственный вебхук.
Для обоих путей на стороне сети нужен продукт «Подключение сайта» (входит в «Витрину Pro» и выше).
Коннектор ЮKassa
Принцип: Recca не верит присланному уведомлению. Из тела берётся только идентификатор платежа или возврата, а сумма, статус и валюта запрашиваются у ЮKassa по API с вашими учётными данными. Поддельное уведомление «заказ оплачен на миллион» получит ответ «такой оплаты нет».
Подключение. Коннектор создаётся для витрины: POST /admin/shops/{id}/payment-connectors с телом
{
"provider": "yookassa",
"label": "Основной сайт",
"credentials": { "shop_id": "123456", "secret_key": "<секретный ключ из кабинета платёжной системы>" },
"mapping": { "lead_field": "recca_lead_id", "code_field": "recca" }
}
Учётные данные проверяются запросом GET /v3/me и хранятся зашифрованными; наружу они не возвращаются никогда (в ответе только has_credentials). Активное подключение провайдера на витрину одно: второе даёт 409. В ответе приходят public_id и готовый notification_url вида https://api.recca.ru/hooks/connectors/yookassa/<public_id>. Этот адрес вы вставляете в личном кабинете ЮKassa как адрес уведомлений. Идентификатор в адресе прав не даёт.
События. Обрабатываются payment.succeeded и refund.succeeded. Остальные события (например, ожидание подтверждения) отвечают 200 без записи.
Как связывается оплата с реферальной заявкой. Передайте в metadata платежа ЮKassa поле с идентификатором заявки (по умолчанию recca_lead_id) и/или поле с реферальным кодом (по умолчанию recca, затем promo). Имена полей меняются в mapping.lead_field и mapping.code_field (латиница, цифры и _.-, до 32 символов).
Что не засчитывается.
- Валюта не рубли: ядро считает рубли и чужую валюту не конвертирует (
UNSUPPORTED_CURRENCY). - Тестовый платёж тестового аккаунта платёжной системы: деньги не начисляются (
TEST_PAYMENT). - Возврат, который в ЮKassa не завершён (
REFUND_NOT_SUCCEEDED).
Защита двери. Принимаются уведомления только с адресов ЮKassa; остальные получают 403. На один коннектор действует лимит 300 уведомлений в минуту. Ответ 200 приходит и тогда, когда начислять нечего: иначе платёжная система повторяла бы то, что повторять незачем. Ответ 503 означает, что до ЮKassa не удалось достучаться, — в этом случае повтор доставки спасает оплату от потери.
Собственный вебхук: POST
Для конструкторов и касс, которые умеют отправить POST с заголовком. Интеграция создаётся в кабинете («Интеграции» → «Подключение сайта»), токен показывается один раз.
curl -s -X POST https://api.recca.ru/hooks/payments \
-H "X-Recca-Token: $RECCA_INTEGRATION_TOKEN" -H "Content-Type: application/json" \
-d '{"external_id":"order-1001","amount":5000,"currency":"RUB","status":"paid","referral_code":"ABC0123XYZ"}'
Токен передаётся только заголовком X-Recca-Token или Authorization: Bearer …; в адресе он не принимается.
Тело (контракт Recca). external_id — номер заказа, amount (или amount_rub) — сумма, currency, status (или payment_status), referral_code, lead_id, email. Сумма должна быть положительным числом, с пробелами и запятой вместо точки допустимо. Статус понимается по словарю: оплачено (paid, success, succeeded, confirmed, 1, «оплачено» и др.), в ожидании (pending, waiting, 2), отменено (cancelled, failed, expired, 3), возврат (refunded, refund, return, chargeback, «возврат»). Незнакомый статус даёт 400 INVALID_PAYLOAD.
Тела других форм распознаются сами: заказ Creatium (order.id, cart.subtotal, поля формы recca/promo/recca_lead_id) и плоское тело Tilda (tranid, orderid).
Ответ. Всегда 200 с { "success": true, "data": { "outcome": "…", "reason": "…" } }. Значения outcome:
| outcome | Смысл |
|---|---|
matched | оплата сопоставлена, вознаграждение начислено |
unmatched | реферала нет или причина в reason (например, NO_REFERRAL_MATCH, PAYMENT_PENDING); это нормальный случай — клиент пришёл сам |
duplicate | этот заказ уже учтён (ALREADY_PROCESSED) |
rejected | не принято: reason называет причину (например, IDEMPOTENT_MISMATCH — тот же заказ с другой суммой) |
reversed | возврат отменил начисление |
Ответ нарочно не содержит идентификаторов начисления и имени реферера. Разбор «почему не начислено» виден владельцу сети в журнале кабинета.
Ошибки: 401 MISSING_TOKEN, 401 INVALID_TOKEN, 401 TOKEN_REVOKED, 400 INVALID_PAYLOAD, 429 RATE_LIMITED (лимит 60 запросов в минуту с одного IP), 503 REVERSAL_FAILED (откат не завершился, повторите).
Собственный вебхук: GET
Для CRM, у которых есть одно поле «URL» с макросами и нет POST с заголовками:
https://api.recca.ru/hooks/payments/<public_id>?order={ORDER}&sum={SUM}&status={STATUS}&secure=<токен>
public_id и secure (значение вида cpay_…) показываются один раз при создании интеграции и при перевыпуске токена. Это не токен интеграции, а производное от него значение: им можно звонить только в эту дверь, а перевыпуск токена интеграции отзывает и его. Параметры адреса: номер заказа (external_id, order_id, order, orderid, tranid, id), сумма (amount, sum, sum_rub, amount_rub), status или payment_status, код (referral_code, code, promo, recca), lead_id или lead, email, currency. Значение параметра — до 200 символов.
Неизвестный public_id и неверный токен отвечают одинаково — 401 INVALID_TOKEN, чтобы дверь не подсказывала, какие соединения существуют. Ответ несёт те же outcome и reason. Честный предел: у GET нет контрольного запроса к источнику, подлинность держит один токен; адрес остаётся в истории вашей CRM. Если CRM умеет POST с заголовком, выбирайте POST.
Идемпотентность и возвраты
Заказ узнаётся по external_id (для ЮKassa — по идентификатору платежа). Повтор того же заказа возвращает duplicate, не двоит начисление. Возврат (status из группы возвратов или refund.succeeded у ЮKassa) отменяет начисление, в том числе частично, и повторно не применяется.
См. также
- Реферальные программы — коды и погашение
- Вебхуки — события сети
- Tilda — заявки с сайта на Tilda
- Creatium — заявки с сайта на Creatium
- Ключи, права и лимиты — ключи и права