Переход с Corefy
Как перевести платёжную интеграцию с Corefy (PayCore) на этот API: соответствие вызовов, полей, статусов и колбэков, ключи и повтор, проверка и переключение по методам.
Входа, совместимого с API Corefy (PayCore), нет: платёжный клиент кассы переписывается на этот API один раз. Ниже то, что меняется, и порядок, в котором методы оплаты переводятся по одному без остановки приёма.
Вызовы
| Corefy | Этот API |
|---|---|
POST /api/payment-invoices | POST /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}/refund | POST /api/v1/payments/:id/refunds: Возвраты |
POST /public-api/payment-prerequest | GET /api/v1/services: Сервисы и суммы |
POST /api/payout-invoices | POST /api/v1/payouts: Выплаты; пока только в тестовом контуре и без отправки провайдеру |
GET /api/payout-invoices/{id} | GET /api/v1/payouts/:id |
terminate выплатного инвойса | POST /api/v1/payouts/:id/cancel: отмена, пока выплата не отправлена |
payout-prerequest | GET /api/v1/services, сервисы с direction: PAYOUT |
Списание и отмена авторизации, повтор платежа, пакетные выплаты и запуск выплаты (process), балансы, отчёты | Нет |
Вызова из браузера публичным ключом нет: API вызывает только сервер мерчанта.
Создание платежа
Тело плоское, без обёртки data.attributes.
| Corefy | Этот API |
|---|---|
reference_id | reference: до 128 знаков, уникален у мерчанта в контуре |
amount дробным числом в валюте счёта, service_amount в валюте сервиса | amountMinor: строка, целое число минорных единиц валюты сервиса. Делитель даёт minorUnit в списке сервисов |
currency | Нет: валюту задаёт сервис |
service | service: код из GET /api/v1/services, коды другие |
service_fields с именами провайдера | fields с ключами списка сервисов (payer.tax_id, payer.name) или fieldsOnPage: true, чтобы поля собрала страница оплаты |
customer, около двадцати полей | customer.id и customer.country; данные плательщика идут в fields |
return_url, return_urls | returnUrl, один адрес; при странице оплаты источник из списка разрешённых |
metadata | metadata |
test_mode | Нет: контур задаёт ключ |
callback_url | callbackUrl: адрес уведомлений этого платежа вместо адреса контура (то же поле есть у возврата и выплаты); подпись секретом контура, его выпускают один раз 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 |
|---|---|
created | CREATED |
processing | PROCESSING или AWAITING_CUSTOMER, если ждём плательщика |
process_pending | PROCESSING и inReview: true: исход неизвестен, это не отказ |
process_error | Отдельного статуса нет: повторы попыток идут внутри платежа |
processed | SUCCEEDED. Из него платёж не выходит, возврат его не меняет |
partially_processed | PARTIALLY_PAID в разборе |
process_failed | FAILED |
expired | EXPIRED; поздние деньги переводят его в SUCCEEDED, PARTIALLY_PAID или OVERPAID |
refunded, partially_refunded | SUCCEEDED; сумма возвратов в refundedMinor, сами возвраты отдельными объектами |
| Отказ Firewall | REJECTED с причиной firewall_blocked или customer_blocked; не зачислять |
terminated | Соответствия нет: отмены платежа через API нет |
| Чарджбэки, авторизация и проверка карты | Нет |
Что значит каждый статус и когда зачислять: Статусы платежа.
Колбэки
Колбэк Corefy соответствует уведомлению payment.updated, refund.updated или payout.updated: Уведомления.
| Corefy | Этот API |
|---|---|
Подпись SHA-1 в заголовке X-Signature или поле signature | HMAC-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 значит, что не прошли проверку данные плательщика.
Проверка перед переключением
В тестовом контуре, тестовым ключом:
GET /api/v1/meотвечает контуромTEST.- Касса берёт код сервиса, поля и границы суммы из
GET /api/v1/services, а не из своей настройки. - Каждая метка тестовых данных проходит так, как написано в таблице: зачисление только при
SUCCEEDEDбез разбора,timeout_paidне превращается в отказ,underpaidиoverpaidне зачисляются. - Обрыв после отправки создания и повтор с тем же
Idempotency-Keyдают один платёж. - Уведомление с чужой подписью отклоняется, повтор уведомления с тем же
idничего не меняет. - Без уведомлений касса узнаёт исход чтением не чаще раза в 5 секунд на платёж.
- Истёкшие платежи касса перечитывает сверкой, с уведомлениями или без.
- Отказ 429 ждёт
RateLimit-Resetи не теряет заказ: Ограничения.
Переключение по методам
- Параллельная работа. В кассе живут оба клиента, Corefy и этот API, и для каждого метода оплаты настройкой выбирается, через кого он идёт. Платёж доживает там, где создан: его статус и возвраты ведут у того, кто его создал.
- Перевод потока. Методы переводятся по одному. Перед переводом метод проходит проверку выше; после перевода новые платежи этого метода создаются здесь, а прежние дочитываются у Corefy.
- Откат. Метод возвращается на Corefy той же настройкой. Незавершённый платёж не пересоздают у другого: если первый прошёл, плательщик заплатит дважды. Его дочитывают здесь до финального статуса.
Боевой приём закрыт: пока он закрыт, переключение проверяется в тестовом контуре.