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

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

BASE_URL https://api.merchant.fastpay.business

POST /v1/auth/login

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

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

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

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

curl -i -X POST 'https://api.merchant.fastpay.business/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.fastpay.business/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.fastpay.business/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.fastpay.business/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.fastpay.business/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.fastpay.business/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.fastpay.business/v1/payments' -H 'Authorization: Bearer <fictitious-jwt>'

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

{
  "items": [
    {
      "paymentId": "df7a24d4-dc7f-46f1-b3bc-4096acee6d96",
      "externalId": "order-42",
      "status": "PENDING",
      "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. Мерчант не выбирает банк. Дополнительные поля (webhookUrl, merchantRef, ttlSeconds) уникальны для мерчанта при наличии.

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

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

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

curl -i -X POST 'https://api.merchant.fastpay.business/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": "PENDING",
  "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",
  "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.fastpay.business/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 платформы в опубликованной проекции PaymentIntegrationView.

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

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

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

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

{
  "paymentId": "df7a24d4-dc7f-46f1-b3bc-4096acee6d96",
  "externalId": "order-42",
  "status": "PENDING",
  "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",
  "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.fastpay.business/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.fastpay.business/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": "ASSIGNED",
    "amount": 1250,
    "currency": "RUB",
    "expiresAt": "2026-07-28T12:45:00.000Z",
    "paidAt": null,
    "createdAt": "2026-07-28T12:30:00.000Z",
    "updatedAt": "2026-07-28T12:31:00.000Z",
    "code": "8RTRFHKRJA5BO"
  },
  "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

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

Создаёт заказ у провайдера и выдаёт P2P-реквизиты. Требует Idempotency-Key. Банк назначает платформенная маршрутизация; query bank отклоняется. Всегда возвращает payment code для последующей отмены и оплаты.

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

Start всегда выполняет P2P-выдачу после назначения банка платформой. Сохраните и используйте возвращённый code для отмены.

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

curl -i -X POST 'https://api.merchant.fastpay.business/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

{
  "operation": {
    "intentId": "df7a24d4-dc7f-46f1-b3bc-4096acee6d96",
    "state": "awaiting_payment",
    "mode": "p2p_details",
    "details": {
      "code": "8RTRFHKRJA5BO",
      "txId": "1785743999933012401",
      "paymentUrl": "https://example.test/pay?code=8RTRFHKRJA5BO",
      "owner": "EXAMPLE OWNER",
      "cardNumber": "9860246614555802",
      "phoneNumber": "998428590817",
      "country": "UZB",
      "bank": "octobank",
      "selectedBank": 2,
      "lockDatetime": "2026-08-03T08:00:00.726Z"
    },
    "hostedUrl": "https://example.test/pay?code=8RTRFHKRJA5BO",
    "paymentCode": "8RTRFHKRJA5BO",
    "expiresAt": "2026-08-03T08:00:00.726Z"
  },
  "payment": {
    "paymentId": "df7a24d4-dc7f-46f1-b3bc-4096acee6d96",
    "externalId": "order-42",
    "status": "ASSIGNED",
    "amount": 1250,
    "currency": "RUB",
    "expiresAt": "2026-07-28T12:45:00.000Z",
    "paidAt": null,
    "createdAt": "2026-07-28T12:30:00.000Z",
    "updatedAt": "2026-07-28T12:31:00.000Z",
    "code": "8RTRFHKRJA5BO"
  },
  "code": "8RTRFHKRJA5BO",
  "paymentUrl": "https://example.test/pay?code=8RTRFHKRJA5BO",
  "details": {
    "code": "8RTRFHKRJA5BO",
    "txId": "1785743999933012401",
    "paymentUrl": "https://example.test/pay?code=8RTRFHKRJA5BO",
    "owner": "EXAMPLE OWNER",
    "cardNumber": "9860246614555802",
    "phoneNumber": "998428590817",
    "country": "UZB",
    "bank": "octobank",
    "selectedBank": 2,
    "lockDatetime": "2026-08-03T08:00:00.726Z"
  },
  "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

Возвращает платёж по уникальному внешнему идентификатору мерчанта.

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

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

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

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

{
  "paymentId": "df7a24d4-dc7f-46f1-b3bc-4096acee6d96",
  "externalId": "order-42",
  "status": "PENDING",
  "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",
  "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.fastpay.business/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.fastpay.business/v1/stats/payments' -H 'Authorization: Bearer <fictitious-jwt>'

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

{
  "currencies": [
    {
      "currency": "RUB",
      "countsByStatus": {
        "PENDING": 3,
        "ASSIGNED": 1,
        "CONFIRMED": 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 и текущее время сервера.

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

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

curl -i -X GET 'https://api.merchant.fastpay.business/v1/status'

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

{
  "availability": "available",
  "apiVersion": "v1",
  "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.fastpay.business/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.fastpay.business/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"
}