> ## 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. # Введение > Документация API pague.dev ## Добро пожаловать API pague.dev позволяет интегрировать обработку платежей в ваши приложения. Эта документация охватывает все доступные эндпоинты для управления клиентами, проектами, платежами, транзакциями и платежами PIX. ## Базовый URL Все запросы должны отправляться на: ``` https://api-gateway.pague.dev/v2 ``` ## Аутентификация Аутентификация выполняется в два этапа: вы обмениваете учётные данные вашего аккаунта на короткоживущий **токен доступа** и отправляете этот токен в заголовке `Authorization` каждого запроса. ### 1. Получите ваши учётные данные Создайте учётные данные API в Dashboard. Они состоят из `client_id` и `client_secret`: * `mp_live_*` — учётные данные для **продакшена** * `mp_test_*` — учётные данные для **песочницы** `client_secret` отображается **только один раз** — в момент создания. Сохраните его в надёжном месте. ### 2. Сгенерируйте токен доступа Обменяйте ваши учётные данные на токен через эндпоинт [аутентификации](/ru/api-reference/auth/token): ```bash theme={null} curl -X POST https://api-gateway.pague.dev/v2/auth \ -H 'Content-Type: application/json' \ -d '{ "client_id": "mp_live_abc123...", "client_secret": "seu_client_secret" }' ``` ```json Ответ theme={null} { "access_token": "eyJhbGciOiJSUzI1NiIs...", "token_type": "Bearer", "expires_in": 300 } ``` Недействительные или отозванные учётные данные возвращают `401 {"error": "Unauthorized", "message": "Invalid credentials"}`. ### 3. Используйте токен в запросах Отправляйте токен в заголовке `Authorization`: ```bash theme={null} curl https://api-gateway.pague.dev/v2/account \ -H 'Authorization: Bearer eyJhbGciOiJSUzI1NiIs...' ``` Токен истекает через **300 секунд (5 минут)**. Сгенерируйте новый токен через `/auth` после истечения — refresh token не предусмотрен. ## Разрешения Каждые учётные данные имеют гранулярные разрешения, определяющие, к каким эндпоинтам они могут обращаться. Разрешения назначаются в момент создания учётных данных. ### Доступные разрешения | Разрешение | Описание | | ------------------ | ---------------------------------------- | | `FULL_ACCESS` | Полный доступ ко всем эндпоинтам API | | `PIX:WRITE` | Создание платежей PIX | | `PROJECT:WRITE` | Создание проектов | | `PROJECT:READ` | Получение списка проектов и поиск по ним | | `TRANSACTION:READ` | Получение транзакций | | `WITHDRAWAL:WRITE` | Создание выводов средств через PIX | | `METRICS:READ` | Получение метрик выручки | | `ACCOUNT:READ` | Просмотр данных аккаунта и баланса | | `SUBACCOUNT:WRITE` | Создание субсчетов | | `SUBACCOUNT:READ` | Получение списка субсчетов | Разрешение `FULL_ACCESS` предоставляет доступ ко всем эндпоинтам и эквивалентно наличию всех перечисленных выше разрешений. **Исключение: доступ к субсчетам — это не разрешение.** `FULL_ACCESS` покрывает эндпоинты `/sub-accounts` (создание и просмотр кошельков), но **не** включает заголовок `X-Sub-Account` — это отдельное поле учётных данных. См. [Субсчета](/ru#субсчета). ### Ограничение по IP При желании вы можете ограничить учётные данные списком разрешённых IP-адресов. Когда список настроен, запросы с IP-адресов вне списка отклоняются с ошибкой `403 Forbidden`. Мы рекомендуем настраивать ограничение по IP для учётных данных с чувствительными разрешениями, такими как `FULL_ACCESS` и `WITHDRAWAL:WRITE`. ## Субсчета У аккаунта могут быть субсчета — дочерние кошельки, баланс которых **полностью независим** от баланса основного аккаунта. Каждый субсчёт идентифицируется по `reference`, который вы задаёте сами. Субсчета и [разделение платежа](/ru#разделение-платежа) работают в **обоих окружениях**: учётные данные `mp_test_*` создают кошельки и работают с ними в песочнице так же, как `mp_live_*` в продакшене. Чтобы выполнить операцию в субсчёте, отправьте заголовок `X-Sub-Account` с его `reference`: ```bash theme={null} curl https://api-gateway.pague.dev/v2/account \ -H 'Authorization: Bearer eyJhbGciOiJSUzI1NiIs...' \ -H 'X-Sub-Account: loja-centro' ``` Заголовок **необязателен** и принимается всеми эндпоинтами, кроме `/auth` и самих эндпоинтов `/sub-accounts`: создание и получение списка субсчетов всегда выполняются в основном аккаунте. Если он передан, вся операция выполняется в субсчёте — создание платежа, получение транзакции, создание вывода средств, проверка баланса. Если он не передан, операция выполняется в основном аккаунте. `X-Sub-Account: principal` тоже указывает на основной аккаунт и равнозначен отсутствию заголовка. `reference` задаётся вами при создании субсчёта и является **неизменяемым**. Он должен соответствовать `^[a-z0-9][a-z0-9_-]{1,31}$`: от 2 до 32 символов, только строчные латинские буквы, цифры, `-` и `_`, начиная со строчной буквы или цифры. `principal` — **зарезервированное слово**: оно обозначает основной аккаунт в `split` и в заголовке `X-Sub-Account`, поэтому создать субсчёт с таким `reference` нельзя. ### Субсчета в песочнице Заголовок `X-Sub-Account`, поле `split`, слово `principal` и внутренний перевод работают в песочнице ровно так же, как в продакшене. **Один и тот же `reference` может существовать в обоих окружениях.** Аккаунт песочницы и продакшен-аккаунт — это разные аккаунты, поэтому `loja-centro` в песочнице и `loja-centro` в продакшене сосуществуют без конфликта. Именно это позволяет **одному и тому же payload работать в обоих**: вы тестируете с `mp_test_*`, меняете ключ на `mp_live_*` и переходите в продакшен, не меняя ни строки. **Два дерева изолированы.** Учётные данные `mp_test_*` видят только кошельки песочницы, а `mp_live_*` — только продакшен-кошельки. Это касается и `split`: разделение из кошелька песочницы в продакшен-кошелёк отклоняется, потому что в этом контексте продакшен-кошелька не существует. Ошибка та же — `Subconta 'X' não existe nesta conta ou não está ativa`. **Кошелёк нужно создать в каждом окружении.** Создание `loja-centro` в продакшене не создаёт его в песочнице — это две отдельные записи, и так задумано. **Комиссия одинакова в обоих окружениях**, и это сделано намеренно: кошелёк песочницы наследует комиссию продакшен-аккаунта именно для того, чтобы потолок разделения — чистая сумма, а не брутто — вёл себя одинаково. Разделение, которое проходит в песочнице, пройдёт и в продакшене. Кошелёк песочницы, создавший платёж на R$ 20,00 и разделивший R$ 1,00, получает **+R$ 18,80**, а получатель — **+R$ 1,00**, при комиссии R\$ 0,20; те же числа, что и в продакшене. ### Внутренний перевод Субсчёт создаётся с **нулевым балансом**. Внутренний перевод — это то, как вы пополняете новый кошелёк и как позже возвращаете остаток в основной аккаунт. Он перемещает средства между счетами **одного владельца**: из основного аккаунта в кошелёк, из кошелька в основной аккаунт или между «сестринскими» кошельками. Это не PIX и не вывод средств — это перекладывание из одного своего кармана в другой. Деньги уходят с одного счёта и поступают на другой, попадают в **обе** выписки, а общий баланс аккаунта не меняется. **В публичном API нет эндпоинта внутреннего перевода.** Операция выполняется в Дашборде, на экране кошельков. Искать маршрут бесполезно: в этот контракт он не входит. Что важно знать перед переводом: * **Только в пределах своей структуры.** Перевода на счёт третьего лица здесь нет — это PIX, и путь для него другой: [Создать вывод средств PIX](/ru/api-reference/withdrawals/create). * **Потолок — доступный к трате баланс источника**, а не полный доступный остаток: это доступное за вычетом непогашенного долга по возвратам, тот же критерий, что и для вывода средств. * **Отмены нет.** Ошибочный перевод исправляется обратным переводом. В выписке каждый перевод порождает **две строки** типа `internal_transfer` — списание (отрицательная сумма) у источника и зачисление (положительная) у получателя. Это тот же тип, что и у частей [разделения платежа](/ru#разделение-платежа): в обоих случаях `GET /transactions/{id}` возвращает `type: internal_transfer`. ### Лимиты субсчёта По умолчанию **кошелёк использует общий бюджет лимитов основного аккаунта**. Так ведёт себя любой субсчёт, созданный через API или в панели: расход всех кошельков суммируется в пределах одного и того же потолка владельца. **Создание кошельков не увеличивает ваш лимит.** Бюджет один, поэтому платёж в одном кошельке может быть отклонён по лимиту **из-за оборота другого кошелька** того же аккаунта — в том числе того, к которому ваш код в этом запросе даже не обращался. Это ожидаемое поведение, а не нарушение изоляции. Платформа может в отдельных случаях выделить кошельку **собственный** бюджет, отделив его расход от остального аккаунта. Это решение платформы: оно не настраивается продавцом, для него нет эндпоинта и нет самообслуживания — если это нужно вашей операции, обратитесь в поддержку. В **песочнице лимитов нет**: описанный здесь общий потолок проявляется только в продакшене. Это не особенность кошельков — так работает любая операция в песочнице, — поэтому не делайте из тестов вывод, что общий бюджет исчез. Не путайте это с `SUB_ACCOUNT_QUOTA_EXCEEDED` из таблицы ниже: тот лимит — на **количество** кошельков в аккаунте, к сумме оборота он отношения не имеет. ### Ошибки субсчетов | HTTP | Код | Когда возникает | | ---- | ------------------------------- | ---------------------------------------------------------------------------------------------- | | 404 | `SUB_ACCOUNT_NOT_FOUND` | Указанный `reference` не существует в этом аккаунте | | 403 | `SUB_ACCOUNT_FORBIDDEN` | Учётные данные не имеют права работать с этим субсчётом | | 403 | `SUB_ACCOUNT_SUSPENDED` | Субсчёт приостановлен | | 409 | `SUB_ACCOUNT_QUOTA_EXCEEDED` | Достигнут лимит субсчетов для аккаунта | | 409 | `SUB_ACCOUNT_REFERENCE_TAKEN` | Такой `reference` уже используется в этом аккаунте | | 400 | `SUB_ACCOUNT_INVALID_REFERENCE` | При создании запрошен `reference` `principal` — зарезервированное слово для основного аккаунта | Доступом к кошелькам управляют две разные вещи, и отказывают они по-разному: * **Разрешение учётных данных** относится к эндпоинтам `/sub-accounts`: для списка нужен `SUBACCOUNT:READ`, для создания — `SUBACCOUNT:WRITE`. Без него ответ — `403 Insufficient permissions. Required: SUBACCOUNT:READ`. * **Область действия учётных данных** относится к работе *внутри* кошелька: она определяет, до каких кошельков эти учётные данные дотягиваются через заголовок `X-Sub-Account` и через `split`, и именно она возвращает `SUB_ACCOUNT_FORBIDDEN`. Поэтому для создания платежа с `X-Sub-Account` и `split` достаточно `PIX:WRITE`: разрешения `SUBACCOUNT:*` управляют реестром кошельков, а не их использованием. **Область действия по умолчанию выключена, и никакое разрешение её не заменяет.** Только что созданные учётные данные — даже с полным доступом — получат `403 SUB_ACCOUNT_FORBIDDEN` на первом же запросе с `X-Sub-Account`, пока область действия остаётся в значении «без доступа». Включите её в разделе **Настройки → Интеграция → Учётные данные API**, поле **Доступ к субсчетам** (действует сразу, в том числе для уже выданных токенов). Так сделано намеренно: иначе все ранее созданные учётные данные получили бы доступ ко всему дереву в день создания первого кошелька. Субсчета создаются через [Создать субсчёт](/ru/api-reference/sub-accounts/create), а их список доступен в [Списке субсчетов](/ru/api-reference/sub-accounts/list). В вебхуках поле `subAccount` указывает, какому кошельку принадлежит событие — см. [Вебхуки](/ru/api-reference/webhooks). ## Разделение платежа Платёж PIX может разделить часть полученной суммы с другими кошельками того же аккаунта — субсчетами или самим основным аккаунтом. Отправьте необязательное поле `split` при [создании платежа](/ru/api-reference/pix/create): ```json theme={null} { "amount": 100.00, "description": "Pedido 4821", "split": [ { "subAccount": "loja-centro", "amount": 30.00 }, { "subAccount": "loja-sul", "amount": 20.00 } ] } ``` | Поле | Тип | Описание | | -------------------- | ------ | -------------------------------------------------------------------------------------------- | | `split` | array | Необязательное. Не более **10** элементов | | `split[].subAccount` | string | `reference` субсчёта, который получает свою часть, либо `principal` — для основного аккаунта | | `split[].amount` | number | Сумма в BRL для этого кошелька — минимум `0.01`, не более 2 знаков после запятой | Суммы **фиксированные, в BRL**: разделение по процентам не поддерживается. Ответ на создание возвращает принятый `split` в том же формате и тоже в BRL — если он пришёл в ответе, значит субсчета существовали и сумма поместилась. Проверка выполняется **до** создания платежа: некорректный `split` возвращает `400`, и платёж не создаётся. ### Инициатор — тот, кто создал платёж Инициатор — это аккаунт (или субсчёт из заголовка `X-Sub-Account`), создавший платёж. Именно он получает **сумму брутто**, платит **полную комиссию** и только потом делит остаток. Комиссия **не делится** между получателями. Каждый субсчёт из `split` получает ровно тот `amount`, который вы указали, без каких-либо вычетов. ### Потолок разделения — чистая сумма, а не брутто Разделить можно максимум сумму платежа **за вычетом комиссии**. При платеже на **R$ 100,00** с комиссией **R$ 1,49** чистая сумма равна \*\*R$ 98,51** — это и есть потолок. `split` на сумму R$ 98,51 принимается (инициатору остаётся ноль). `split` на сумму \*\*R$ 99,00** отклоняется, хотя она и меньше R$ 100,00 самого платежа: ```json Ответ 400 theme={null} { "statusCode": 400, "error": "DomainError", "message": "A soma do split (R$ 99.00) excede o líquido da cobrança (R$ 98.51 — bruto R$ 100.00 menos taxa de R$ 1.49)", "timestamp": "2026-01-11T19:03:28.280Z" } ``` Учитывается комиссия того аккаунта, который инициирует платёж, для метода PIX. **Возврат и MED затрагивают только инициатора.** С того, кто получил свою часть, средства **никогда** не списываются: каскадных возвратов нет, и уже переведённые деньги не отзываются. Возврат, чарджбэк или блокировка MED по платежу списываются исключительно с аккаунта, который его инициировал. Последствия вы контролируете сами: если разделить 100% чистой суммы и транзакция будет возвращена, весь убыток ляжет на инициатора — а списание может увести его баланс в минус. Оставлять запас у инициатора — решение интегратора, а не системы. ### Разделение происходит при зачислении Создание платежа **не двигает деньги вообще**. `split` сохраняется в платеже и выполняется только тогда, когда оплата подтверждена — именно в этот момент суммы уходят с баланса инициатора и поступают на кошельки получателей. Истёкший или неоплаченный платёж не порождает разделения. Комиссия аккаунта может измениться между созданием платежа и его оплатой. Если при зачислении сумма `split` больше не помещается в чистую сумму, части выполняются **в том порядке, в котором вы их отправили**, пока чистая сумма не закончится: последняя может быть уменьшена или не выполнена вовсе. Зачисление из-за этого никогда не срывается — сортируйте массив по приоритету и сверяйтесь по полю `split` вебхука [`payment_completed`](/ru/api-reference/webhooks), в котором приходит фактически распределённое. ### Только кошельки того же аккаунта `subAccount` принимает `reference` **активного субсчёта того же аккаунта** либо зарезервированное слово `principal`. Разделения за пределы своей структуры в этом API нет. ### Разделение обратно в основной аккаунт `principal` — единственное слово, которое не является ничьим `reference`: оно указывает на **основной аккаунт** как на получателя части суммы. Это обратный путь по отношению ко всему остальному в этом разделе: платёж создаётся в субсчёте, и часть чистой суммы возвращается в основной аккаунт: ```bash theme={null} curl -X POST https://api-gateway.pague.dev/v2/pix \ -H 'Authorization: Bearer eyJhbGciOiJSUzI1NiIs...' \ -H 'X-Sub-Account: loja-centro' \ -H 'Content-Type: application/json' \ -d '{ "amount": 20.00, "description": "Pedido 4821", "split": [ { "subAccount": "principal", "amount": 5.00 } ] }' ``` При комиссии R$ 0,20 результат такой: у `loja-centro` остаётся **R$ 14,80\*\* (R$ 20,00 минус R$ 0,20 комиссии и минус R$ 5,00 разделения), а основной аккаунт получает **R$ 5,00\*\*. Инициатором остаётся `loja-centro` — именно он платит полную комиссию, а основной аккаунт получает свою часть без вычетов, как и любой другой получатель. В ответе на создание и в поле `split` вебхука приходит `"subAccount": "principal"` — так же, как и для остальных кошельков. Платёж, **созданный основным аккаунтом**, не может делиться с `principal` — это было бы разделение с самим собой, и всё неразделённое и так остаётся у него. Такой случай возвращает `400`. Чтобы переводить остатки между кошельками вне платежа, используйте [внутренний перевод](/ru#внутренний-перевод) — явную операцию, не привязанную к зачислению платежа. ### Разделение из субсчёта Заголовок `X-Sub-Account` и поле `split` отвечают на разные вопросы и работают **вместе**: заголовок говорит, **кто инициирует** платёж, а `split` — **кому уходит часть чистой суммы**. Субсчёт может инициировать платёж и разделить его с «сестринским» субсчётом. При этом основной аккаунт не затрагивается — он ничего не получает и не платит комиссию: ```bash theme={null} curl -X POST https://api-gateway.pague.dev/v2/pix \ -H 'Authorization: Bearer eyJhbGciOiJSUzI1NiIs...' \ -H 'X-Sub-Account: loja-centro' \ -H 'Content-Type: application/json' \ -d '{ "amount": 100.00, "description": "Pedido 4821", "split": [ { "subAccount": "loja-sul", "amount": 20.00 } ] }' ``` Здесь инициатор — `loja-centro`: он получает R$ 100,00, платит комиссию и передаёт R$ 20,00 субсчёту `loja-sul`. Субсчёт не может разделить платёж сам с собой. ### Ошибки разделения Все возвращают `400`. Тексты сообщений приходят от API ровно в таком виде: | Сообщение | Когда возникает | | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `Subconta 'X' não existe nesta conta ou não está ativa` | `reference` не принадлежит активному субсчёту этого аккаунта. Эта же ошибка возникает при указании субсчёта другого владельца или кошелька из другого окружения — чтобы указать основной аккаунт, используйте `principal` | | `Subconta 'X' aparece duas vezes no split` | Один и тот же `reference` отправлен в двух элементах — объедините суммы в один элемент | | `A soma do split (R$ Y) excede o líquido da cobrança (R$ Z — bruto R$ A menos taxa de R$ B)` | Разделение не помещается в чистую сумму платежа | | `A conta que origina a cobrança não pode receber rateio de si mesma` | Субсчёт из заголовка `X-Sub-Account` указан и в `split` | | `Esta cobrança já foi criada pela conta principal — o que não for rateado fica nela. Use 'principal' no split apenas quando a cobrança for originada por uma subconta (header X-Sub-Account)` | Платёж создан основным аккаунтом, а в `split` указан `principal` | | `split must contain no more than 10 elements` | В массиве больше 10 элементов | | `split.0.amount must not be less than 0.01` | У какого-то элемента `amount` меньше `0.01` — индекс указывает, у какого именно | ### В выписке При зачислении каждая часть разделения порождает **две строки** типа `internal_transfer`, обе привязаны к платежу через `parentTransactionId`: * **списание** у инициатора — `Split enviado para loja-centro`, либо `Split enviado para a conta principal`, когда получатель — `principal` * **зачисление** на кошелёк получателя — `Split recebido do pagamento {ID платежа}` Обе — настоящие транзакции: [Получить транзакцию](/ru/api-reference/transactions/get) возвращает для каждой `type: internal_transfer`. `parentTransactionId` — связь на уровне выписки, в публичный ответ он не входит. ## Выбор учреждения Каждый счёт PIX выставляется одним из учреждений, привязанных к вашему аккаунту. По умолчанию выбор делает **маршрутизация**, настроенная в панели — фиксированный порядок, разделение по долям или автоматический режим. Если в вашем аккаунте включён **выбор учреждения**, вы можете решать это для каждого счёта, передавая `pspCredentialId` при [создании счёта](/ru/api-reference/pix/create): ```bash theme={null} curl -X POST https://api-gateway.pague.dev/v2/pix \ -H 'Authorization: Bearer eyJhbGciOiJSUzI1NiIs...' \ -H 'Content-Type: application/json' \ -d '{ "amount": 100.00, "description": "Заказ 4821", "pspCredentialId": "6e307aa4-4772-4230-a648-d88cee308f54" }' ``` Без этого поля ничего не меняется: продолжает действовать настроенная маршрутизация с переключением при сбое. ### Где взять ID В панели, в разделе **Настройки → Маршрутизация**. У каждого учреждения ID показан прямо под цифрами, рядом кнопка «Копировать». Он находится именно там, а не в отдельном списке, намеренно: в той же строке видно конверсию за последние 6 часов, итоги за 7 и 30 дней и отвечает ли учреждение. Выбирать учреждение без этих цифр — выбирать вслепую. ID **стабилен**: он не меняется при изменении порядка учреждений, смене режима или отключении другого учреждения. ### Зафиксировать — не значит «предпочесть» Когда вы передаёте `pspCredentialId`, счёт выставляется этим учреждением **или не выставляется вовсе**. Отката к другому нет: | Ситуация | Ответ | | ------------------------------------------------------------------------- | ------------------------------------------------- | | Учреждение недоступно (таймаут, сбой инфраструктуры, отклонённые доступы) | `500` — `Payment service temporarily unavailable` | | У учреждения исчерпан лимит на вывод в текущем цикле | `400` — `reason: out_capacity_exhausted` | Ни в одном из случаев счёт не создаётся в другом учреждении. Это сделано намеренно. Переход к другому учреждению означал бы, что QR родился не там, где вы просили, и вы узнали бы об этом только из ответа — что хуже ошибки как раз для тех, кто фиксирует учреждение ради сверки, лимитов или условий договора. Если конверсия важнее предсказуемости — не передавайте поле: для этого и существует маршрутизация с переключением при сбое. ### Подтверждение в ответе Если вы зафиксировали учреждение, ответ вернёт `pspCredentialId` с тем, которое действительно выставило счёт — используйте его для сверки. Если поля не было в запросе, его не будет и в ответе. ```json Ответ 201 theme={null} { "id": "e3b0c442-98fc-1c14-9afb-f4c8996fb924", "status": "pending", "amount": 100.00, "pixCopyPaste": "00020126580014br.gov.bcb.pix...", "pspCredentialId": "6e307aa4-4772-4230-a648-d88cee308f54", "expiresAt": "2026-08-22T18:00:00.000Z" } ``` ### Ошибки выбора учреждения Все `400`, код в поле `reason`: | `reason` | Когда возникает | | ------------------------ | --------------------------------------------------------------- | | `self_routing_disabled` | В аккаунте не включён выбор учреждения — обратитесь в поддержку | | `credential_not_linked` | `pspCredentialId` не является учреждением PIX этого аккаунта | | `credential_not_enabled` | Учреждение есть в аккаунте, но отключено для приёма счетов | | `credential_inactive` | Учреждение сейчас неактивно | Проверка выполняется **до** любого обращения к учреждению: отказ здесь никогда не оставляет счёт в подвешенном состоянии. Выбор действует только для **счетов PIX**. Выводы по-прежнему уходят через учреждение, назначенное для выводов — там выбор остаётся за нами, поскольку это то же учреждение, которое оплачивает комиссии и возвраты. ## Доступные ресурсы Создание платежей PIX Получение уведомлений о событиях Организация платежей по проектам Создание выводов средств через PIX Просмотр деталей транзакций Просмотр данных аккаунта и баланса Дочерние кошельки с собственным балансом