Começar

Autenticação, ambientes e escopos

Uma chave por ambiente, com só os escopos de que a integração precisa.

Como autenticar

Envie a chave no cabeçalho Authorization: Bearer. Chaves de teste começam com gw_test_ e chaves de produção com gw_live_.

Cabeçalho

Authorization: Bearer gw_live_AbCdEfGh.xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Uma chave inválida, revogada, expirada, do outro ambiente ou sem o escopo da rota recebe 401 com invalid_api_key. O motivo exato não é revelado, para não ajudar quem testa chaves roubadas.

Ambientes

Cada ambiente aceita só as próprias chaves. Chaves gw_test_ nunca movimentam dinheiro e funcionam apenas no ambiente de teste; peça o endereço dele ao suporte. Em produção, use https://api.mainumpay.com com uma chave gw_live_.

Escopos

Cada rota exige um escopo. Uma chave nunca recebe mais poder do que o usuário que a criou, e escopos novos não são dados automaticamente a chaves antigas.

Escopo	Libera
`charges:write`	POST /v1/checkout-sessions · POST /v1/charges · POST /v1/card-charges
`charges:read`	GET /v1/checkout-sessions/{sessionId} · GET /v1/charges · GET /v1/charges/{chargeId} · GET /v1/products · GET /v1/products/{productId}
`transactions:read`	GET /v1/transactions
`balance:read`	GET /v1/balance
`statement:read`	GET /v1/statement
`withdrawals:read`	GET /v1/withdrawals · GET /v1/withdrawals/{withdrawalId}
`withdrawals:write`	POST /v1/withdrawals
`med:read`	GET /v1/med-cases · GET /v1/med-cases/{medCaseId}
`events:read`	GET /v1/events · GET /v1/events/{eventId}
`withdrawals:external_write`	Saques para chaves Pix de outro titular, junto com `withdrawals:write`.

Saques para terceiros pedem um escopo a mais. withdrawals:write envia só para o CPF ou CNPJ verificado da conta. Para outras chaves Pix, a chave também precisa de withdrawals:external_write, liberado pelo admin.

Limites de requisição

Os limites valem por minuto, por IP, por chave e por conta. Toda resposta traz X-RateLimit-Limit, X-RateLimit-Remaining e X-RateLimit-Reset; ao passar do limite você recebe 429 com Retry-After em segundos.