Ambientes e URL base
Descubra o endereço da API, o que muda entre Produção e Homologação e por que a chamada deve partir do seu servidor.
URL base
A URL base da API da PagPolar é:
https://api.pagpolar.com/v1Nesta documentação, as rotas aparecem sem a URL base, como GET /me ou POST /payments/pix. Para chamar uma rota, junte a URL base com o caminho da rota: https://api.pagpolar.com/v1 + /me = https://api.pagpolar.com/v1/me. Não repita o /v1 no caminho nem deixe barra dupla.
Os exemplos em cURL e Node.js já usam a URL completa.
Existe um único endereço. Produção e Homologação usam o mesmo.
Produção e Homologação
Toda credencial pertence a um ambiente. Você escolhe o ambiente ao criar a credencial e não consegue mudar depois.
| Ambiente no painel | Valor em environment | A chave começa com | Onde a chamada é processada |
|---|---|---|---|
| Produção | PRODUCTION | pgp_live_ | Na sua conta. As cobranças são reais. |
| Homologação | STAGING | pgp_test_ | No ambiente de testes. Nenhuma cobrança é real. |
As duas chaves usam a mesma URL base. A PagPolar reconhece a chave de Homologação, ou o token obtido com ela, e leva a chamada para o ambiente de testes. Para saber o ambiente de uma chave, chame GET /me e leia environment.
Ambiente de testes
Ao criar a chave de Homologação, a PagPolar prepara uma conta de testes separada da sua conta real, com dados fictícios e cadastro já aprovado. A chave só funciona depois que a conta de testes fica pronta. Veja as etiquetas e as regras da chave em A chave de Homologação.
- Produtos, ofertas, vendas e clientes criados com a chave de Homologação ficam só no ambiente de testes. Eles não aparecem na sua conta real.
- PIX, boleto e cartão criados com a chave de Homologação não cobram ninguém.
- Se o ambiente de testes estiver fora do ar, veja Ambiente de testes indisponível.
Comprar no ambiente de testes
No ambiente de testes, o pagamento passa por um gateway de testes. Ele aceita dados fictícios e aprova o pagamento sozinho:
| Dado | O que usar |
|---|---|
| CPF do cliente e do titular | Qualquer CPF válido (com dígitos verificadores corretos). Não precisa ser de uma pessoa real. Geradores de CPF de teste servem. |
| Cartão de crédito | Número 4000 0000 0000 0010, CVV 123, qualquer nome de titular e qualquer validade futura. |
| PIX | Crie a cobrança normalmente. O QR Code é gerado, mas não precisa ser pago. |
PIX e cartão são aprovados cerca de 30 segundos depois da criação da cobrança. Nesse momento a venda passa a PAID, paid_at é preenchido e o evento TRANSACTION_PAID chega na URL do webhook da chave de Homologação. Use esse intervalo para testar o fluxo de espera do webhook e a consulta da venda.
Outros números de cartão
Qualquer outro número de cartão pode ser recusado ou ficar sem resposta no gateway de testes. Para simular o caminho feliz, use o cartão acima.
Onde o ambiente faz diferença
Com a chave de Homologação, todas as rotas rodam no ambiente de testes. Estas cobram, mudam, cancelam ou devolvem dinheiro de verdade quando a chamada usa a chave de Produção:
POST /payments/pixPOST /payments/boletoPOST /payments/credit-cardPOST /plans/offer/{id}/subscribePOST /subscriptions/{id}/plan-changePATCH /subscriptions/{id}/cardDELETE /subscriptions/{id}(cancela a assinatura; não pode ser desfeito)POST /refunds
Testar pelo portal
As páginas da Referência da API têm o botão Send, que executa a operação no ambiente de testes sem você digitar chave nem token:
- Entre no painel da PagPolar neste navegador.
- Tenha uma chave de Homologação pronta. IPs autorizados da chave não valem para o playground: ele passa por essa restrição.
- Abra uma operação na referência, preencha os campos e clique em Send.
O portal gera sozinho um token de 15 minutos para a sua chave de Homologação e envia a requisição por ele. Por isso o playground não tem campo Authorization: a autenticação é feita pelo portal. O playground só alcança o ambiente de testes: não há como criar uma cobrança real por ele.
| Resposta do playground | O que fazer |
|---|---|
401 com playground_login_required | Entre no painel neste navegador e tente de novo. |
404 com a mensagem "Nenhuma chave de Homologação ativa" | Crie uma chave de Homologação em Configurações → API. |
409 avisando que o ambiente ainda não está pronto | Espere a chave aparecer como pronta. |
POST /auth/token não roda pelo playground, porque ele recebe a chave de API. Teste essa rota pelo seu servidor.
Chame a API do seu servidor
Faça as chamadas a partir do seu servidor (back-end), nunca a partir do navegador do cliente:
- A chave é secreta. Quem tiver a chave consegue criar cobranças e ler os dados dos seus clientes.
- O navegador bloqueia a chamada. A API só libera chamadas de navegador de uma lista fixa de origens da PagPolar. Uma chamada feita pelo JavaScript do seu site é bloqueada pelo navegador.
O fluxo certo é: o seu site chama o seu servidor, e o seu servidor chama a API com o token de acesso. A chave e o token ficam no servidor, nunca no navegador.