> ## 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.
# Создать платёж PIX
> Создаёт мгновенный платёж PIX.
**Требуемое разрешение:** `PIX:WRITE` или `FULL_ACCESS`
**Разделение между субсчетами.** Необязательное поле `split` делит часть суммы с другими вашими кошельками — субсчетами или основным аккаунтом, через зарезервированное слово `principal`. Не более 10 элементов, фиксированные суммы в BRL.
Инициатор — тот, кто создал платёж: он получает сумму брутто, платит полную комиссию и только потом делит остаток, поэтому потолок разделения — **чистая** сумма (сумма платежа за вычетом комиссии), а не брутто. Разделение происходит при зачислении, а не при создании. Возврат и MED списываются **только с инициатора** — с того, кто получил свою часть, средства никогда не списываются.
См. [Разделение платежа](/ru#разделение-платежа) — там полные правила, примеры и таблица ошибок.
**Выбор учреждения.** Если в вашем аккаунте включена эта опция, необязательное поле `pspCredentialId` фиксирует учреждение, которое выставит этот счёт, в обход настроенной маршрутизации. Скопируйте ID в разделе **Настройки → Маршрутизация** в панели.
Зафиксировать — **не значит «предпочесть»**: если учреждение недоступно или исчерпало лимит, счёт завершится ошибкой, а не уйдёт в другое. Ответ вернёт `pspCredentialId` как подтверждение.
См. [Выбор учреждения](/ru#выбор-учреждения) — там полные правила и таблица ошибок.
## OpenAPI
````yaml openapi.ru.json POST /pix
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:
/pix:
post:
tags:
- External API - PIX
summary: Создать платёж PIX
description: |-
Создаёт мгновенный платёж PIX.
**Требуемое разрешение:** `PIX:WRITE` или `FULL_ACCESS`
operationId: ExternalPixController_createCharge
parameters:
- name: Idempotency-Key
in: header
required: false
description: >-
Уникальный клиентский ключ (8–255 символов), делающий запрос
идемпотентным. Повторные запросы с тем же ключом возвращают
закешированный ответ (TTL 24 ч). Тот же ключ с другим телом запроса
возвращает 422.
schema:
type: string
minLength: 8
maxLength: 255
- $ref: '#/components/parameters/SubAccount'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreatePixChargeInput'
responses:
'201':
description: Платёж PIX успешно создан
content:
application/json:
schema:
$ref: '#/components/schemas/CreatePixChargeOutput'
'400':
description: Bad Request — ошибка валидации
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestErrorResponse'
'401':
description: Unauthorized — требуется аутентификация
content:
application/json:
schema:
$ref: '#/components/schemas/UnauthorizedErrorResponse'
'404':
description: Not Found — ресурс не найден
content:
application/json:
schema:
$ref: '#/components/schemas/NotFoundErrorResponse'
'500':
description: Internal Server Error — внутренняя ошибка сервера
content:
application/json:
schema:
$ref: '#/components/schemas/InternalServerErrorResponse'
security:
- bearerAuth: []
components:
parameters:
SubAccount:
name: X-Sub-Account
in: header
required: false
description: >-
Reference субсчёта, в котором должна выполняться операция. Если
заголовок не передан, операция выполняется в основном аккаунте;
зарезервированное значение `principal` также указывает на основной
аккаунт и равнозначно отсутствию заголовка. Принимается всеми
эндпоинтами, кроме `POST /auth` и самих эндпоинтов `/sub-accounts`,
которые всегда работают с основным аккаунтом.
Возможные ошибки: `404 SUB_ACCOUNT_NOT_FOUND`, `403
SUB_ACCOUNT_FORBIDDEN`, `403 SUB_ACCOUNT_SUSPENDED`.
Требует, чтобы у учётных данных был включён **доступ к субсчетам**
(Настройки → Интеграция → Учётные данные API). По умолчанию он выключен
и не заменяется никаким разрешением, даже `FULL_ACCESS`: без него ответ
— `403 SUB_ACCOUNT_FORBIDDEN`.
schema:
type: string
pattern: ^[a-z0-9][a-z0-9_-]{1,31}$
example: loja-centro
schemas:
CreatePixChargeInput:
type: object
properties:
amount:
type: number
description: Сумма в BRL (напр., 100.50 для R$ 100,50)
minimum: 1
example: 150.75
description:
type: string
description: Описание платежа
maxLength: 255
example: 'Pagamento do pedido #12345'
customer:
description: Данные плательщика (все поля необязательны).
allOf:
- $ref: '#/components/schemas/CustomerDto'
projectId:
type: string
description: >-
ID проекта для привязки транзакции. Если не указан и у аккаунта один
проект, платёж наследует этот проект; если проектов несколько —
платёж создаётся без проекта.
format: uuid
pspCredentialId:
type: string
description: >-
Фиксирует учреждение, которое выставит этот счёт, в обход
настроенной маршрутизации. Используйте ID из раздела «Настройки →
Маршрутизация» в панели. Учреждение должно быть включено и активно в
вашем аккаунте. Если оно недоступно или исчерпало лимит, счёт
завершится ОШИБКОЙ и не уйдёт в другое: вы запросили именно это.
Доступно аккаунтам с включённым выбором учреждения.
format: uuid
example: 6e307aa4-4772-4230-a648-d88cee308f54
expiresIn:
type: integer
description: 'Секунд до истечения срока действия (по умолчанию: 86400 = 24 ч)'
minimum: 300
maximum: 604800
example: 3600
externalReference:
type: string
description: Ваш внешний референс-ID
maxLength: 255
example: pedido-12345
metadata:
type: object
description: Пользовательские метаданные (пары ключ–значение)
additionalProperties: true
example:
orderId: '12345'
source: website
split:
type: array
description: >-
Делит часть суммы с другими субсчетами того же аккаунта при
зачислении. Инициатор — тот, кто создал платёж: он получает сумму
брутто, платит полную комиссию и только потом делит остаток —
комиссия между получателями не делится. Сумма split не может
превышать чистую сумму (сумма платежа за вычетом комиссии). Возврат
и MED списываются только с инициатора; с того, кто получил свою
часть, средства никогда не списываются.
maxItems: 10
items:
$ref: '#/components/schemas/PixSplitAllocationInput'
required:
- amount
- description
CreatePixChargeOutput:
type: object
properties:
id:
type: string
description: ID платежа (ID транзакции)
format: uuid
status:
type: string
description: Статус платежа
enum:
- pending
- completed
- failed
- cancelled
amount:
type: number
description: Сумма в BRL
example: 150.75
currency:
type: string
description: Код валюты
example: BRL
pixCopyPaste:
type: string
description: Код PIX «копировать и вставить»
example: 00020126580014br.gov.bcb.pix0136a1b2c3d4-e5f6-7890-abcd-ef1234567890
qrCodeBase64:
type: string
description: QR-код PIX в формате data URI (data:image/png;base64,...)
pspPaymentId:
type: string
description: >-
ID транзакции у платёжного провайдера (PSP). Используйте его для
сверки; отсутствует, если PSP не вернул ID при создании.
example: de3516a2-c63a-4c02-b132-a239bf42e183
expiresAt:
type: string
description: Дата истечения срока действия
format: date-time
pspCredentialId:
type: string
description: >-
Учреждение, выставившее этот счёт. Приходит только если вы
зафиксировали учреждение в запросе (`pspCredentialId`) — как
подтверждение, что выбор соблюдён.
format: uuid
example: 6e307aa4-4772-4230-a648-d88cee308f54
externalReference:
type: string
description: Ваш внешний референс-ID
example: pedido-12345
createdAt:
type: string
description: Дата создания
format: date-time
split:
type: array
description: >-
Принятое разделение, в BRL. Присутствует, только если платёж был
создан с разделением — если оно пришло в ответе, значит субсчета
существовали и сумма поместилась в чистую сумму. Фактически
распределённое приходит в вебхуке payment_completed.
items:
$ref: '#/components/schemas/PixSplitAllocationOutput'
required:
- id
- status
- amount
- currency
- pixCopyPaste
- expiresAt
- 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
NotFoundErrorResponse:
type: object
properties:
statusCode:
type: number
example: 404
error:
type: string
example: NotFound
message:
type: string
example: Resource with id 550e8400-e29b-41d4-a716-446655440000 not found
details:
type: object
example:
resource: Example
id: 550e8400-e29b-41d4-a716-446655440000
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
CustomerDto:
type: object
properties:
name:
type: string
description: Имя плательщика
maxLength: 255
example: João da Silva
document:
type: string
description: CPF или CNPJ плательщика, только цифры (необязательно)
maxLength: 20
example: '12345678909'
email:
type: string
description: Email плательщика
format: email
maxLength: 255
phone:
type: string
description: Телефон плательщика (в свободном формате)
maxLength: 20
example: '+5511999998888'
PixSplitAllocationInput:
type: object
properties:
subAccount:
type: string
description: >-
Reference активного субсчёта того же аккаунта, который получает свою
часть. Зарезервированное слово `principal` указывает на основной
аккаунт — используйте его, когда платёж создан субсчётом (заголовок
`X-Sub-Account`); платёж, созданный самим основным аккаунтом, не
может делиться с `principal`.
pattern: ^[a-z0-9][a-z0-9_-]{1,31}$
example: loja-centro
amount:
type: number
description: >-
Сумма в BRL для этого кошелька. Фиксированная сумма — проценты не
принимаются. Не более 2 знаков после запятой.
minimum: 0.01
example: 30
required:
- subAccount
- amount
PixSplitAllocationOutput:
type: object
properties:
subAccount:
type: string
description: >-
Reference субсчёта, который получает свою часть, либо `principal`,
когда получатель — основной аккаунт
example: loja-centro
amount:
type: number
description: Сумма в BRL для этого кошелька
example: 30
required:
- subAccount
- amount
securitySchemes:
bearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
description: >-
Токен доступа, полученный через POST /auth (client_id + client_secret).
Действителен в течение 300 секунд.
````