> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pague.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Создать субсчёт

> Создаёт субсчёт с собственным балансом, полностью независимым от баланса основного аккаунта.

**Требуемое разрешение:** `SUBACCOUNT:WRITE` или `FULL_ACCESS`

<Note>
  **`reference` неизменяем.** Это идентификатор, который вы отправляете в заголовке `X-Sub-Account`, чтобы выполнить операцию в субсчёте, и значение, которое приходит в поле `subAccount` вебхуков, — выбирайте его внимательно, изменить его после создания невозможно.

  Формат: `^[a-z0-9][a-z0-9_-]{1,31}$` — от 2 до 32 символов, только строчные латинские буквы, цифры, `-` и `_`, начиная со строчной буквы или цифры. `reference` должен быть уникальным в пределах аккаунта: повторное использование существующего возвращает `409 SUB_ACCOUNT_REFERENCE_TAKEN`.

  Субсчёт создаётся с собственным нулевым балансом, полностью независимым от баланса основного аккаунта. См. [Субсчета](/ru#субсчета) — там описано поведение заголовка `X-Sub-Account` и приведена полная таблица ошибок.
</Note>


## OpenAPI

````yaml openapi.ru.json POST /sub-accounts
openapi: 3.0.0
info:
  title: pague.dev API
  description: Документация платёжного API pague.dev
  version: '1.0'
  contact: {}
servers:
  - url: https://api-gateway.pague.dev/v2
security: []
paths:
  /sub-accounts:
    post:
      tags:
        - External API - Sub-accounts (Subcontas)
      summary: Создать субсчёт
      description: >-
        Создаёт субсчёт с собственным балансом, полностью независимым от баланса
        основного аккаунта.


        **Требуемое разрешение:** `SUBACCOUNT:WRITE` или `FULL_ACCESS`
      operationId: ExternalSubAccountsController_createSubAccount
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateSubAccountInput'
      responses:
        '201':
          description: Субсчёт успешно создан
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateSubAccountOutput'
        '400':
          description: Bad Request — ошибка валидации
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequestErrorResponse'
        '401':
          description: Unauthorized — требуется аутентификация
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedErrorResponse'
        '403':
          description: Forbidden — доступ запрещён
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ForbiddenErrorResponse'
        '409':
          description: >-
            Conflict — `reference` уже используется в этом аккаунте
            (`SUB_ACCOUNT_REFERENCE_TAKEN`) либо достигнут лимит субсчетов
            (`SUB_ACCOUNT_QUOTA_EXCEEDED`)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConflictErrorResponse'
        '500':
          description: Internal Server Error — внутренняя ошибка сервера
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalServerErrorResponse'
      security:
        - bearerAuth: []
components:
  schemas:
    CreateSubAccountInput:
      type: object
      properties:
        reference:
          type: string
          description: >-
            Идентификатор субсчёта, задаваемый вами. Уникален в пределах
            аккаунта и неизменяем после создания. `principal` —
            зарезервированное слово основного аккаунта, использовать его нельзя:
            возвращается `400 SUB_ACCOUNT_INVALID_REFERENCE`.
          pattern: ^[a-z0-9][a-z0-9_-]{1,31}$
          example: loja-centro
        name:
          type: string
          description: Отображаемое имя субсчёта
          maxLength: 255
          example: Loja Centro
      required:
        - reference
        - name
    CreateSubAccountOutput:
      type: object
      properties:
        id:
          type: string
          description: ID субсчёта
          format: uuid
        reference:
          type: string
          description: Reference субсчёта
          example: loja-centro
        name:
          type: string
          description: Название субсчёта
          example: Loja Centro
        status:
          type: string
          description: Статус субсчёта
          example: approved
        createdAt:
          type: string
          description: Дата создания
          format: date-time
      required:
        - id
        - reference
        - name
        - status
        - createdAt
    BadRequestErrorResponse:
      type: object
      properties:
        statusCode:
          type: number
          example: 400
        error:
          type: string
          example: BadRequest
        message:
          type: string
          example: name must be longer than or equal to 2 characters
        details:
          type: object
        timestamp:
          type: string
          example: '2025-12-15T22:00:00.000Z'
        traceId:
          type: string
      required:
        - statusCode
        - error
        - message
        - timestamp
    UnauthorizedErrorResponse:
      type: object
      properties:
        statusCode:
          type: number
          example: 401
        error:
          type: string
          example: Unauthorized
        message:
          type: string
          example: Authentication token is required
        details:
          type: object
        timestamp:
          type: string
          example: '2025-12-15T22:00:00.000Z'
        traceId:
          type: string
      required:
        - statusCode
        - error
        - message
        - timestamp
    ForbiddenErrorResponse:
      type: object
      properties:
        statusCode:
          type: number
          example: 403
        error:
          type: string
          example: Forbidden
        message:
          type: string
          example: You do not have permission to access this resource
        details:
          type: object
        timestamp:
          type: string
          example: '2025-12-15T22:00:00.000Z'
        traceId:
          type: string
      required:
        - statusCode
        - error
        - message
        - timestamp
    ConflictErrorResponse:
      type: object
      properties:
        statusCode:
          type: number
          example: 409
        error:
          type: string
          example: Conflict
        message:
          type: string
          example: Resource with name 'Example' already exists
        details:
          type: object
          example:
            resource: Example
            field: name
            value: Example
        timestamp:
          type: string
          example: '2025-12-15T22:00:00.000Z'
        traceId:
          type: string
      required:
        - statusCode
        - error
        - message
        - timestamp
    InternalServerErrorResponse:
      type: object
      properties:
        statusCode:
          type: number
          example: 500
        error:
          type: string
          example: InternalError
        message:
          type: string
          example: An unexpected error occurred
        details:
          type: object
        timestamp:
          type: string
          example: '2025-12-15T22:00:00.000Z'
        traceId:
          type: string
          example: 2771463d58840c8e116dc6dda1e1e5d0
      required:
        - statusCode
        - error
        - message
        - timestamp
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: >-
        Токен доступа, полученный через POST /auth (client_id + client_secret).
        Действителен в течение 300 секунд.

````