Документация Merchant API

Публичный справочник маршрутов Merchant API. Показаны объяснения, примеры запросов, затем успешный и ошибочный ответы. Некоторые поля уникальны для мерчанта и возвращаются индивидуально для него.

BASE_URL https://api.merchant.yes-pay.cc

POST /v1/auth/login

Аутентификация пользователя мерчанта

Обменивает имя пользователя и пароль на краткоживущий JWT RS256. При ошибке возвращается общий ответ без указания неверного поля.

Аутентификация: NoneАутентификация

Пример запроса

curl -i -X POST 'https://api.merchant.yes-pay.cc/v1/auth/login' -H 'Content-Type: application/json' --data '{"username":"owner@example.test","password":"fictitious-password"}'

Пример успешного ответа 200

{
  "token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.fictitious-token",
  "role": "MERCHANT",
  "requestId": "00000000-0000-4000-8000-000000000001"
}

Пример ошибки 401

{
  "error": {
    "code": "authentication_failed",
    "message": "Authentication failed"
  },
  "requestId": "00000000-0000-4000-8000-000000000001"
}

POST /v1/auth/logout

Отзыв текущей сессии мерчанта

Отзывает JWT-сессию из заголовка Bearer. Последующие запросы с тем же токеном завершаются ошибкой аутентификации.

Аутентификация: Authorization: BearerАутентификация

Пример запроса

curl -i -X POST 'https://api.merchant.yes-pay.cc/v1/auth/logout' -H 'Authorization: Bearer <fictitious-jwt>'

Пример успешного ответа 200

{
  "revoked": true,
  "requestId": "00000000-0000-4000-8000-000000000001"
}

Пример ошибки 401

{
  "error": {
    "code": "authentication_failed",
    "message": "Authentication failed"
  },
  "requestId": "00000000-0000-4000-8000-000000000001"
}

POST /v1/auth/password-recovery

Начать восстановление пароля

Запускает восстановление пароля для указанного пользователя. Ответ намеренно непрозрачен, чтобы нельзя было перечислять учётные записи.

Аутентификация: NoneАутентификация

Пример запроса

curl -i -X POST 'https://api.merchant.yes-pay.cc/v1/auth/password-recovery' -H 'Content-Type: application/json' --data '{"username":"owner@example.test"}'

Пример успешного ответа 202

{
  "accepted": true,
  "requestId": "00000000-0000-4000-8000-000000000001"
}

Пример ошибки 401

{
  "error": {
    "code": "authentication_failed",
    "message": "Authentication failed"
  },
  "requestId": "00000000-0000-4000-8000-000000000001"
}

POST /v1/auth/password-recovery/confirmation

Завершить восстановление пароля

Завершает восстановление с помощью доказательства и нового пароля, соответствующего политике.

Аутентификация: NoneАутентификация

Пример запроса

curl -i -X POST 'https://api.merchant.yes-pay.cc/v1/auth/password-recovery/confirmation' -H 'Content-Type: application/json' --data '{"recoveryProof":"fictitious-recovery-proof-32chars-min","newPassword":"fictitious-new-password"}'

Пример успешного ответа 200

{
  "reset": true,
  "requestId": "00000000-0000-4000-8000-000000000001"
}

Пример ошибки 401

{
  "error": {
    "code": "authentication_failed",
    "message": "Authentication failed"
  },
  "requestId": "00000000-0000-4000-8000-000000000001"
}

GET /v1/auth/session

Просмотр текущей сессии мерчанта

Возвращает пользователя, членства, выбранную организацию, роли, разрешения и срок действия сессии.

Аутентификация: Authorization: BearerАутентификация

Пример запроса

curl -i -X GET 'https://api.merchant.yes-pay.cc/v1/auth/session' -H 'Authorization: Bearer <fictitious-jwt>'

Пример успешного ответа 200

{
  "user": {
    "id": "244282ff-bc9b-4072-89cc-82167d9c94ee",
    "accountState": "active"
  },
  "organizations": [
    {
      "merchantId": "c4cc938f-6174-4b90-b61e-d77472e3c861",
      "status": "active"
    }
  ],
  "selectedOrganization": "c4cc938f-6174-4b90-b61e-d77472e3c861",
  "roles": [
    "owner"
  ],
  "permissions": [
    "payments_create",
    "transactions_read",
    "balances_read"
  ],
  "expiresAt": "2026-07-28T13:30:00.000Z",
  "requestId": "00000000-0000-4000-8000-000000000001"
}

Пример ошибки 401

{
  "error": {
    "code": "authentication_failed",
    "message": "Authentication failed"
  },
  "requestId": "00000000-0000-4000-8000-000000000001"
}

POST /v1/auth/session/organization

Выбор организации мерчанта

Выбирает разрешённую организацию и возвращает обновлённый JWT в контексте этого мерчанта.

Аутентификация: Authorization: BearerАутентификация

Пример запроса

curl -i -X POST 'https://api.merchant.yes-pay.cc/v1/auth/session/organization' -H 'Authorization: Bearer <fictitious-jwt>' -H 'Content-Type: application/json' --data '{"merchantId":"00000000-0000-4000-8000-000000000002"}'

Пример успешного ответа 200

{
  "token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.fictitious-token",
  "role": "MERCHANT",
  "requestId": "00000000-0000-4000-8000-000000000001"
}

Пример ошибки 403

{
  "error": {
    "code": "permission_denied",
    "message": "Permission denied"
  },
  "requestId": "00000000-0000-4000-8000-000000000001"
}

GET /v1/payments

Список платежей

Возвращает платежи с курсорной пагинацией. Опциональные фильтры status и currency сопоставляются с поддерживаемыми состояниями бэкенда.

Аутентификация: Authorization: Bearer or X-Api-KeyПлатежи

Пример запроса

curl -i -X GET 'https://api.merchant.yes-pay.cc/v1/payments' -H 'Authorization: Bearer <fictitious-jwt>'

Пример успешного ответа 200

{
  "items": [
    {
      "paymentId": "df7a24d4-dc7f-46f1-b3bc-4096acee6d96",
      "externalId": "order-42",
      "status": "CREATED",
      "amount": 1250,
      "currency": "RUB",
      "expiresAt": "2026-07-28T12:45:00.000Z",
      "paidAt": null,
      "createdAt": "2026-07-28T12:30:00.000Z",
      "updatedAt": "2026-07-28T12:30:00.000Z"
    }
  ],
  "nextCursor": null,
  "requestId": "00000000-0000-4000-8000-000000000001"
}

Пример ошибки 401

{
  "error": {
    "code": "authentication_failed",
    "message": "Authentication failed"
  },
  "requestId": "00000000-0000-4000-8000-000000000001"
}

POST /v1/payments

Создать платёжное намерение

Создаёт платёжное намерение с externalId, amount и опциональной currency. Мерчант не выбирает банк. Дополнительные неизвестные поля create игнорируются.

Аутентификация: Authorization: Bearer or X-Api-KeyПлатежи

В запросе amount — десятичная сумма в основных единицах; в ответе amount — целые минорные единицы.

Пример запроса

curl -i -X POST 'https://api.merchant.yes-pay.cc/v1/payments' -H 'Authorization: Bearer <fictitious-jwt>' -H 'Content-Type: application/json' --data '{"externalId":"order-42","amount":1250,"currency":"RUB"}'

Пример успешного ответа 201

{
  "paymentId": "df7a24d4-dc7f-46f1-b3bc-4096acee6d96",
  "externalId": "order-42",
  "status": "CREATED",
  "amount": 1250,
  "currency": "RUB",
  "expiresAt": null,
  "paidAt": null,
  "createdAt": "2026-07-28T12:30:00.000Z",
  "updatedAt": "2026-07-28T12:30:00.000Z",
  "commissionForMerchant": 0,
  "merchantGet": 1250,
  "requestId": "00000000-0000-4000-8000-000000000001"
}

Пример ошибки 422

{
  "error": {
    "code": "validation_failed",
    "message": "Validation failed"
  },
  "requestId": "00000000-0000-4000-8000-000000000001"
}

POST /v1/payments/{externalId}/cancel

Отменить платёж по внешнему ID

Отменяет подходящий платёж по внешнему ID мерчанта. В теле обязателен payment code из start. Для ASSIGNED сначала выполняется отмена у провайдера.

Аутентификация: Authorization: Bearer or X-Api-KeyПлатежи

Пример запроса

curl -i -X POST 'https://api.merchant.yes-pay.cc/v1/payments/{externalId}/cancel' -H 'Authorization: Bearer <fictitious-jwt>' -H 'Content-Type: application/json' --data '{"code":"8RTRFHKRJA5BO"}'

Пример успешного ответа 200

{
  "paymentId": "df7a24d4-dc7f-46f1-b3bc-4096acee6d96",
  "externalId": "order-42",
  "status": "cancelled",
  "amount": 1250,
  "currency": "RUB",
  "expiresAt": "2026-07-28T12:45:00.000Z",
  "paidAt": null,
  "createdAt": "2026-07-28T12:30:00.000Z",
  "updatedAt": "2026-07-28T12:40:00.000Z",
  "requestId": "00000000-0000-4000-8000-000000000001"
}

Пример ошибки 409

{
  "error": {
    "code": "payment_state_conflict",
    "message": "Payment state conflict"
  },
  "requestId": "00000000-0000-4000-8000-000000000001"
}

GET /v1/payments/{paymentId}

Получить платёж

Возвращает платёж по UUID платформы. Если каталожные реквизиты назначены, включает ту же публичную проекцию details, что и start.

Аутентификация: Authorization: Bearer or X-Api-KeyПлатежи

Пример запроса

curl -i -X GET 'https://api.merchant.yes-pay.cc/v1/payments/{paymentId}' -H 'Authorization: Bearer <fictitious-jwt>'

Пример успешного ответа 200

{
  "paymentId": "df7a24d4-dc7f-46f1-b3bc-4096acee6d96",
  "externalId": "order-42",
  "status": "AWAITING_PAYMENT",
  "amount": 1250,
  "currency": "RUB",
  "expiresAt": null,
  "paidAt": null,
  "createdAt": "2026-07-28T12:30:00.000Z",
  "updatedAt": "2026-07-28T12:31:00.000Z",
  "details": {
    "beneficiaryName": "Fixture Holder",
    "cardNumber": "4111111111111111",
    "phoneNumber": "+70000000000",
    "bankName": "Fixture Bank",
    "bin": "411111",
    "expiryDate": "2027-12-31"
  },
  "requestId": "00000000-0000-4000-8000-000000000001"
}

Пример ошибки 404

{
  "error": {
    "code": "resource_not_found",
    "message": "Resource not found"
  },
  "requestId": "00000000-0000-4000-8000-000000000001"
}

GET /v1/payments/{paymentId}/confirmation-claims

Список подтверждений оплаты

Возвращает подтверждения оплаты по платежу. Поля элементов claim уникальны для мерчанта и возвращаются индивидуально для него.

Аутентификация: Authorization: Bearer or X-Api-KeyПлатежи

Пример запроса

curl -i -X GET 'https://api.merchant.yes-pay.cc/v1/payments/{paymentId}/confirmation-claims' -H 'Authorization: Bearer <fictitious-jwt>' -H 'Idempotency-Key: 00000000-0000-4000-8000-000000000099'

Пример успешного ответа 200

Поля claim уникальны для мерчанта и возвращаются индивидуально для него; в примере показан общий каркас страницы.

{
  "items": [],
  "nextCursor": null,
  "requestId": "00000000-0000-4000-8000-000000000001"
}

Пример ошибки 401

{
  "error": {
    "code": "authentication_failed",
    "message": "Authentication failed"
  },
  "requestId": "00000000-0000-4000-8000-000000000001"
}

POST /v1/payments/{paymentId}/confirmation-claims

Отправить подтверждение оплаты

Отправляет неавторитетное подтверждение оплаты от мерчанта. Claim не переводит платёж в paid и не зачисляет баланс. Требует Idempotency-Key.

Аутентификация: Authorization: Bearer or X-Api-KeyIdempotency-KeyПлатежи

Некоторые необязательные поля claim уникальны для мерчанта и возвращаются индивидуально для него.

Пример запроса

curl -i -X POST 'https://api.merchant.yes-pay.cc/v1/payments/{paymentId}/confirmation-claims' -H 'Authorization: Bearer <fictitious-jwt>' -H 'Idempotency-Key: 00000000-0000-4000-8000-000000000099' -H 'Content-Type: application/json' --data '{"claimed_paid_at":"2026-07-28T12:35:00.000Z","payer_transfer_reference":"payer-visible-reference"}'

Пример успешного ответа 201

{
  "claimId": "6fed4dbb-86be-4918-b95b-1fa40dcb8fe3",
  "claimStatus": "received",
  "payment": {
    "paymentId": "df7a24d4-dc7f-46f1-b3bc-4096acee6d96",
    "externalId": "order-42",
    "status": "AWAITING_PAYMENT",
    "amount": 1250,
    "currency": "RUB",
    "expiresAt": null,
    "paidAt": null,
    "createdAt": "2026-07-28T12:30:00.000Z",
    "updatedAt": "2026-07-28T12:31:00.000Z"
  },
  "requestId": "00000000-0000-4000-8000-000000000001"
}

Пример ошибки 401

{
  "error": {
    "code": "authentication_failed",
    "message": "Authentication failed"
  },
  "requestId": "00000000-0000-4000-8000-000000000001"
}

POST /v1/payments/{paymentId}/start

Запустить платёж и получить реквизиты

Назначает каталожные платёжные реквизиты через Main Backend. Требует UUID v4 Idempotency-Key. Query bank отклоняется. Возвращает статус AWAITING_PAYMENT и инструкции для плательщика.

Аутентификация: Authorization: Bearer or X-Api-KeyIdempotency-KeyПлатежи

Start больше не вызывает Gateway Bridge и не возвращает Bridge payment code. Публичный integration_mode отражается в ответе, но не передаётся upstream.

Пример запроса

curl -i -X POST 'https://api.merchant.yes-pay.cc/v1/payments/{paymentId}/start' -H 'Authorization: Bearer <fictitious-jwt>' -H 'Idempotency-Key: 00000000-0000-4000-8000-000000000099' -H 'Content-Type: application/json' --data '{"integration_mode":"p2p_details"}'

Пример успешного ответа 200

{
  "payment": {
    "paymentId": "df7a24d4-dc7f-46f1-b3bc-4096acee6d96",
    "externalId": "order-42",
    "status": "AWAITING_PAYMENT",
    "amount": 1250,
    "currency": "RUB",
    "expiresAt": null,
    "paidAt": null,
    "createdAt": "2026-07-28T12:30:00.000Z",
    "updatedAt": "2026-07-28T12:31:00.000Z"
  },
  "integration_mode": "p2p_details",
  "details": {
    "beneficiaryName": "Fixture Holder",
    "cardNumber": "4111111111111111",
    "phoneNumber": "+70000000000",
    "bankName": "Fixture Bank",
    "bin": "411111",
    "expiryDate": "2027-12-31"
  },
  "requestId": "00000000-0000-4000-8000-000000000001"
}

Пример ошибки 409

{
  "error": {
    "code": "payment_state_conflict",
    "message": "Payment state conflict"
  },
  "requestId": "00000000-0000-4000-8000-000000000001"
}

GET /v1/payments/by-external-id/{externalId}

Получить платёж по внешнему ID

Возвращает платёж по уникальному внешнему идентификатору мерчанта. Назначенные каталожные реквизиты включаются, если Main Backend их возвращает.

Аутентификация: Authorization: Bearer or X-Api-KeyПлатежи

Пример запроса

curl -i -X GET 'https://api.merchant.yes-pay.cc/v1/payments/by-external-id/{externalId}' -H 'Authorization: Bearer <fictitious-jwt>'

Пример успешного ответа 200

{
  "paymentId": "df7a24d4-dc7f-46f1-b3bc-4096acee6d96",
  "externalId": "order-42",
  "status": "AWAITING_PAYMENT",
  "amount": 1250,
  "currency": "RUB",
  "expiresAt": null,
  "paidAt": null,
  "createdAt": "2026-07-28T12:30:00.000Z",
  "updatedAt": "2026-07-28T12:31:00.000Z",
  "details": {
    "beneficiaryName": "Fixture Holder",
    "cardNumber": "4111111111111111",
    "phoneNumber": "+70000000000",
    "bankName": "Fixture Bank",
    "bin": "411111",
    "expiryDate": "2027-12-31"
  },
  "requestId": "00000000-0000-4000-8000-000000000001"
}

Пример ошибки 404

{
  "error": {
    "code": "resource_not_found",
    "message": "Resource not found"
  },
  "requestId": "00000000-0000-4000-8000-000000000001"
}

GET /v1/profile

Получить профиль мерчанта

Возвращает профиль интеграции мерчанта для выбранной среды. Часть полей о комиссиях, лимитах и вебхуках уникальна для мерчанта и возвращается индивидуально для него.

Аутентификация: Authorization: Bearer or X-Api-KeyОбнаружение

Пример запроса

curl -i -X GET 'https://api.merchant.yes-pay.cc/v1/profile' -H 'Authorization: Bearer <fictitious-jwt>'

Пример успешного ответа 200

{
  "id": "c4cc938f-6174-4b90-b61e-d77472e3c861",
  "legalName": "Example Merchant Ltd",
  "displayName": "Example Shop",
  "externalReference": "merchant-42",
  "status": "active",
  "supportedCurrencies": [
    "RUB"
  ],
  "enforceUniqueOrderReference": true,
  "version": 4,
  "createdAt": "2026-07-01T09:00:00.000Z",
  "updatedAt": "2026-07-28T10:00:00.000Z",
  "requestId": "00000000-0000-4000-8000-000000000001"
}

Пример ошибки 401

{
  "error": {
    "code": "authentication_failed",
    "message": "Authentication failed"
  },
  "requestId": "00000000-0000-4000-8000-000000000001"
}

GET /v1/stats/payments

Получить статистику платежей

Возвращает агрегированную статистику платежей мерчанта. Поля периода и актуальности данных уникальны для мерчанта и возвращаются индивидуально для него.

Аутентификация: Authorization: Bearer or X-Api-KeyОбнаружение

Пример запроса

curl -i -X GET 'https://api.merchant.yes-pay.cc/v1/stats/payments' -H 'Authorization: Bearer <fictitious-jwt>'

Пример успешного ответа 200

{
  "currencies": [
    {
      "currency": "RUB",
      "countsByStatus": {
        "created": 3,
        "awaiting_payment": 1,
        "paid": 12,
        "expired": 2,
        "cancelled": 1
      },
      "verifiedGrossMinor": 1500000,
      "totalCount": 19
    }
  ],
  "boundedAt": 200,
  "requestId": "00000000-0000-4000-8000-000000000001"
}

Пример ошибки 401

{
  "error": {
    "code": "authentication_failed",
    "message": "Authentication failed"
  },
  "requestId": "00000000-0000-4000-8000-000000000001"
}

GET /v1/status

Публичный статус сервиса

Публичный endpoint без аутентификации: доступность, мажорная версия API, версия релиза, настроенный BASE_URL и текущее время сервера.

Аутентификация: NoneСтатус

Пример запроса

curl -i -X GET 'https://api.merchant.yes-pay.cc/v1/status'

Пример успешного ответа 200

{
  "availability": "available",
  "apiVersion": "v1",
  "version": "0.1.0",
  "baseUrl": "https://api.example.test",
  "currentTime": "2026-07-28T12:30:00.000Z",
  "requestId": "00000000-0000-4000-8000-000000000001"
}

Пример ошибки 429

{
  "error": {
    "code": "rate_limited",
    "message": "Rate limited"
  },
  "requestId": "00000000-0000-4000-8000-000000000001"
}

GET /v1/transactions

Список транзакций

Возвращает видимые мерчанту финансовые транзакции. Поля *Minor возвращаются целыми числами.

Аутентификация: Authorization: Bearer or X-Api-KeyФинансы

Пример запроса

curl -i -X GET 'https://api.merchant.yes-pay.cc/v1/transactions' -H 'Authorization: Bearer <fictitious-jwt>'

Пример успешного ответа 200

{
  "items": [
    {
      "id": "5e66e3cd-8ad1-4600-a9e5-8e7ab744358e",
      "sourceType": "payment_verification",
      "sourceId": "9124d44f-8a49-4480-885d-c021fd406ac6",
      "description": "Verified payment",
      "reversalOfId": null,
      "effectiveAt": "2026-07-28T12:35:00.000Z",
      "createdAt": "2026-07-28T12:35:01.000Z",
      "entries": [
        {
          "id": "70e8edca-352a-4810-a75f-1c14c25546ab",
          "direction": "credit",
          "amountMinor": 121875,
          "currency": "RUB",
          "effectiveAt": "2026-07-28T12:35:00.000Z"
        }
      ]
    }
  ],
  "nextCursor": null,
  "requestId": "00000000-0000-4000-8000-000000000001"
}

Пример ошибки 401

{
  "error": {
    "code": "authentication_failed",
    "message": "Authentication failed"
  },
  "requestId": "00000000-0000-4000-8000-000000000001"
}

GET /v1/transactions/{transactionId}

Получить транзакцию

Возвращает одну неизменяемую транзакцию без account ID и доказательств верификации.

Аутентификация: Authorization: Bearer or X-Api-KeyФинансы

Пример запроса

curl -i -X GET 'https://api.merchant.yes-pay.cc/v1/transactions/{transactionId}' -H 'Authorization: Bearer <fictitious-jwt>'

Пример успешного ответа 200

{
  "id": "5e66e3cd-8ad1-4600-a9e5-8e7ab744358e",
  "sourceType": "payment_verification",
  "sourceId": "9124d44f-8a49-4480-885d-c021fd406ac6",
  "description": "Verified payment",
  "reversalOfId": null,
  "effectiveAt": "2026-07-28T12:35:00.000Z",
  "createdAt": "2026-07-28T12:35:01.000Z",
  "entries": [
    {
      "id": "70e8edca-352a-4810-a75f-1c14c25546ab",
      "direction": "credit",
      "amountMinor": 121875,
      "currency": "RUB",
      "effectiveAt": "2026-07-28T12:35:00.000Z"
    }
  ],
  "requestId": "00000000-0000-4000-8000-000000000001"
}

Пример ошибки 404

{
  "error": {
    "code": "resource_not_found",
    "message": "Resource not found"
  },
  "requestId": "00000000-0000-4000-8000-000000000001"
}