Recca Разработчикам
Меню

Платёжные коннекторы

Приём оплат и сделок из внешних систем: готовые коннекторы и собственный вебхук.

Вознаграждение партнёру начисляется за оплаченный заказ, а не за заявку. Recca узнаёт об оплате двумя путями: подключённым коннектором платёжной системы (сейчас это ЮKassa) или вашим собственным вебхуком. Оба сводятся к одной цепочке: оплата сопоставляется с заявкой или реферальным кодом, начисление идемпотентно, возврат отменяет начисление.

Что подключено сегодня

ПутьЧто этоПодлинность
Коннектор ЮKassaPOST /hooks/connectors/yookassa/{public_id}сверка факта по API ЮKassa
Собственный вебхук, POSTPOST /hooks/paymentsтокен интеграции в заголовке
Собственный вебхук, GETGET /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) отменяет начисление, в том числе частично, и повторно не применяется.

См. также