Переход с Corefy

Как перевести платёжную интеграцию с Corefy (PayCore) на этот API: соответствие вызовов, полей, статусов и колбэков, ключи и повтор, проверка и переключение по методам.

Входа, совместимого с API Corefy (PayCore), нет: платёжный клиент кассы переписывается на этот API один раз. Ниже то, что меняется, и порядок, в котором методы оплаты переводятся по одному без остановки приёма.

Вызовы

CorefyЭтот API
POST /api/payment-invoicesPOST /api/v1/payments: Приём платежа
GET /api/payment-invoices/{id}GET /api/v1/payments/:id
Список инвойсов с отбором filter[reference_id]GET /api/v1/payments?reference=…: ноль или один платёж
POST /api/payment-invoices/{id}/refundPOST /api/v1/payments/:id/refunds: Возвраты
POST /public-api/payment-prerequestGET /api/v1/services: Сервисы и суммы
POST /api/payout-invoicesPOST /api/v1/payouts: Выплаты; пока только в тестовом контуре и без отправки провайдеру
GET /api/payout-invoices/{id}GET /api/v1/payouts/:id
terminate выплатного инвойсаPOST /api/v1/payouts/:id/cancel: отмена, пока выплата не отправлена
payout-prerequestGET /api/v1/services, сервисы с direction: PAYOUT
Списание и отмена авторизации, повтор платежа, пакетные выплаты и запуск выплаты (process), балансы, отчётыНет

Вызова из браузера публичным ключом нет: API вызывает только сервер мерчанта.

Создание платежа

Тело плоское, без обёртки data.attributes.

CorefyЭтот API
reference_idreference: до 128 знаков, уникален у мерчанта в контуре
amount дробным числом в валюте счёта, service_amount в валюте сервисаamountMinor: строка, целое число минорных единиц валюты сервиса. Делитель даёт minorUnit в списке сервисов
currencyНет: валюту задаёт сервис
serviceservice: код из GET /api/v1/services, коды другие
service_fields с именами провайдераfields с ключами списка сервисов (payer.tax_id, payer.name) или fieldsOnPage: true, чтобы поля собрала страница оплаты
customer, около двадцати полейcustomer.id и customer.country; данные плательщика идут в fields
return_url, return_urlsreturnUrl, один адрес; при странице оплаты источник из списка разрешённых
metadatametadata
test_modeНет: контур задаёт ключ
callback_urlcallbackUrl: адрес уведомлений этого платежа вместо адреса контура (то же поле есть у возврата и выплаты); подпись секретом контура, его выпускают один раз POST /api/v1/notifications/secret: Адрес в запросе
expires, description, descriptor, flow, options, tokenНет. Срок платежа задаёт администратор, он приходит в expiresAt

Страница оплаты

hpp_url соответствует pageUrl: ссылка на страницу оплаты этого платежа. Способ оплаты на странице не выбирают: его выбирает касса, называя сервис при создании. Касса, которая рисует оплату сама, берёт action: переход на страницу провайдера или реквизит. Подробно: Страница оплаты.

Ответ и статусы

  • id это номер pr_…; храните его рядом с заказом.
  • resolution соответствует reason.
  • Суммы приходят строками в минорных единицах, моменты времени строками ISO 8601 в UTC.
  • Признак разбора отдельный: inReview. Пока он true, не зачисляйте, при любом статусе.
CorefyЭтот API
createdCREATED
processingPROCESSING или AWAITING_CUSTOMER, если ждём плательщика
process_pendingPROCESSING и inReview: true: исход неизвестен, это не отказ
process_errorОтдельного статуса нет: повторы попыток идут внутри платежа
processedSUCCEEDED. Из него платёж не выходит, возврат его не меняет
partially_processedPARTIALLY_PAID в разборе
process_failedFAILED
expiredEXPIRED; поздние деньги переводят его в SUCCEEDED, PARTIALLY_PAID или OVERPAID
refunded, partially_refundedSUCCEEDED; сумма возвратов в refundedMinor, сами возвраты отдельными объектами
Отказ FirewallREJECTED с причиной firewall_blocked или customer_blocked; не зачислять
terminatedСоответствия нет: отмены платежа через API нет
Чарджбэки, авторизация и проверка картыНет

Что значит каждый статус и когда зачислять: Статусы платежа.

Колбэки

Колбэк Corefy соответствует уведомлению payment.updated, refund.updated или payout.updated: Уведомления.

CorefyЭтот API
Подпись SHA-1 в заголовке X-Signature или поле signatureHMAC-SHA-256 по Standard Webhooks: заголовки webhook-id, webhook-timestamp, webhook-signature
Тело в формате инвойсаТело события: id, type, sequence и снимок платежа, возврата или выплаты
Повторы до 100 раз30 попыток, около 20 часов
Порядок по полю updatedПорядок по sequence

Зачисляйте не по телу уведомления, а по прочитанному платежу: статус SUCCEEDED, inReview равен false, сумма paidMinor, один раз на id.

Ключи и вход

CorefyЭтот API
Basic из номера коммерческого аккаунта и ключаAuthorization: Bearer <ключ>; ключ можно передать и именем Basic с пустым паролем
Тестовые и боевые ключи, признак test_modeКлюч ak_test_ или ak_live_: контур задаёт ключ, признака в теле нет
Публичный ключ для браузераНет

Как выдать, сменить и отозвать ключ: Авторизация.

Повтор запроса

  • Заголовка повтора у Corefy нет, у этого API есть: Idempotency-Key. Повтор с тем же ключом и тем же телом возвращает тот же платёж: Повтор запроса. У возврата и выплаты ключ обязателен.
  • Повтор того же reference без ключа получает отказ 409 с правилом payment_reference_exists, а details.paymentId называет созданный платёж. По спецификации Corefy на это место приходит 409 с уже созданным инвойсом.
  • Платёж, ответ на создание которого не дошёл, находят по номеру заказа: GET /api/v1/payments?reference=….

Отказы

Тело отказа одно на все ручки: error.code, error.message, error.details. Разбирайте code и details.rule, а не текст: Формат ошибок. Отказ проверки тела у Corefy приходил кодом 422, здесь это 400 с кодом validation_failed или bad_amount; 422 значит, что не прошли проверку данные плательщика.

Проверка перед переключением

В тестовом контуре, тестовым ключом:

  1. GET /api/v1/me отвечает контуром TEST.
  2. Касса берёт код сервиса, поля и границы суммы из GET /api/v1/services, а не из своей настройки.
  3. Каждая метка тестовых данных проходит так, как написано в таблице: зачисление только при SUCCEEDED без разбора, timeout_paid не превращается в отказ, underpaid и overpaid не зачисляются.
  4. Обрыв после отправки создания и повтор с тем же Idempotency-Key дают один платёж.
  5. Уведомление с чужой подписью отклоняется, повтор уведомления с тем же id ничего не меняет.
  6. Без уведомлений касса узнаёт исход чтением не чаще раза в 5 секунд на платёж.
  7. Истёкшие платежи касса перечитывает сверкой, с уведомлениями или без.
  8. Отказ 429 ждёт RateLimit-Reset и не теряет заказ: Ограничения.

Переключение по методам

  1. Параллельная работа. В кассе живут оба клиента, Corefy и этот API, и для каждого метода оплаты настройкой выбирается, через кого он идёт. Платёж доживает там, где создан: его статус и возвраты ведут у того, кто его создал.
  2. Перевод потока. Методы переводятся по одному. Перед переводом метод проходит проверку выше; после перевода новые платежи этого метода создаются здесь, а прежние дочитываются у Corefy.
  3. Откат. Метод возвращается на Corefy той же настройкой. Незавершённый платёж не пересоздают у другого: если первый прошёл, плательщик заплатит дважды. Его дочитывают здесь до финального статуса.

Боевой приём закрыт: пока он закрыт, переключение проверяется в тестовом контуре.

API v1 · собрано 18.11.2026 · выпуск f13e6bf

Справочник методов собирается из кода сервера: он не описывает адрес, которого нет.