Introdução - pague.dev

Bem-vindo

A API pague.dev permite integrar o processamento de pagamentos em suas aplicações. Esta documentação cobre todos os endpoints disponíveis para gerenciar clientes, projetos, cobranças, transações e pagamentos PIX.

URL Base

Todas as requisições devem ser feitas para:

https://api-gateway.pague.dev/v2

Autenticação

A autenticação é feita em duas etapas: você troca as credenciais da sua conta por um access token de curta duração e envia esse token no header Authorization de cada requisição.

1. Obtenha suas credenciais

Crie uma credencial de API no Dashboard. Ela é composta por um client_id e um client_secret:

mp_live_* — credencial de produção
mp_test_* — credencial de sandbox

O client_secret é exibido uma única vez, no momento da criação. Guarde-o em local seguro.

2. Gere um access token

Troque suas credenciais por um token no endpoint de autenticação:

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

Resposta

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

Credenciais inválidas ou revogadas retornam 401 {"error": "Unauthorized", "message": "Invalid credentials"}.

3. Use o token nas requisições

Envie o token no header Authorization:

curl https://api-gateway.pague.dev/v2/account \
  -H 'Authorization: Bearer eyJhbGciOiJSUzI1NiIs...'

O token expira em 300 segundos (5 minutos). Gere um novo token no /auth quando ele expirar — não há refresh token.

Permissões

Cada credencial possui permissões granulares que determinam quais endpoints ela pode acessar. As permissões são atribuídas no momento da criação da credencial.

Permissões disponíveis

Permissão	Descrição
`FULL_ACCESS`	Acesso completo a todos os endpoints da API
`PIX:WRITE`	Criar cobranças PIX
`PROJECT:WRITE`	Criar projetos
`PROJECT:READ`	Listar e buscar projetos
`TRANSACTION:READ`	Buscar transações
`WITHDRAWAL:WRITE`	Criar saques via PIX
`METRICS:READ`	Obter métricas de receita
`ACCOUNT:READ`	Visualizar dados da conta e saldo
`SUBACCOUNT:WRITE`	Criar subcontas
`SUBACCOUNT:READ`	Listar subcontas

A permissão FULL_ACCESS concede acesso a todos os endpoints, equivalente a possuir todas as permissões listadas acima.Exceção: o acesso a subcontas não é permissão. FULL_ACCESS cobre os endpoints de /sub-accounts (criar e listar carteiras), mas não libera o header X-Sub-Account — esse é um campo separado da credencial. Veja Subcontas.

Restrição por IP

Opcionalmente, você pode restringir uma credencial a uma lista de IPs permitidos. Quando a lista está configurada, requisições originadas de IPs fora dela são rejeitadas com erro 403 Forbidden. Recomendamos configurar a restrição de IP em credenciais com permissões sensíveis, como FULL_ACCESS e WITHDRAWAL:WRITE.

Subcontas

Uma conta pode ter subcontas: carteiras filhas com saldo totalmente independente do saldo da conta principal. Cada subconta é identificada por um reference escolhido por você. Subcontas e split funcionam nos dois ambientes: uma credencial mp_test_* cria e opera carteiras no sandbox como uma mp_live_* faz em produção. Para operar em uma subconta, envie o header X-Sub-Account com o reference dela:

curl https://api-gateway.pague.dev/v2/account \
  -H 'Authorization: Bearer eyJhbGciOiJSUzI1NiIs...' \
  -H 'X-Sub-Account: loja-centro'

O header é opcional e é aceito em todos os endpoints, exceto /auth e os próprios endpoints de /sub-accounts — criar e listar subcontas acontece sempre na conta principal. Quando presente, a operação inteira acontece na subconta — criar cobrança, consultar transação, criar saque, consultar saldo. Quando ausente, a operação acontece na conta principal. X-Sub-Account: principal também resolve para a conta principal, e é equivalente a omitir o header.

O reference é definido por você na criação da subconta e é imutável. Ele precisa casar com ^[a-z0-9][a-z0-9_-]{1,31}$: de 2 a 32 caracteres, apenas letras minúsculas, números, - e _, começando por letra minúscula ou número.principal é palavra reservada: ela identifica a conta principal no split e no header X-Sub-Account, então nenhuma subconta pode ser criada com esse reference.

Subcontas no sandbox

O header X-Sub-Account, o split, a palavra principal e a transferência interna funcionam no sandbox exatamente como em produção. O mesmo reference pode existir nos dois ambientes. A conta sandbox e a de produção são contas distintas, então loja-centro no sandbox e loja-centro em produção convivem sem colidir. É isso que permite o mesmo payload rodar nos dois: você testa com mp_test_*, troca a chave por uma mp_live_* e vai para produção sem mudar uma linha.

As duas árvores são isoladas. Uma credencial mp_test_* só enxerga as carteiras da árvore sandbox; uma mp_live_*, só as de produção.Isso vale para o split: ratear de uma carteira sandbox para uma carteira de produção é recusado, porque a de produção não existe naquele contexto. O erro é o mesmo Subconta 'X' não existe nesta conta ou não está ativa.

A carteira precisa ser criada em cada ambiente. Criar loja-centro em produção não a faz aparecer no sandbox — são dois cadastros, de propósito. A taxa é a mesma nos dois ambientes, e isso é deliberado: a carteira sandbox herda a taxa da conta de produção justamente para que o teto do rateio, que é o líquido e não o bruto, se comporte igual. Um split que passa no sandbox passa em produção. Uma carteira sandbox originando R

20,00 e rateando R

1,00 fecha em +R $18,80** na originadora e **+R$ 1,00 no destino, com taxa de R$ 0,20 — os mesmos números de produção.

Transferência interna

Uma subconta nasce com saldo zero. A transferência interna é como você abastece uma carteira nova — e como devolve saldo para a conta principal depois. Ela move saldo entre contas da mesma titularidade: da conta principal para uma carteira, de uma carteira para a conta principal, ou entre carteiras irmãs. Não é PIX e não é saque — é troca de bolso. O dinheiro sai de uma conta e entra na outra, aparece nos dois extratos, e o saldo total da conta não muda.

Não existe endpoint de transferência interna na API pública. A operação é feita no Dashboard, na tela de carteiras. Não adianta procurar uma rota: ela não faz parte deste contrato.

O que vale saber antes de transferir:

Só dentro da titularidade. Transferir para conta de terceiro não existe aqui — isso é PIX, e o caminho é Criar Saque PIX.
O teto é o saldo gastável da origem, não o disponível bruto: é o disponível menos a dívida de estorno em aberto, o mesmo critério que vale para o saque.
Não tem desfazer. Uma transferência errada se corrige transferindo no sentido inverso.

No extrato, cada transferência gera duas linhas de tipo internal_transfer — uma saída (valor negativo) na origem e uma entrada (positiva) no destino. É o mesmo tipo das pernas de split: nos dois casos, GET /transactions/{id} devolve type: internal_transfer.

Limites da subconta

Por padrão, a carteira compartilha o orçamento de limite da conta principal. Esse é o comportamento de toda subconta criada pela API ou pelo painel: o consumo de todas as carteiras soma contra o mesmo teto do titular.

Criar carteiras não multiplica o seu limite. Como o orçamento é um só, uma cobrança em uma carteira pode ser recusada por limite por causa do movimento de outra carteira da mesma conta — inclusive de uma carteira que o seu código nem tocou naquela requisição. Isso é o comportamento esperado, não uma falha de isolamento.

A plataforma pode, caso a caso, dar orçamento próprio a uma carteira, separando o consumo dela do resto da conta. É decisão da plataforma: não é configurável pelo lojista, não tem endpoint e não é autoatendimento — se a sua operação precisa disso, fale com o suporte. No sandbox não há limite: o teto compartilhado descrito aqui só se manifesta em produção. Isso não é específico de carteiras — vale para qualquer operação sandbox —, então não conclua dos seus testes que o compartilhamento sumiu. Não confunda com o SUB_ACCOUNT_QUOTA_EXCEEDED da tabela abaixo: aquele é o teto de quantas carteiras a conta pode ter, e não tem relação com valor transacionado.

Erros de subconta

HTTP	Código	Quando acontece
404	`SUB_ACCOUNT_NOT_FOUND`	O `reference` informado não existe nesta conta
403	`SUB_ACCOUNT_FORBIDDEN`	A credencial não está autorizada a operar essa subconta
403	`SUB_ACCOUNT_SUSPENDED`	A subconta está suspensa
409	`SUB_ACCOUNT_QUOTA_EXCEEDED`	O limite de subcontas da conta foi atingido
409	`SUB_ACCOUNT_REFERENCE_TAKEN`	O `reference` já está em uso nesta conta
400	`SUB_ACCOUNT_INVALID_REFERENCE`	O `reference` pedido na criação é `principal`, palavra reservada da conta principal

Duas coisas diferentes controlam o acesso a carteiras, e elas falham de formas diferentes:

A permissão da credencial vale para os endpoints de /sub-accounts: listar exige SUBACCOUNT:READ, criar exige SUBACCOUNT:WRITE. Sem ela, a resposta é 403 Insufficient permissions. Required: SUBACCOUNT:READ.
O escopo da credencial vale para operar dentro de uma carteira: é ele que decide quais carteiras aquela credencial alcança pelo header X-Sub-Account e pelo split, e é ele que devolve SUB_ACCOUNT_FORBIDDEN.

Por isso criar uma cobrança com X-Sub-Account e split exige só PIX:WRITE: as permissões SUBACCOUNT:* governam o cadastro de carteiras, não o uso delas.

O escopo nasce desligado, e nenhuma permissão o substitui. Uma credencial recém-criada — inclusive uma com acesso total — recebe 403 SUB_ACCOUNT_FORBIDDEN no primeiro request com X-Sub-Account enquanto o escopo estiver em “sem acesso”. Ligue em Configurações → Integração → Credenciais de API, no campo Acesso a subcontas (vale na hora, inclusive para tokens já emitidos). É proposital: sem isso, toda credencial que já existia passaria a alcançar a árvore inteira no dia em que a primeira carteira fosse criada.

Subcontas são criadas em Criar Subconta e listadas em Listar Subcontas. Nos webhooks, o campo subAccount indica de qual carteira é o evento — veja Webhooks.

Split de Pagamento

Uma cobrança PIX pode repartir parte do valor recebido com outras carteiras da mesma conta — subcontas ou a própria conta principal. Envie o campo opcional split na criação da cobrança:

{
  "amount": 100.00,
  "description": "Pedido 4821",
  "split": [
    { "subAccount": "loja-centro", "amount": 30.00 },
    { "subAccount": "loja-sul", "amount": 20.00 }
  ]
}

Campo	Tipo	Descrição
`split`	array	Opcional. No máximo 10 itens
`split[].subAccount`	string	`reference` da subconta que recebe o rateio, ou `principal` para a conta principal
`split[].amount`	number	Valor em reais destinado a essa carteira — mínimo `0.01`, no máximo 2 casas decimais

Os valores são fixos, em reais: não existe rateio por percentual. A resposta da criação ecoa o split aceito, no mesmo formato e também em reais — se ele veio na resposta, as subcontas existiam e a soma cabia. A validação acontece antes de a cobrança ser gerada: um split inválido devolve 400 e nenhuma cobrança é criada.

Quem cria a cobrança é o originador

O originador é a conta — ou a subconta do header X-Sub-Account — que criou a cobrança. É ele que recebe o valor bruto, paga a taxa cheia e só então reparte o que sobrou. A taxa não é rateada entre os destinatários. Cada subconta do split recebe exatamente o amount que você pediu, sem desconto nenhum.

O teto do rateio é o líquido, não o bruto

O máximo que pode ser repartido é o valor da cobrança menos a taxa. Numa cobrança de R $100,00** com taxa de **R$ 1,49, o líquido é **R

98,51** — e é esse o teto. Um `split` somando R

98,51 é aceito (o originador fica com zero). Um split somando **R

99,00** é recusado, mesmo sendo menor que os R

100,00 da cobrança:

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

A taxa considerada é a da conta que origina a cobrança, para o método PIX.

Estorno e MED atingem só o originador. Quem recebeu rateio nunca é debitado: não existe estorno em cadeia nem recolhimento do valor já repassado. Um reembolso, um chargeback ou um bloqueio MED sobre a cobrança debita exclusivamente a conta que a originou.A consequência é sua para administrar: se você repartir 100% do líquido e a transação for estornada, o originador arca com o prejuízo inteiro — e o débito pode deixar o saldo dele negativo. Guardar uma margem no originador é decisão do integrador, não do sistema.

O rateio acontece na liquidação

Criar a cobrança não move dinheiro nenhum. O split fica registrado na cobrança e só é executado quando o pagamento é confirmado — é nesse momento que os valores saem do saldo do originador e entram nas carteiras de destino. Cobrança expirada ou nunca paga não gera rateio.

A taxa da conta pode mudar entre a criação da cobrança e o pagamento. Se, na liquidação, a soma do split não couber mais no líquido, as pernas são atendidas na ordem em que você as enviou, até o líquido acabar: a última pode ser reduzida, ou não acontecer. A liquidação nunca falha por causa disso — ordene o array por prioridade e concilie pelo split do webhook payment_completed, que traz o que foi efetivamente distribuído.

Só carteiras da mesma conta

subAccount aceita o reference de uma subconta ativa da mesma conta, ou a palavra reservada principal. Split para fora da titularidade não existe nesta API.

Rateio de volta para a conta principal

principal é a única palavra que não é reference de ninguém: ela endereça a conta principal como destino do rateio. Serve para o caminho inverso do resto desta seção — a cobrança nasce em uma subconta e parte do líquido volta para a conta principal:

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

Com uma taxa de R

0,20, o resultado é: `loja-centro` fica com **R

14,80** (R

20,00 menos R

0,20 de taxa menos R

5,00 de rateio) e a conta principal recebe **R

5,00**. Quem origina continua sendo loja-centro — é ela que paga a taxa cheia, e a conta principal recebe o rateio limpo, como qualquer outro destinatário. O eco na resposta e o split do webhook trazem "subAccount": "principal", igual às demais carteiras.

Uma cobrança originada pela conta principal não pode ratear para principal — seria rateio para si mesma, e o que não é repartido já fica nela de qualquer forma. Esse caso devolve 400.

Para mover saldo entre carteiras fora de um pagamento, use a transferência interna — operação explícita, que não fica pendurada na liquidação de uma cobrança.

Split a partir de uma subconta

O header X-Sub-Account e o campo split respondem a perguntas diferentes e funcionam juntos: o header diz quem origina a cobrança, o split diz para quem vai parte do líquido. Uma subconta pode originar uma cobrança e repartir com uma irmã. Nesse caso a conta principal não é tocada — não recebe nada e não paga taxa nenhuma:

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 é a originadora: recebe os R

100,00, paga a taxa e repassa R

20,00 para loja-sul. Uma subconta não pode repartir consigo mesma.

Erros do split

Todos retornam 400:

Mensagem	Quando acontece
`Subconta 'X' não existe nesta conta ou não está ativa`	O `reference` não é de uma subconta ativa desta conta. É também o erro de quem endereça uma subconta de outra titularidade ou uma carteira do outro ambiente — para endereçar a conta principal, use `principal`
`Subconta 'X' aparece duas vezes no split`	O mesmo `reference` foi enviado em dois itens — junte os valores em um item só
`A soma do split (R$ Y) excede o líquido da cobrança (R$ Z — bruto R$ A menos taxa de R$ B)`	O rateio não cabe no líquido da cobrança
`A conta que origina a cobrança não pode receber rateio de si mesma`	A subconta do header `X-Sub-Account` também aparece no `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)`	A cobrança foi criada pela conta principal e o `split` inclui `principal`
`split must contain no more than 10 elements`	O array tem mais de 10 itens
`split.0.amount must not be less than 0.01`	Algum item tem `amount` abaixo de `0.01` — o índice indica qual

No extrato

Na liquidação, cada perna do split gera duas linhas de tipo internal_transfer, ambas amarradas à cobrança pelo parentTransactionId:

uma saída no originador — Split enviado para loja-centro, ou Split enviado para a conta principal quando o destino é principal
uma entrada na carteira que recebeu — Split recebido do pagamento {id da cobrança}

As duas são transações de verdade: Buscar Transação devolve type: internal_transfer para cada uma. O parentTransactionId é vínculo de extrato e não faz parte da resposta pública.

Escolha da Instituição

Toda cobrança PIX é emitida por uma das instituições ligadas à sua conta. Por padrão, quem escolhe é o roteamento configurado no painel — ordem fixa, divisão por fatias ou automático. Se a sua conta tem a escolha de instituição habilitada, você pode decidir isso por cobrança, enviando pspCredentialId na criação da cobrança:

curl -X POST https://api-gateway.pague.dev/v2/pix \
  -H 'Authorization: Bearer eyJhbGciOiJSUzI1NiIs...' \
  -H 'Content-Type: application/json' \
  -d '{
    "amount": 100.00,
    "description": "Pedido 4821",
    "pspCredentialId": "6e307aa4-4772-4230-a648-d88cee308f54"
  }'

Sem o campo, nada muda: o roteamento configurado continua valendo, com failover.

Onde encontrar o ID

No painel, em Configurações → Roteamento. Cada instituição mostra o ID logo abaixo dos números, com um botão de copiar. É de propósito que ele fique ali e não numa lista à parte: na mesma linha você vê a conversão das últimas 6 horas, o fechamento de 7 e 30 dias e se a instituição está respondendo. Escolher instituição sem olhar esses números é escolher no escuro. O ID é estável: não muda quando você reordena as instituições, troca de modo ou desabilita outra.

Fixar não é preferir

Quando você envia pspCredentialId, a cobrança sai por aquela instituição ou não sai. Não existe fallback:

Situação	Resposta
Instituição fora do ar (timeout, erro de infra, credencial recusada)	`500` — `Payment service temporarily unavailable`
Instituição sem capacidade de saída no ciclo	`400` — `reason: out_capacity_exhausted`

Em nenhum dos dois a cobrança é criada em outra instituição. Isso é deliberado. Cair para outra faria o QR nascer num lugar que você não pediu, e você só descobriria conferindo a resposta — o que é pior do que falhar, justamente para quem fixa a instituição por conciliação, limite ou contrato. Quem prefere conversão a previsibilidade não deve enviar o campo: é para isso que o roteamento com failover existe.

Recibo na resposta

Fixou a instituição, a resposta ecoa pspCredentialId com a que realmente emitiu — use na conciliação. Sem o campo no request, ele também não vem na resposta.

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

Erros da escolha

Todos 400, com o código em reason:

`reason`	Quando acontece
`self_routing_disabled`	A conta não tem a escolha de instituição habilitada — fale com o suporte
`credential_not_linked`	O `pspCredentialId` não é uma instituição de PIX desta conta
`credential_not_enabled`	A instituição existe na conta, mas está desabilitada para receber cobranças
`credential_inactive`	A instituição está inativa no momento

A validação acontece antes de qualquer chamada à instituição: recusa aqui nunca deixa cobrança pendurada.

A escolha vale só para cobranças PIX. Saques continuam saindo pela instituição definida para saque — ali a escolha é nossa, porque é a mesma que paga taxas e devoluções.

Recursos Disponíveis

PIX

Criar cobranças PIX

Webhooks

Receber notificações de eventos

Projetos

Organizar pagamentos por projeto

Saques

Criar saques via PIX

Transações

Visualizar detalhes de transações

Conta

Consultar dados da conta e saldo

Subcontas

Carteiras filhas com saldo próprio

​Bem-vindo

​URL Base

​Autenticação

​1. Obtenha suas credenciais

​2. Gere um access token

​3. Use o token nas requisições

​Permissões

​Permissões disponíveis

​Restrição por IP

​Subcontas

​Subcontas no sandbox

​Transferência interna

​Limites da subconta

​Erros de subconta

​Split de Pagamento

​Quem cria a cobrança é o originador

​O teto do rateio é o líquido, não o bruto

​O rateio acontece na liquidação

​Só carteiras da mesma conta

​Rateio de volta para a conta principal

​Split a partir de uma subconta

​Erros do split

​No extrato

​Escolha da Instituição

​Onde encontrar o ID

​Fixar não é preferir

​Recibo na resposta

​Erros da escolha

​Recursos Disponíveis

PIX

Webhooks

Projetos

Saques

Transações

Conta

Subcontas

Bem-vindo

URL Base

Autenticação

1. Obtenha suas credenciais

2. Gere um access token

3. Use o token nas requisições

Permissões

Permissões disponíveis

Restrição por IP

Subcontas

Subcontas no sandbox

Transferência interna

Limites da subconta

Erros de subconta

Split de Pagamento

Quem cria a cobrança é o originador

O teto do rateio é o líquido, não o bruto

O rateio acontece na liquidação

Só carteiras da mesma conta

Rateio de volta para a conta principal

Split a partir de uma subconta

Erros do split

No extrato

Escolha da Instituição

Onde encontrar o ID

Fixar não é preferir

Recibo na resposta

Erros da escolha

Recursos Disponíveis