Merchant API Documentation

Public Merchant API route reference. Each route includes an explanation, a request sample, then success and error response examples. Some fields are unique per merchant and are returned uniquely for that merchant.

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

POST /v1/auth/login

Authenticate a merchant user

Exchanges a username and password for a short-lived RS256 JWT. Failed credentials return a generic authentication error without revealing which field was wrong.

Authentication: NoneAuthentication

Request example

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"}'

Success example 200

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

Error example 401

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

POST /v1/auth/logout

Revoke the current merchant session

Revokes the JWT session represented by the Bearer token. Subsequent calls with the same token fail authentication.

Authentication: Authorization: BearerAuthentication

Request example

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

Success example 200

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

Error example 401

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

POST /v1/auth/password-recovery

Begin password recovery

Starts password recovery for the given username. The response is intentionally opaque so callers cannot enumerate accounts.

Authentication: NoneAuthentication

Request example

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

Success example 202

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

Error example 401

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

POST /v1/auth/password-recovery/confirmation

Complete password recovery

Completes recovery with a proof token and a new password that meets policy requirements.

Authentication: NoneAuthentication

Request example

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"}'

Success example 200

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

Error example 401

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

GET /v1/auth/session

Inspect the current merchant session

Returns the authenticated user, memberships, selected organization, roles, permissions, and session expiry.

Authentication: Authorization: BearerAuthentication

Request example

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

Success example 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"
}

Error example 401

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

POST /v1/auth/session/organization

Select an authorized merchant organization

Selects an organization the user is allowed to access and returns a refreshed JWT scoped to that merchant.

Authentication: Authorization: BearerAuthentication

Request example

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"}'

Success example 200

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

Error example 403

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

GET /v1/payments

List payments

Lists payments with cursor pagination. Optional status and currency filters are mapped to supported backend states.

Authentication: Authorization: Bearer or X-Api-KeyPayments

Request example

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

Success example 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"
}

Error example 401

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

POST /v1/payments

Create a payment intent

Creates a payment intent with externalId and amount. Merchants cannot choose a bank. Additional fields such as webhookUrl, merchantRef, and ttlSeconds are unique per merchant when applicable.

Authentication: Authorization: Bearer or X-Api-KeyPayments

Request amount is a decimal in major units; the response amount is integer minor units.

Request example

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"}'

Success example 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"
}

Error example 422

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

POST /v1/payments/{externalId}/cancel

Cancel a payment by external ID

Cancels an eligible payment by merchant external ID. Body must include the payment code returned by start. ASSIGNED payments are cancelled with the provider first.

Authentication: Authorization: Bearer or X-Api-KeyPayments

Request example

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"}'

Success example 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"
}

Error example 409

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

GET /v1/payments/{paymentId}

Retrieve a payment

Retrieves a payment by platform UUID using the published PaymentIntegrationView projection.

Authentication: Authorization: Bearer or X-Api-KeyPayments

Request example

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

Success example 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"
}

Error example 404

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

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

List confirmation claims

Lists confirmation claims for a payment. Claim item fields are unique per merchant and are returned uniquely for that merchant.

Authentication: Authorization: Bearer or X-Api-KeyPayments

Request example

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'

Success example 200

Claim fields are unique per merchant and are returned uniquely for that merchant; the example shows the common page envelope.

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

Error example 401

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

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

Submit a confirmation claim

Submits a non-authoritative merchant confirmation claim. Claims never mark a payment paid and never credit balances. Requires Idempotency-Key.

Authentication: Authorization: Bearer or X-Api-KeyIdempotency-KeyPayments

Some optional claim fields are unique per merchant and are returned uniquely for that merchant.

Request example

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"}'

Success example 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"
}

Error example 401

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

POST /v1/payments/{paymentId}/start

Start a payment and acquire details

Creates a provider order and allocates P2P details. Requires Idempotency-Key. Platform routing assigns the bank; a bank query parameter is rejected. Always returns payment code for later cancel and payer flows.

Authentication: Authorization: Bearer or X-Api-KeyIdempotency-KeyPayments

Start always uses P2P allocation after platform bank assignment. Preserve and reuse the returned code for cancel.

Request example

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"}'

Success example 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"
}

Error example 409

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

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

Retrieve a payment by external ID

Retrieves a payment by the merchant unique external identifier.

Authentication: Authorization: Bearer or X-Api-KeyPayments

Request example

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

Success example 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"
}

Error example 404

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

GET /v1/profile

Retrieve the merchant profile

Returns the authenticated merchant integration profile for the selected environment. Some fee, limit, and webhook summary fields are unique per merchant and are returned uniquely for that merchant.

Authentication: Authorization: Bearer or X-Api-KeyDiscovery

Request example

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

Success example 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"
}

Error example 401

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

GET /v1/stats/payments

Retrieve payment statistics

Returns aggregated payment statistics for the merchant. Period and freshness fields are unique per merchant and are returned uniquely for that merchant.

Authentication: Authorization: Bearer or X-Api-KeyDiscovery

Request example

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

Success example 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"
}

Error example 401

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

GET /v1/status

Retrieve public service availability

Unauthenticated health-style endpoint returning availability, API version, and current server time.

Authentication: NoneStatus

Request example

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

Success example 200

{
  "availability": "available",
  "apiVersion": "v1",
  "currentTime": "2026-07-28T12:30:00.000Z",
  "requestId": "00000000-0000-4000-8000-000000000001"
}

Error example 429

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

GET /v1/transactions

List transactions

Lists merchant-visible financial transactions. Money fields ending in Minor are returned as integers.

Authentication: Authorization: Bearer or X-Api-KeyFinance

Request example

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

Success example 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"
}

Error example 401

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

GET /v1/transactions/{transactionId}

Retrieve a transaction

Retrieves one immutable ledger-derived transaction without account IDs or verification evidence.

Authentication: Authorization: Bearer or X-Api-KeyFinance

Request example

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

Success example 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"
}

Error example 404

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