Comece por aqui

Autenticação

Toda chamada leva a sua chave privada no cabeçalho Authorization. As chaves são criadas no painel, em Integrações › API.

Como enviar a chave

Authorization: Bearer gp_live_1a2b3c4d5e6f_0123456789abcdef0123456789abcdef0123456789abcdef
  • Formato: gp_live_ + 12 caracteres + _ + 48 caracteres (letras a-f e números).
  • A parte gp_live_ + os 12 primeiros caracteres é o identificador público da chave (aparece no painel). O resto é segredo.
  • A chave privada inteira aparece uma única vez, na criação. Guardamos só uma versão embaralhada (hash): se perder, gere outra.
  • Chave de produção começa com gp_live_. Para testar sem Pix de verdade, use a chave de teste gp_test_ (mesmo formato): veja Modo de teste.

Pedido feito por http:// recebe 403 https_obrigatorio e não é redirecionado, porque a chave já teria passado aberta pela internet. Se isso acontecer, troque a chave no painel.

Permissões

Cada chave tem uma ou mais permissões. Chamada sem a permissão daquele endereço recebe 403 sem_permissao.

Permissão no painelLibera
Criar/consultar transações/charges
Consultar dados da conta e saldo/balance
Criar/consultar saques/withdrawals

Chave com permissão de saque tem regras a mais:

  • Sempre tem data de validade, de no máximo 365 dias.
  • Só cria saque se a conta tiver pelo menos um IP autorizado (senão: 403 ip_obrigatorio).
  • Pode ser criada com a opção Exigir minha aprovação: o saque fica esperando você aprovar no painel (status aguardando_sua_aprovacao).

IPs autorizados

Em Integrações › API você pode cadastrar até 20 IPs ou faixas (IPv4 de /16 a /32, IPv6 de /48 a /128). Com a lista preenchida, pedido de outro IP recebe 403 ip_nao_autorizado. Com a lista vazia, qualquer IP é aceito (menos para saques).

Validade, troca e revogação

  • Você pode dar uma data de validade à chave (até 5 anos). Depois dela: 401 chave_expirada.
  • Trocar a chave gera uma nova chave privada com o mesmo identificador; a antiga para na hora.
  • Revogar desliga a chave para sempre: 401 nao_autorizado.
  • Cada conta pode ter até 5 chaves ativas de produção e até 5 de teste.

Quando a chave é recusada

HTTPCódigoQuando
401nao_autorizadoChave errada, revogada ou cabeçalho fora do formato.
401chave_expiradaPassou da data de validade.
403https_obrigatorioPedido chegou por http.
403conta_nao_aprovadaConta ainda em análise.
403ip_nao_autorizadoIP fora da lista de IPs autorizados.
403sem_permissaoA chave não tem a permissão daquele endereço.
403recurso_indisponivel_em_testeChave de teste chamando saldo ou saque.
403chave_de_teste_na_producaoChave de teste (gp_test_) no endereço de produção. Ela só vale em /sandbox.
429muitas_chaves_invalidasMuitos pedidos com chave errada da mesma rede em 1 minuto. Espere 1 minuto.