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.yes-pay.cc

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.yes-pay.cc/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.yes-pay.cc/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.yes-pay.cc/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.yes-pay.cc/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.yes-pay.cc/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.yes-pay.cc/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.yes-pay.cc/v1/payments' -H 'Authorization: Bearer <fictitious-jwt>'

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

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, amount, and optional currency. Merchants cannot choose a bank. Additional unrecognized create fields are ignored.

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.yes-pay.cc/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": "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"
}

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.yes-pay.cc/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. When catalog pay details are assigned, includes the same public details projection returned by start.

Authentication: Authorization: Bearer or X-Api-KeyPayments

Request example

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

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

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.yes-pay.cc/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.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"}'

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

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

Assigns catalog payment details through Main Backend. Requires a UUID v4 Idempotency-Key. A bank query parameter is rejected. Returns AWAITING_PAYMENT status and payer instructions.

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

Start no longer calls Gateway Bridge or returns a Bridge payment code. Public integration_mode is echoed but not forwarded upstream.

Request example

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

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

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. Assigned catalog details are included when Main Backend returns them.

Authentication: Authorization: Bearer or X-Api-KeyPayments

Request example

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

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

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.yes-pay.cc/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.yes-pay.cc/v1/stats/payments' -H 'Authorization: Bearer <fictitious-jwt>'

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

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 major version, service release version, configured BASE_URL, and current server time.

Authentication: NoneStatus

Request example

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

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

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.yes-pay.cc/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.yes-pay.cc/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"
}