Ir para o conteúdo
P Prontopag API PixPáginas

Autenticação

A credencial da sua máquina é o par client_id e client_secret. Troque os dois por um token OAuth2 (client_credentials) e envie o token em Authorization: Bearer em toda chamada a /v2/. O token vale 900 segundos.

Token #

POST /oauth/token

O client_id e o client_secret vão em HTTP Basic. É o que curl -u faz:

curl -u "prod_loja01:SEU_CLIENT_SECRET" -d "grant_type=client_credentials" -d "scope=cob.write cob.read pix.read ex.saldo.read" https://api.prontopag.com/oauth/token

POST /oauth/token
Authorization: Basic base64(client_id:client_secret)
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&scope=cob.write cob.read pix.read ex.saldo.read
→ 200
{
  "access_token": "eyJhbGciOiJFUzI1NiIsImtpZCI6IjAxSjEifQ...",
  "token_type": "Bearer",
  "expires_in": 900,
  "scope": "cob.write cob.read pix.read ex.saldo.read"
}
Campo Tipo Obrigatório Descrição
grant_type string sim Sempre client_credentials.
scope string não Escopos separados por espaço, no máximo 10, dentro dos concedidos. Omitido, o token traz todos os escopos concedidos.

Como alternativa ao Basic, client_id e client_secret podem ir no corpo do formulário. Mandar os dois nas duas formas com valores diferentes responde 400 invalid_request.

O segredo é entregue uma vez, na admissão, e nunca é mostrado de novo. Perdeu, peça a rotação ao suporte: o anterior deixa de valer na hora, e o novo é entregue uma vez. Os tokens já emitidos continuam valendo até expirar, salvo rotação por vazamento.

Se quiser, o suporte prende a credencial aos IPs de saída da sua máquina. Com a lista ligada, o token só é emitido e só vale de dentro dela.

Primeira chamada #

GET /v2/ex/config

GET /v2/ex/config
→ 200
{
  "conta": { "status": "ATIVA", "desde": "2026-09-18T09:20:23Z" },
  "capacidades": {
    "pix": true,
    "subcontas": true,
    "split": true,
    "baas": false
  },
  "recebedor": { "chave": "7d9f0335-8dcc-4054-9bf9-0dbd61d36906" },
  "custodia": { "tipo": "PROPRIA", "custodiante": "Conta PI" }
}
Campo Tipo Descrição
conta.status string ATIVA é o único estado que opera.
capacidades objeto O que esta conta pode usar. Leia antes de assumir.
recebedor.chave string A chave Pix da sua conta.
custodia.tipo string PROPRIA ou PARCEIRA.

Escopos #

Escopo O que libera
cob.read, cob.write Cobranças.
pix.read, pix.write Pix recebidos e devoluções.
ex.pix.send, ex.pix.send.read Saques.
ex.saldo.read, ex.extrato.read Saldo, extrato, transações e resumo.
ex.webhook.read, ex.webhook.write, ex.eventos.read Webhooks e o feed de eventos.
ex.subcontas.read, ex.subcontas.write Sub-contas.
ex.limites.read, ex.limites.write, ex.bloqueios.read Limites e bloqueios de saldo.
ex.config.read GET /v2/ex/config.

Erros do token #

O POST /oauth/token responde no formato { "error", "error_description" }.

Status error Quando
401 invalid_client Segredo errado, client_id desconhecido ou credencial suspensa. A resposta não diz qual.
400 invalid_request Credencial ausente ou malformada, ou Basic e corpo divergentes.
400 invalid_scope Escopo fora dos concedidos, ou mais de 10.
403 origem_nao_permitida O IP de origem está fora da allowlist da credencial.
429 invalid_client Cinco segredos errados seguidos do mesmo IP. Espere o Retry-After; a tentativa durante a espera não é conferida.
429 limite_requisicoes Mais de 2 pedidos por segundo do mesmo IP (rajada de 20). Espere o Retry-After.
413 corpo_grande_demais O corpo passa de 4 KiB.

Erros nas chamadas #

Status title Quando
401 acesso_negado Chamada sem Authorization: Bearer.
401 token_invalido Token inválido ou expirado. Renove.
401 token_revogado A credencial foi revogada, ou o segredo foi rotacionado por vazamento. Renovar não resolve.
403 origem_nao_permitida O IP de origem está fora da allowlist da credencial. Renovar não resolve.
403 escopo_insuficiente O token não tem o escopo da rota. Renovar não resolve.
403 merchant_nao_provisionado O client_id ainda não tem conta.
403 conta_bloqueada A conta não está ATIVA.