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 usam await direto no arquivo: salve o código em um arquivo .mjs e rode com node arquivo.mjs.
  • Uma URL pública no seu servidor para receber os webhooks.

Crie a credencial no painel

  1. No painel da PagPolar, abra Configurações → API.
  2. Clique em Nova chave. Abre o painel lateral Criar nova chave de integração.
  3. Preencha os campos:
CampoO que colocar
Nome da integraçãoUm nome para você reconhecer a credencial, como Loja virtual.
AmbienteHomologação. Não dá para mudar depois. Cada conta pode ter uma chave de Homologação ativa.
URL do webhookA URL do seu servidor que vai receber os avisos.
EventosDeixe em branco para receber todos os eventos.
IPs autorizadosDeixe em branco neste teste. Assim, qualquer IP é aceito.

Painel lateral Criar nova chave de integração com o nome da integração, o ambiente Produção, a URL do webhook, os eventos e os IPs autorizados

A imagem mostra o ambiente Produção, o valor inicial do campo. Troque para Homologação.

  1. 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:

ValorPara que serve
Chave de APIVai 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 webhookChega no header Authorization de cada webhook, para você confirmar que o aviso é da PagPolar.

Janela Chave criada com sucesso com o aviso para copiar e guardar agora, o campo Chave de API e o campo Token do webhook, cada um com botão de copiar

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:

HeaderValor
AuthorizationBearer seguido do token de acesso do passo 3.
Idempotency-KeyUm valor único para esta cobrança, como um UUID. Veja Idempotência.
Content-Typeapplication/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());
CampoObrigatórioO que é
offer_identifierSim, ou offerCódigo da oferta.
external_referenceNãoCódigo do seu pedido, até 255 caracteres. Serve para achar a venda depois. Veja Como a venda é encontrada.

Dados do cliente:

CampoObrigatórioO que é
customer.nameSimNome do cliente, até 255 caracteres.
customer.emailSimE-mail válido do cliente.
customer.documentSimCPF ou CNPJ do cliente, com ou sem pontuação. Veja o formato em Documento e telefone.
customer.phoneSimTelefone 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"
    }
  }
}
CampoO que fazer com ele
transactions[0]É o id da venda. Guarde junto do seu pedido.
pix.qr_codeMostre 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:

PassoSituaçãoRespostaComo resolver
1A 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.
1A 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.
1A 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.
3A chave ainda não está pronta no ambiente de testes.401 unauthorizedEspere a etiqueta Ambiente de testes pronto e repita.
6product_id errado ou de outra conta.404 com Produto não encontradoUse o data.id do passo 5.
6Parcela abaixo do mínimo.400 com O valor da parcela (...) fica abaixo do mínimo permitido (...)Envie max_credit_card_installments: 1.
7Código da oferta errado.404 com Oferta não encontradaUse o data.identifier do passo 6.
7PIX desligado na oferta.409 com Método de pagamento PIX não habilitado para esta ofertaCrie a oferta com is_enabled_pix: true e price a partir do valor mínimo do PIX.
3 a 8O ambiente de testes está fora do ar ou não respondeu em 30 segundos.502 sandbox_unavailableEspere alguns segundos e repita. Veja Erros.

Próximos passos