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.

A API só aceita chamadas dos IPs do seu servidor cadastrados na sua credencial. Você gera o client_secret e informa os IPs de saída no painel, em O segredo e os IPs no painel.

Token #

POST /oauth/token

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

curl -u "loja01:SEU_CLIENT_SECRET" -d "grant_type=client_credentials" -d "scope=cob.write cob.read pix.read ex.saldo.read ex.config.read" https://api.amunpay.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 ex.config.read
→ 200
{
  "access_token": "eyJhbGciOiJFUzI1NiIsImtpZCI6IjAxSjEifQ...",
  "token_type": "Bearer",
  "expires_in": 900,
  "scope": "cob.write cob.read pix.read ex.saldo.read ex.config.read"
}

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 token só é emitido e só vale para chamadas vindas dos IPs cadastrados: de outro IP, o pedido do token e cada chamada respondem 403 origem_nao_permitida. Sem nenhum IP cadastrado, nenhuma chamada passa.

O segredo e os IPs no painel #

O gestor da sua empresa gera o client_secret no painel, em Integração, na aba Credenciais, com o código do segundo fator. O segredo aparece uma vez, ao lado do client_id, cada um com o botão de copiar, e nunca é mostrado de novo. Perdeu, gere outro: o anterior deixa de valer na hora. Os tokens já emitidos valem até expirar, salvo quando você marca suspeita de vazamento, que os derruba também.

O painel aceita IP público, com prefixo até /24 (IPv4) ou /48 (IPv6), até 20 IPs. Todo ato sobre a credencial vai por e-mail aos contatos da sua empresa, sem o segredo. Sem contato técnico nem financeiro cadastrado, o painel não gera nem inclui IP.

Só o gestor gera e muda os IPs. Os outros usuários veem o client_id e os IPs. Se a AmunPay ligar a espera do segundo fator para a sua conta, o gestor que acabou de ativar o segundo fator, que foi promovido, reativado ou que teve a senha redefinida por outra pessoa espera 24 horas para gerar. A credencial de uma sub-conta com credencial própria é gerada pela empresa titular.

Se a tela disser que a funcionalidade não está habilitada para a sua conta, fale com a AmunPay. Ela também gera o segredo e cadastra os IPs para você, e pela AmunPay o IP novo vale na hora.

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": "01J8Z3QK5W7R2N4M6P8T0V2X4Y" },
  "custodia": { "tipo": "PROPRIA", "custodiante": "Conta PI", "recusaAntesDoCredito": true },
  "depositoPorChave": { "modo": "RECUSAR" }
}

Escopos #

Erros do token #

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

Erros nas chamadas #