Pular para o conteúdo
Documentação oficial

Integre pagamentos PIX com clareza e segurança.

Crie cobranças, exiba o QR Code e acompanhe cada pagamento com uma API simples, previsível e pronta para o seu backend.

criar-cobranca.shlive
$ curl -X POST \
  /api/v1/pix \

→ 200 OK
{
  "status": "pending",
  "transaction_id": "8a401...",
  "pix": { ... }
}
Base URL
https://www.goupay.com.br
01
Gere sua chave

Crie uma API Key no painel de integrações.

02
Crie a cobrança

Envie valor e dados do cliente pelo backend.

03
Confirme o pagamento

Consulte o status ou receba um webhook.

01 · Primeiros passos

Autenticação

Toda requisição precisa identificar sua conta por uma chave de API.

Obtenha sua chave

No painel, acesse Integrações → API Pix e selecione Gerar nova chave.

Use pelo servidor

Armazene a chave em uma variável de ambiente e faça as chamadas somente pelo backend.

Headers aceitos

http
# Recomendado
x-api-key: SUA_CHAVE_AQUI

# Alternativa
Authorization: Bearer SUA_CHAVE_AQUI
Sua API Key é um segredo

Não inclua a chave em JavaScript entregue ao navegador, aplicativos distribuídos, repositórios públicos ou logs. Se houver exposição, desative a chave e gere uma nova.

02 · Referência

Endpoints

A API v1 usa JSON, HTTPS e valores monetários inteiros em centavos.

Limite compartilhado por chave

São permitidas 20 requisições por minuto para cada API Key. Em uma resposta 429, respeite o header Retry-After.

03 · Cobranças

Criar cobrança PIX

Envie o valor em centavos e os dados essenciais do pagador.

POSThttps://www.goupay.com.br/api/v1/pix

Body JSON

CampoTipoObrigatórioDescrição
amountintegerSimValor em centavos. Mínimo de 100 (R$ 1,00).
descriptionstringNãoIdentificação interna da cobrança.
customer.namestringSimNome completo do pagador.
customer.emailstringSimE-mail válido do pagador. Também recebe os dados do PIX pendente.
customer.cpfstringSimCPF com 11 dígitos, somente números.
customer.phonestringNãoTelefone com DDD, somente números.

Exemplo de requisição

Node.js
const response = await fetch('https://www.goupay.com.br/api/v1/pix', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'x-api-key': process.env.GOUPAY_API_KEY
  },
  body: JSON.stringify({
    amount: 2990,
    description: 'Pedido #42',
    customer: {
      name: 'Maria Souza',
      email: 'maria@email.com',
      cpf: '12345678900',
      phone: '11999999999'
    }
  })
});

const data = await response.json();
if (!response.ok) throw new Error(data.error);

console.log(data.transaction_id);
console.log(data.pix.qr_code);

Resposta de sucesso 200

json
{
  "success": true,
  "transaction_id": "8a40135d-e021-456d-a94f-3122c525d5d9",
  "status": "pending",
  "amount": 2990,
  "pix": {
    "qr_code": "00020126580014BR.GOV.BCB.PIX...",
    "qr_code_url": "https://api.pagar.me/.../qrcode",
    "expires_at": "2026-08-01T15:30:00.000Z"
  },
  "notifications": {
    "pending_email_sent": true
  }
}
transaction_idGuarde para consultar a cobrança.
pix.qr_codeCódigo PIX copia e cola.
pix.qr_code_urlImagem pronta do QR Code.
pix.expires_atValidade em ISO 8601.
notifications.pending_email_sentConfirma se o e-mail do PIX foi aceito pelo SMTP.
04 · Cobranças

Consultar status

Use o transaction_id recebido na criação para obter o estado mais recente e reconciliar cobranças pendentes.

GEThttps://www.goupay.com.br/api/v1/pix/{transaction_id}

Exemplo de consulta

Node.js
const response = await fetch(
  `https://www.goupay.com.br/api/v1/pix/${transactionId}`,
  {
    headers: {
      'x-api-key': process.env.GOUPAY_API_KEY
    }
  }
);

const payment = await response.json();
if (!response.ok) throw new Error(payment.error);

if (payment.status === 'paid') {
  await liberarPedidoUmaVez(payment.transaction_id);
}

Resposta

json
{
  "success": true,
  "transaction_id": "8a40135d-e021-456d-a94f-3122c525d5d9",
  "status": "paid",
  "raw_status": "paid",
  "amount": 2990,
  "payment_method": "pix",
  "pagarme_id": "or_...",
  "description": "Venda via API",
  "customer": {
    "name": "Maria Souza",
    "email": "maria@email.com"
  },
  "created_at": "2026-08-01T15:00:00.000Z",
  "pix": {
    "qr_code": "00020126580014BR.GOV.BCB.PIX...",
    "qr_code_url": "https://api.pagar.me/.../qrcode",
    "expires_at": "2026-08-01T15:30:00.000Z"
  }
}
Liberação idempotente

Ao receber paid, registre o transaction_id como processado. Assim, uma nova consulta ou notificação não libera o mesmo pedido duas vezes.

Reconciliação automática

Quando o pedido local ainda está pendente, esta consulta também confere o estado diretamente no provedor de pagamento. Se o provedor estiver temporariamente indisponível, a API preserva o último estado conhecido e uma consulta posterior tenta novamente.

05 · Cobranças

Status da cobrança

Use o status para controlar o ciclo de vida do pedido no seu sistema.

pendingAguardando

Cobrança criada e ainda não confirmada.

paidPago

Pagamento confirmado. Pode liberar o pedido.

failedFalhou

A cobrança falhou durante o processamento.

refundedEstornado

O valor pago foi estornado.

chargebackChargeback

Contestação registrada para o pagamento.

Expiração do QR Code

A validade vem em pix.expires_at. Use esse campo para bloquear novas tentativas no checkout; expired não faz parte dos status retornados atualmente pelo endpoint.

06 · Cobranças

Polling de status

Use consultas controladas como contingência do webhook e para reconciliar pagamentos pendentes.

Intervalo recomendado5 segundos
Tempo máximo sugerido10 minutos
PreferênciaWebhook
Considere o limite global

O limite de 20 requisições/minuto é compartilhado por todas as cobranças da mesma chave. Para várias cobranças simultâneas, prefira webhooks e aplique backoff ao receber 429.

Node.js
async function aguardarPagamento(transactionId, timeoutMs = 600_000) {
  const inicio = Date.now();

  while (Date.now() - inicio < timeoutMs) {
    const response = await fetch(
      `https://www.goupay.com.br/api/v1/pix/${transactionId}`,
      { headers: { 'x-api-key': process.env.GOUPAY_API_KEY } }
    );

    if (response.status === 429) {
      const espera = Number(response.headers.get('Retry-After') || 60);
      await new Promise(resolve => setTimeout(resolve, espera * 1000));
      continue;
    }

    const payment = await response.json();
    if (payment.status === 'paid') return payment;
    if (['failed', 'refunded', 'chargeback'].includes(payment.status)) {
      throw new Error(`Cobrança finalizada como ${payment.status}`);
    }

    await new Promise(resolve => setTimeout(resolve, 5000));
  }

  throw new Error('Tempo limite de consulta atingido');
}
07 · Checkout

Exibir o QR Code

Ofereça a imagem e o código copia e cola para o cliente escolher como pagar.

pix.qr_codeTexto PIX copia e cola
pix.qr_code_urlURL da imagem PNG
pix.expires_atExpiração em ISO 8601
HTML
<img
  src="{qr_code_url}"
  alt="QR Code para pagamento via PIX"
  width="240"
  height="240"
/>

<label for="pix-code">PIX copia e cola</label>
<input id="pix-code" value="{qr_code}" readonly />

<button
  type="button"
  onclick="navigator.clipboard.writeText(
    document.getElementById('pix-code').value
  )"
>
  Copiar código
</button>
08 · Eventos

Webhooks

Receba uma notificação HTTP quando o status de uma cobrança mudar.

Configure seu endpoint

No painel, acesse Integrações → API Pix → Webhook da API Pix e cadastre uma URL HTTPS pública.

Confirme a notificação pela API

O payload de webhook ainda não inclui assinatura criptográfica. Antes de liberar um produto, consulte GET /api/v1/pix/{transaction_id} pelo backend e confirme status === "paid".

Entrega pelo menos uma vez

Cada URL configurada é processada de forma independente. Respostas fora da faixa 2xx, falhas de conexão ou demora superior a 10 segundos mantêm a entrega pendente. A GouPay realiza até 12 tentativas com intervalos progressivos. Por isso, o mesmo evento pode chegar mais de uma vez e seu endpoint deve ser idempotente.

Eventos enviados

EventoQuando ocorreAção sugerida
order.paidPagamento confirmadoConsultar e liberar uma vez
order.failedPagamento falhouInformar o cliente
order.refundedPagamento estornadoAtualizar o pedido
order.chargebackChargeback registradoBloquear entrega pendente

Payload

json
{
  "event": "order.paid",
  "data": {
    "id": "8a40135d-e021-456d-a94f-3122c525d5d9",
    "transaction_id": "8a40135d-e021-456d-a94f-3122c525d5d9",
    "status": "paid",
    "amount": 2990,
    "amount_display": "29.90",
    "description": null,
    "payment_method": "pix",
    "customer": {
      "name": "Maria Souza",
      "email": "maria@email.com",
      "cpf": "12345678900",
      "phone": "11999999999"
    },
    "created_at": "2026-08-01T15:00:00.000Z",
    "updated_at": "2026-08-01T15:04:33.000Z"
  }
}

Receber no seu servidor

Node.js (Express)
import express from 'express';

const app = express();
app.use(express.json());

app.post('/webhooks/goupay', async (req, res) => {
  const { event, data } = req.body;

  try {
    if (event === 'order.paid') {
      // Confirme o status na API antes de liberar o pedido.
      const response = await fetch(
        `https://www.goupay.com.br/api/v1/pix/${data.transaction_id}`,
        {
          headers: {
            'x-api-key': process.env.GOUPAY_API_KEY
          }
        }
      );

      const payment = await response.json();
      if (payment.status === 'paid') {
        await liberarPedidoUmaVez(payment.transaction_id);
      }
    }

    return res.sendStatus(200);
  } catch (error) {
    console.error('Falha ao processar webhook', error);
    return res.sendStatus(500);
  }
});
Responda rapidamentePersista o evento e retorne qualquer HTTP 2xx em até 10 segundos.
Seja idempotenteUse transaction_id como chave única no seu banco.
Valide pela APIConfirme o status com sua API Key antes da entrega.
09 · Referência

Códigos de erro

Trate o código HTTP antes de consumir o corpo da resposta.

HTTPSituaçãoMotivo comumO que fazer
400Requisição inválidaValor inválido, cliente incompleto ou conta recebedora ausenteRevise o body e a configuração
401Não autenticadoChave ausente ou inválidaEnvie uma API Key ativa
403Acesso bloqueadoChave inativa ou conta bloqueadaVerifique o painel
404Não encontradoTransação ou usuário não encontradoConfira o transaction_id
429Limite excedido20 requisições/minuto excedidasRespeite Retry-After
500Erro internoFalha interna ou do processadorRegistre o erro e tente mais tarde

Formato padrão

A maioria dos erros segue esta estrutura.

json
{
  "error": "Chave de API inválida",
  "status": "error"
}
Resposta 429

Além do JSON de erro, a resposta inclui Retry-After (segundos) e X-RateLimit-Reset (data ISO).

10 · Produção

Checklist de integração

Um caminho seguro do primeiro teste até a liberação do pedido.

01
Gere e proteja a API Key

Salve a chave em uma variável de ambiente do backend.

02
Crie uma cobrança

Faça o POST, trate erros e guarde o transaction_id.

03
Exiba as opções PIX

Mostre o QR Code, o copia e cola e a validade.

04
Acompanhe o pagamento

Use webhook como principal e polling como contingência.

05
Confirme e libere uma vez

Valide paid pela API e processe de forma idempotente.

Pronto para integrar?

Gere sua chave e faça a primeira cobrança.

Abrir integrações