Введение - 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. Сгенерируйте токен доступа

Обменяйте ваши учётные данные на токен через эндпоинт аутентификации:

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

Ответ

{
  "access_token": "eyJhbGciOiJSUzI1NiIs...",
  "token_type": "Bearer",
  "expires_in": 300
}

Недействительные или отозванные учётные данные возвращают 401 {"error": "Unauthorized", "message": "Invalid credentials"}.

3. Используйте токен в запросах

Отправляйте токен в заголовке Authorization:

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 — это отдельное поле учётных данных. См. Субсчета.

Ограничение по IP

При желании вы можете ограничить учётные данные списком разрешённых IP-адресов. Когда список настроен, запросы с IP-адресов вне списка отклоняются с ошибкой 403 Forbidden. Мы рекомендуем настраивать ограничение по IP для учётных данных с чувствительными разрешениями, такими как FULL_ACCESS и WITHDRAWAL:WRITE.

Субсчета

У аккаунта могут быть субсчета — дочерние кошельки, баланс которых полностью независим от баланса основного аккаунта. Каждый субсчёт идентифицируется по reference, который вы задаёте сами. Субсчета и разделение платежа работают в обоих окружениях: учётные данные mp_test_* создают кошельки и работают с ними в песочнице так же, как mp_live_* в продакшене. Чтобы выполнить операцию в субсчёте, отправьте заголовок X-Sub-Account с его reference:

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.
Потолок — доступный к трате баланс источника, а не полный доступный остаток: это доступное за вычетом непогашенного долга по возвратам, тот же критерий, что и для вывода средств.
Отмены нет. Ошибочный перевод исправляется обратным переводом.

В выписке каждый перевод порождает две строки типа internal_transfer — списание (отрицательная сумма) у источника и зачисление (положительная) у получателя. Это тот же тип, что и у частей разделения платежа: в обоих случаях 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, поле Доступ к субсчетам (действует сразу, в том числе для уже выданных токенов). Так сделано намеренно: иначе все ранее созданные учётные данные получили бы доступ ко всему дереву в день создания первого кошелька.

Субсчета создаются через Создать субсчёт, а их список доступен в Списке субсчетов. В вебхуках поле subAccount указывает, какому кошельку принадлежит событие — см. Вебхуки.

Разделение платежа

Платёж PIX может разделить часть полученной суммы с другими кошельками того же аккаунта — субсчетами или самим основным аккаунтом. Отправьте необязательное поле split при создании платежа:

{
  "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 самого платежа:

Ответ 400

{
  "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, в котором приходит фактически распределённое.

Только кошельки того же аккаунта

subAccount принимает reference активного субсчёта того же аккаунта либо зарезервированное слово principal. Разделения за пределы своей структуры в этом API нет.

Разделение обратно в основной аккаунт

principal — единственное слово, которое не является ничьим reference: оно указывает на основной аккаунт как на получателя части суммы. Это обратный путь по отношению ко всему остальному в этом разделе: платёж создаётся в субсчёте, и часть чистой суммы возвращается в основной аккаунт:

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.

Чтобы переводить остатки между кошельками вне платежа, используйте внутренний перевод — явную операцию, не привязанную к зачислению платежа.

Разделение из субсчёта

Заголовок X-Sub-Account и поле split отвечают на разные вопросы и работают вместе: заголовок говорит, кто инициирует платёж, а split — кому уходит часть чистой суммы. Субсчёт может инициировать платёж и разделить его с «сестринским» субсчётом. При этом основной аккаунт не затрагивается — он ничего не получает и не платит комиссию:

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 платежа}

Обе — настоящие транзакции: Получить транзакцию возвращает для каждой type: internal_transfer. parentTransactionId — связь на уровне выписки, в публичный ответ он не входит.

Выбор учреждения

Каждый счёт PIX выставляется одним из учреждений, привязанных к вашему аккаунту. По умолчанию выбор делает маршрутизация, настроенная в панели — фиксированный порядок, разделение по долям или автоматический режим. Если в вашем аккаунте включён выбор учреждения, вы можете решать это для каждого счёта, передавая pspCredentialId при создании счёта:

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 с тем, которое действительно выставило счёт — используйте его для сверки. Если поля не было в запросе, его не будет и в ответе.

Ответ 201

{
  "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

Вебхуки

Получение уведомлений о событиях

Проекты

Организация платежей по проектам

Выводы средств

Создание выводов средств через PIX

Транзакции

Просмотр деталей транзакций

Аккаунт

Просмотр данных аккаунта и баланса

Субсчета

Дочерние кошельки с собственным балансом

​Добро пожаловать

​Базовый URL

​Аутентификация

​1. Получите ваши учётные данные

​2. Сгенерируйте токен доступа

​3. Используйте токен в запросах

​Разрешения

​Доступные разрешения

​Ограничение по IP

​Субсчета

​Субсчета в песочнице

​Внутренний перевод

​Лимиты субсчёта

​Ошибки субсчетов

​Разделение платежа

​Инициатор — тот, кто создал платёж

​Потолок разделения — чистая сумма, а не брутто

​Разделение происходит при зачислении

​Только кошельки того же аккаунта

​Разделение обратно в основной аккаунт

​Разделение из субсчёта

​Ошибки разделения

​В выписке

​Выбор учреждения

​Где взять ID

​Зафиксировать — не значит «предпочесть»

​Подтверждение в ответе

​Ошибки выбора учреждения

​Доступные ресурсы

PIX

Вебхуки

Проекты

Выводы средств

Транзакции

Аккаунт

Субсчета

Добро пожаловать

Базовый URL

Аутентификация

1. Получите ваши учётные данные

2. Сгенерируйте токен доступа

3. Используйте токен в запросах

Разрешения

Доступные разрешения

Ограничение по IP

Субсчета

Субсчета в песочнице

Внутренний перевод

Лимиты субсчёта

Ошибки субсчетов

Разделение платежа

Инициатор — тот, кто создал платёж

Потолок разделения — чистая сумма, а не брутто

Разделение происходит при зачислении

Только кошельки того же аккаунта

Разделение обратно в основной аккаунт

Разделение из субсчёта

Ошибки разделения

В выписке

Выбор учреждения

Где взять ID

Зафиксировать — не значит «предпочесть»

Подтверждение в ответе

Ошибки выбора учреждения

Доступные ресурсы