Início rápido
Crie uma credencial, obtenha o token de acesso e faça a sua primeira venda PIX pela API.
Ao final deste guia você terá:
- uma credencial com chave de API e webhook;
- um token de acesso para autenticar as chamadas;
- um produto e uma oferta criados pela API;
- uma venda PIX com o código "copia e cola" para o cliente pagar.
Este guia usa a chave de Homologação
Com a chave de Homologação, todas as chamadas vão para o ambiente de testes. O produto, a oferta e a venda ficam só lá, e o PIX do passo 7 é aprovado sozinho cerca de 30 segundos depois de criado. Veja Comprar no ambiente de testes.
Visão geral
O diagrama mostra os passos deste guia, na ordem.
Antes de começar
- Uma conta de vendedor na PagPolar com o menu Configurações → API.
- Um terminal com
curl, ou Node.js 18 ou mais novo. Os exemplos em Node.js usamawaitdireto no arquivo: salve o código em um arquivo.mjse rode comnode arquivo.mjs. - Uma URL pública no seu servidor para receber os webhooks.
Crie a credencial no painel
- No painel da PagPolar, abra Configurações → API.
- Clique em Nova chave. Abre o painel lateral Criar nova chave de integração.
- Preencha os campos:
| Campo | O que colocar |
|---|---|
| Nome da integração | Um nome para você reconhecer a credencial, como Loja virtual. |
| Ambiente | Homologação. Não dá para mudar depois. Cada conta pode ter uma chave de Homologação ativa. |
| URL do webhook | A URL do seu servidor que vai receber os avisos. |
| Eventos | Deixe em branco para receber todos os eventos. |
| IPs autorizados | Deixe em branco neste teste. Assim, qualquer IP é aceito. |

A imagem mostra o ambiente Produção, o valor inicial do campo. Troque para Homologação.
- Clique em Salvar.
A PagPolar começa a preparar a sua conta de testes. Na lista de Configurações → API, a chave aparece com a etiqueta Preparando ambiente de testes. Atualize a tela até a etiqueta mudar para Ambiente de testes pronto antes de seguir para o passo 3. Veja A chave de Homologação.
Guarde a chave e o token do webhook
Depois de salvar, abre a janela Chave criada com sucesso. Ela mostra dois valores:
| Valor | Para que serve |
|---|---|
| Chave de API | Vai no header X-API-Key de POST /auth/token, a rota que devolve o token de acesso. É o único lugar em que a chave é aceita. |
| Token do webhook | Chega no header Authorization de cada webhook, para você confirmar que o aviso é da PagPolar. |

Copie os dois e guarde no seu servidor, em variáveis de ambiente ou em um cofre de segredos.
Os dois valores aparecem uma única vez
Depois de fechar a janela, não há como ver a chave nem o token de novo. Se perder algum dos dois, revogue a credencial e crie outra.
Troque a chave pelo token de acesso
POST /auth/token é a única rota que recebe a chave. Ela devolve o token que autentica todas as outras chamadas. A requisição não tem corpo.
curl -X POST "https://api.pagpolar.com/v1/auth/token" \
-H "X-API-Key: <SUA_CHAVE_DE_API>"const apiUrl = 'https://api.pagpolar.com/v1';
async function obterToken() {
const response = await fetch(`${apiUrl}/auth/token`, {
method: 'POST',
headers: { 'X-API-Key': '<SUA_CHAVE_DE_API>' },
});
const { data } = await response.json();
return data.access_token;
}
const accessToken = await obterToken();
console.log(accessToken);Resposta 200:
{
"data": {
"access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"token_type": "Bearer",
"expires_in": 86400
}
}Guarde data.access_token em memória. Ele é o valor que vai no header Authorization dos próximos passos. Os exemplos em Node.js daqui em diante usam a variável accessToken criada acima. Quando ele expirar, peça outro: veja Validade e Renove o token quando receber 401.
Confirme o token com GET /me
Chame GET /me com o token no header Authorization:
curl "https://api.pagpolar.com/v1/me" \
-H "Authorization: Bearer <SEU_TOKEN_DE_ACESSO>"const response = await fetch('https://api.pagpolar.com/v1/me', {
headers: { Authorization: `Bearer ${accessToken}` },
});
console.log(response.status, await response.json());Se o token estiver certo, a resposta é 200:
{
"data": {
"credential_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
"environment": "STAGING",
"rate_limit_per_minute": 120
}
}environment: STAGING confirma que a chamada foi atendida pelo ambiente de testes.
Se a resposta for 401, veja Autenticação.
Crie um produto
curl -X POST "https://api.pagpolar.com/v1/products" \
-H "Authorization: Bearer <SEU_TOKEN_DE_ACESSO>" \
-H "Content-Type: application/json" \
-d '{
"name": "Curso de exemplo",
"description": "Produto criado no início rápido"
}'const response = await fetch('https://api.pagpolar.com/v1/products', {
method: 'POST',
headers: {
Authorization: `Bearer ${accessToken}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
name: 'Curso de exemplo',
description: 'Produto criado no início rápido',
}),
});
console.log(response.status, await response.json());Resposta 201 (resumida):
{
"data": {
"id": "c4d5e6f7-a8b9-4c0d-1e2f-3a4b5c6d7e8f",
"name": "Curso de exemplo",
"type": "DIGITAL",
"is_active": true
}
}Guarde data.id. Ele é o <ID_DO_PRODUTO> do próximo passo. Contrato completo: POST /products.
Crie uma oferta
A oferta define o preço e os meios de pagamento. price vai em centavos, como número inteiro (1000 = R$ 10,00), e volta em reais na resposta (10). Veja Valores nas respostas.
curl -X POST "https://api.pagpolar.com/v1/offers" \
-H "Authorization: Bearer <SEU_TOKEN_DE_ACESSO>" \
-H "Content-Type: application/json" \
-d '{
"product_id": "<ID_DO_PRODUTO>",
"title": "Oferta de lançamento",
"price": 1000,
"is_enabled_pix": true,
"is_enabled_credit_card": false,
"is_enabled_billet": false,
"max_credit_card_installments": 1
}'const response = await fetch('https://api.pagpolar.com/v1/offers', {
method: 'POST',
headers: {
Authorization: `Bearer ${accessToken}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
product_id: '<ID_DO_PRODUTO>',
title: 'Oferta de lançamento',
price: 1000,
is_enabled_pix: true,
is_enabled_credit_card: false,
is_enabled_billet: false,
max_credit_card_installments: 1,
}),
});
console.log(response.status, await response.json());Resposta 201 (resumida):
{
"data": {
"id": "d5e6f7a8-b9c0-4d1e-2f3a-4b5c6d7e8f9a",
"identifier": "PPP1234567890",
"title": "Oferta de lançamento",
"price": 10,
"payment_methods": {
"pix": true,
"credit_card": false,
"billet": false
},
"max_credit_card_installments": 1
}
}Guarde data.identifier. Ele é o <CODIGO_DA_OFERTA> do próximo passo. Contrato completo: POST /offers.
Por que enviar max_credit_card_installments
Sem esse campo, a oferta vale 12 parcelas, e R$ 10,00 em 12 parcelas fica abaixo da parcela mínima: a criação responde 400. Com 1, a oferta passa.
Crie a venda PIX
Envie o código da oferta e os dados do cliente. No ambiente de testes, customer.document pode ser qualquer CPF válido. Três headers são obrigatórios:
| Header | Valor |
|---|---|
Authorization | Bearer seguido do token de acesso do passo 3. |
Idempotency-Key | Um valor único para esta cobrança, como um UUID. Veja Idempotência. |
Content-Type | application/json |
curl -X POST "https://api.pagpolar.com/v1/payments/pix" \
-H "Authorization: Bearer <SEU_TOKEN_DE_ACESSO>" \
-H "Idempotency-Key: 6b1f2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d" \
-H "Content-Type: application/json" \
-d '{
"offer_identifier": "<CODIGO_DA_OFERTA>",
"external_reference": "PEDIDO-0001",
"customer": {
"name": "Maria Silva",
"email": "cliente@exemplo.com",
"document": "<CPF_DO_CLIENTE>",
"phone": "<TELEFONE_DO_CLIENTE>"
}
}'import { randomUUID } from 'node:crypto';
const response = await fetch('https://api.pagpolar.com/v1/payments/pix', {
method: 'POST',
headers: {
Authorization: `Bearer ${accessToken}`,
'Idempotency-Key': randomUUID(),
'Content-Type': 'application/json',
},
body: JSON.stringify({
offer_identifier: '<CODIGO_DA_OFERTA>',
external_reference: 'PEDIDO-0001',
customer: {
name: 'Maria Silva',
email: 'cliente@exemplo.com',
document: '<CPF_DO_CLIENTE>',
phone: '<TELEFONE_DO_CLIENTE>',
},
}),
});
console.log(response.status, await response.json());| Campo | Obrigatório | O que é |
|---|---|---|
offer_identifier | Sim, ou offer | Código da oferta. |
external_reference | Não | Código do seu pedido, até 255 caracteres. Serve para achar a venda depois. Veja Como a venda é encontrada. |
Dados do cliente:
| Campo | Obrigatório | O que é |
|---|---|---|
customer.name | Sim | Nome do cliente, até 255 caracteres. |
customer.email | Sim | E-mail válido do cliente. |
customer.document | Sim | CPF ou CNPJ do cliente, com ou sem pontuação. Veja o formato em Documento e telefone. |
customer.phone | Sim | Telefone do cliente com DDD, com ou sem pontuação. Veja o formato em Documento e telefone. |
Resposta 201:
{
"data": {
"offer_identifier": "PPP1234567890",
"transactions": ["a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d"],
"subscriptions": [],
"pix": {
"qr_code": "00020126580014br.gov.bcb.pix0136a1b2c3d4-e5f6-4a7b-8c9d"
}
}
}| Campo | O que fazer com ele |
|---|---|
transactions[0] | É o id da venda. Guarde junto do seu pedido. |
pix.qr_code | Mostre ao cliente como "copia e cola" ou gere a imagem do QR Code com ele. |
Contrato completo: POST /payments/pix.
Confira o resultado
1. Consulte a venda. Use o id que veio em transactions[0]:
curl "https://api.pagpolar.com/v1/sales/a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d" \
-H "Authorization: Bearer <SEU_TOKEN_DE_ACESSO>"const response = await fetch(
'https://api.pagpolar.com/v1/sales/a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d',
{ headers: { Authorization: `Bearer ${accessToken}` } },
);
console.log(response.status, await response.json());Resposta 200 (resumida):
{
"data": {
"id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
"identifier": "PPO9876543210",
"external_reference": "PEDIDO-0001",
"status": "PROCESSING",
"payment_method": "PIX",
"total_amount": 10,
"paid_at": null
}
}Você também pode consultar pelo código da venda (identifier) ou pela sua referência: GET /sales/PEDIDO-0001. Veja Como a venda é encontrada.
2. Veja o webhook. A sua URL recebe o evento TRANSACTION_CREATED.
3. Entenda o pagamento. Quando um PIX é pago, chega TRANSACTION_PAID. A venda passa a status: PAID e paid_at é preenchido. No ambiente de testes, isso acontece sozinho, como no aviso do início deste guia.
Se algo deu errado
Além dos erros comuns a todas as rotas, este guia pode responder:
| Passo | Situação | Resposta | Como resolver |
|---|---|---|---|
| 1 | A conta já tem 5 credenciais ativas, somando Produção e Homologação. | Limite de 5 credenciais ativas atingido. Revogue uma credencial antes de criar outra. | Revogue uma credencial sem uso. |
| 1 | A conta já tem uma chave de Homologação ativa. | A opção Homologação fica desabilitada no campo Ambiente. | Use a chave de Homologação que você já tem, ou revogue-a e crie outra. |
| 1 | A etiqueta da chave mudou para Falha ao preparar ambiente de testes. | O motivo aparece ao passar o mouse sobre a etiqueta. | Revogue a chave e crie outra. |
| 3 | A chave ainda não está pronta no ambiente de testes. | 401 unauthorized | Espere a etiqueta Ambiente de testes pronto e repita. |
| 6 | product_id errado ou de outra conta. | 404 com Produto não encontrado | Use o data.id do passo 5. |
| 6 | Parcela abaixo do mínimo. | 400 com O valor da parcela (...) fica abaixo do mínimo permitido (...) | Envie max_credit_card_installments: 1. |
| 7 | Código da oferta errado. | 404 com Oferta não encontrada | Use o data.identifier do passo 6. |
| 7 | PIX desligado na oferta. | 409 com Método de pagamento PIX não habilitado para esta oferta | Crie a oferta com is_enabled_pix: true e price a partir do valor mínimo do PIX. |
| 3 a 8 | O ambiente de testes está fora do ar ou não respondeu em 30 segundos. | 502 sandbox_unavailable | Espere alguns segundos e repita. Veja Erros. |