Referência da API

A chave

Base: https://api.pagora.com.br. Toda rota /v1 pede a chave no header Authorization. Ela é criada no painel e aparece em claro uma vez.

curl https://api.pagora.com.br/v1/charges \
  -H 'Authorization: Bearer sk_live_...'

Enquanto a loja não for aprovada, toda rota /v1 responde 403 com um campo status: pending_kyc, in_review, rejected ou blocked.

Convenções

Campo terminado em Cents é inteiro em centavos. R$ 100,00 é 10000. Fração e string são recusadas com 400.

Campo terminado em At é ISO 8601 em UTC, com milissegundos e sufixo Z: "2026-07-16T13:00:00.000Z".

Id de cobrança tem prefixo ch_ e não é sequencial.

Criar cobrança

O corpo inteiro, com tudo que existe:

curl -X POST https://api.pagora.com.br/v1/charges \
  -H 'Authorization: Bearer sk_live_...' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: pedido-4711' \
  -d '{
    "amountCents": 10000,
    "description": "Pedido 4711",
    "postbackUrl": "https://seu-sistema.com/pagora/aviso",
    "pagador": {
      "nome": "Ana Souza",
      "documento": "00000000000",
      "email": "ana@exemplo.com",
      "celular": "11999998888"
    },
    "beneficiario": {
      "nome": "Loja do Cliente ME",
      "documento": "00000000000000"
    }
  }'

Idempotency-Key é header, opcional. Mesma chave e mesmo valor devolve a cobrança da primeira chamada. Mesma chave e valor diferente devolve 422.

A resposta, inteira · 201

{
  "id": "ch_kkD4vGQxN3m1sJb2aZ7cUg",
  "status": "pending",
  "brCode": "00020126...6304ABCD",
  "amountCents": 10000,
  "feeBps": 150,
  "feeFixedCents": 0,
  "feeCents": 150,
  "netCents": 9850,
  "description": "Pedido 4711",
  "postbackUrl": "https://seu-sistema.com/pagora/aviso",
  "pagador": null,
  "endToEndId": null,
  "qrImageUrl": "https://.../qr.png",
  "metodo": "pix",
  "linhaDigitavel": null,
  "boletoUrl": null,
  "createdAt": "2026-07-16T13:00:00.000Z",
  "expiresAt": "2026-07-16T14:00:00.000Z",
  "paidAt": null
}

Consultar

Mesmo formato da resposta acima. Depois de paga: status: "paid" e paidAt preenchido.

Listar

{ "data": [ { ...igual à resposta acima... } ], "hasMore": true }

Enquanto hasMore for true, repita mandando starting_after = o id do último item.

Webhook

POST na sua URL quando a venda é paga. Responda qualquer 2xx em até 10 segundos. Sem 2xx, são 6 tentativas no total, esperando 10s, 20s, 40s, 80s, 160s entre elas: cerca de 5 minutos do começo ao fim.

Dá pra cadastrar mais de um endereço no painel, o seu sistema e o do seu parceiro por exemplo. Cada venda paga vira um aviso pra cada um, e cada endereço tem o seu próprio segredo: trocar o de um não mexe nos outros.

A postbackUrl da cobrança soma com esses endereços: o aviso vai pra ela e pra todos eles. Se a postbackUrl for igual a um endereço cadastrado, esse endereço não recebe duas vezes.

{
  "type": "charge.paid",
  "createdAt": "2026-07-16T18:20:31.554Z",
  "data": {
    "chargeId": "ch_HuKkN92_2Bx_ZdDH8vxE-w",
    "status": "paid",
    "amountCents": 10000,
    "feeCents": 150,
    "netCents": 9850,
    "endToEndId": "E31872495202607161820Yk7mQ2xLp4t",
    "paidAt": "2026-07-16T18:20:31.554Z"
  }
}

A URL precisa ser https://. Uma entrega pode chegar duas vezes, então guarde o chargeId já processado e ignore repetição.

const { createHmac, timingSafeEqual } = require('node:crypto')

// corpoCru = os BYTES exatos recebidos, ANTES de qualquer JSON.parse
function avisoValido(segredo, headers, corpoCru) {
  const ts = headers['x-pagora-timestamp']
  const esperada = 'sha256=' + createHmac('sha256', segredo)
    .update(`${ts}.${corpoCru}`).digest('hex')
  const a = Buffer.from(esperada)
  const b = Buffer.from(headers['x-pagora-signature'] ?? '')
  if (a.length !== b.length || !timingSafeEqual(a, b)) return false
  // recusa aviso com mais de 5 min de diferença
  if (Math.abs(Math.floor(Date.now() / 1000) - Number(ts)) > 300) return false
  return true
}

Erros

{ "error": "amountCents inválido: precisa ser um inteiro de centavos maior que zero" }

Quando a recusa é de regra, vem junto um motivo. Faça o if no motivo, nunca na mensagem.

No 5xx vem um reqId. Mande ele no chamado.