API de pagamentos PIX

Introdução

A API é REST, aceita e devolve JSON e vive sob a URL base:

Toda resposta segue o mesmo envelope. Em sucesso, os dados vêm em data; em erro, a mensagem vem em error.

{
  "success": true,
  "data": { ... }
}

{
  "success": false,
  "error": "Mensagem legível"
}

Autenticação

Autentique cada requisição com sua chave de API no header X-Api-Key. Gere/rotacione a chave no painel do seller, em Configurações → API. A chave identifica sua conta e a adquirente ativa; trate-a como segredo.

X-Api-Key: sua_chave_de_api

Para máxima segurança, você pode assinar cada requisição (anti-replay). É opcional e retrocompatível — veja Assinatura anti-replay.

Respostas & erros

Os códigos HTTP seguem a semântica REST:

Rate limiting

Os endpoints públicos são limitados por IP em janela fixa. Ao exceder, a API responde 429 com um header Retry-After (segundos). Implemente backoff exponencial e respeite o Retry-After.

POST Criar cobrança PIX

Cria uma transação PIX e devolve o código copia-e-cola para o pagador.

Corpo da requisição

Headers

Exemplo

curl -X POST https://app.junglepagamentos.com/api/gateway/charges \
  -H "X-Api-Key: sua_chave_de_api" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 7f3c9a2e-5b1d-4c8a-9e0f-2d6b4a1c8e53" \
  -d '{
    "product": { "name": "Plano Pro", "value": 49.90 },
    "customer": {
      "name": "Ana Souza",
      "email": "ana@exemplo.com",
      "doc": "12345678909",
      "docType": "cpf",
      "phone": "11987654321"
    },
    "expiracaoSegundos": 3600,
    "callbackUrl": "https://sualoja.com/webhooks/pix"
  }'

const res = await fetch("https://app.junglepagamentos.com/api/gateway/charges", {
  method: "POST",
  headers: {
    "X-Api-Key": "sua_chave_de_api",
    "Content-Type": "application/json",
    "Idempotency-Key": crypto.randomUUID(), // opcional; reuse o mesmo valor nos retries
  },
  body: JSON.stringify({
    product: { name: "Plano Pro", value: 49.90 },
    customer: {
      name: "Ana Souza",
      email: "ana@exemplo.com",
      doc: "12345678909",
      docType: "cpf",
      phone: "11987654321",
    },
    expiracaoSegundos: 3600,
  }),
});
const { data } = await res.json();
console.log(data.pixCode);

Resposta 201

{
  "success": true,
  "data": {
    "transactionId": "a1b2c3d4-e5f6-...",   // use para consultar o status
    "pixCode": "00020101...6304ABCD",      // copia-e-cola / gere o QR
    "expiresAt": "2026-07-21T12:34:56.000Z",
    "amount": 49.90,      // valor bruto (reais)
    "feeAmount": 1.75,    // taxa do gateway
    "netAmount": 48.15     // líquido do seller
  }
}

Idempotência opcional

Envie o header Idempotency-Key para repetir a criação com segurança (timeout, queda de conexão) sem gerar cobrança duplicada. Sem o header, nada muda.

• Formato: de 1 a 255 caracteres ASCII visíveis (0x21–0x7E, sem espaço). Um valor fora disso é ignorado — a requisição é tratada como se não tivesse o header, e a resposta (mesmo status e corpo) traz o header Idempotency-Key-Status: ignored. Sem o header na requisição, ele não aparece.
• Mesmo payload: a ordem das chaves dos objetos JSON não importa; a ordem dos itens de arrays importa.
• Escopo: a conta (workspace) da chave de API.
• Validade: permanente — a chave não expira; use um valor novo por cobrança (ex.: UUID).
• Assinatura: o header fica fora do texto canônico da assinatura. Um retry assinado precisa de X-Nonce e X-Timestamp novos.

Idempotency-Key: 7f3c9a2e-5b1d-4c8a-9e0f-2d6b4a1c8e53

GET Consultar transação

Devolve uma única transação pelo id (o transactionId recebido na criação). É a forma recomendada de polling e de reconciliação — não há janela de 30 dias.

curl "https://app.junglepagamentos.com/api/gateway/transactions/a1b2c3d4-e5f6-..." \
  -H "X-Api-Key: sua_chave_de_api"

{
  "success": true,
  "data": {
    "id": "a1b2c3d4-...",
    "status": "PAID",
    // ... mesmos campos de cada item da listagem
    "createdAt": "2026-07-21T11:34:56.000Z",
    "updatedAt": "2026-07-21T12:10:03.000Z"
  }
}

{ "success": false, "error": "Transaction not found" }

GET Listar transações

Lista as transações da sua conta com paginação. A ordem é contrato: createdAt decrescente e, no empate, id decrescente. Use este endpoint para reconciliação e sincronização incremental; para uma cobrança específica, prefira GET /gateway/transactions/:id.

O objeto meta traz { total, page, limit, pages }. Quando você envia status ou updatedSince, meta ganha também filters: { status, updatedSince } com os valores aplicados — null indica que o parâmetro foi ignorado por ser inválido.

curl "https://app.junglepagamentos.com/api/gateway/transactions?page=1&limit=20" \
  -H "X-Api-Key: sua_chave_de_api"

{
  "success": true,
  "data": [
    {
      "id": "a1b2c3d4-...",
      "status": "PAID",
      "acquirerId": "zorapay",
      "productName": "Plano Pro",
      "amount": 49.90, "feeAmount": 1.75, "netAmount": 48.15,
      "pixCode": "00020101...6304ABCD",
      "pixExpiresAt": "2026-07-21T12:34:56.000Z",
      "paidAt": "2026-07-21T12:10:03.000Z",
      "customer": { "name": "Ana Souza", "email": "ana@exemplo.com" },
      "metadata": { ... },
      "createdAt": "2026-07-21T11:34:56.000Z",
      "updatedAt": "2026-07-21T12:10:03.000Z"
    }
  ],
  "meta": { "total": 128, "page": 1, "limit": 20, "pages": 7 }
}

Sincronização incremental

1. Guarde o maior updatedAt que você já viu.
2. Consulte ?updatedSince= com esse valor menos uma pequena sobreposição (ex.: 1–2 minutos), percorrendo todas as páginas.
3. Deduplique pelo id e atualize o seu maior updatedAt.

curl "https://app.junglepagamentos.com/api/gateway/transactions?updatedSince=2026-07-21T12:08:00.000Z&status=paid&limit=100" \
  -H "X-Api-Key: sua_chave_de_api"

// meta: { "total": 3, "page": 1, "limit": 100, "pages": 1,
//         "filters": { "status": "PAID", "updatedSince": "2026-07-21T12:08:00.000Z" } }

POST Checkout hospedado

Em vez de gerar o PIX você mesmo, crie uma sessão de checkout e redirecione o cliente para uma página de pagamento hospedada (com seu template, order bumps, etc.). A sessão referencia um checkoutId criado no painel.

{
  "success": true,
  "data": {
    "sessionId": "8feccd9e-...",
    "amount": 202.40,
    "checkoutUrl": "https://app.junglepagamentos.com/c/8feccd9e-..."
  }
}

Status de pagamento

Toda transação passa por um destes estados:

Webhooks

Informe uma callbackUrl ao criar a cobrança para ser notificado quando o status mudar. Anexamos um token à sua URL — valide-o para garantir que a chamada veio da Jungle Pagamentos.

POST https://sualoja.com/webhooks/pix?token=<token-de-verificacao>
// Responda 2xx para confirmar o recebimento.

Eventos

Política de entrega

• Até 3 tentativas: espera de 0,5 s antes da 2ª e de 2 s antes da 3ª.
• Timeout de 10 s por tentativa; orçamento total de 15 s por entrega.
• Nova tentativa só em erro de rede, timeout ou resposta 5xx.
• 2xx e 4xx são finais — um 4xx não é reenviado.
• 3xx: seguimos 1 redirecionamento, desde que para um host público; caso contrário é final.

Assinatura anti-replay opcional

Para blindar contra replay, assine a requisição. Se você enviar X-Signature, exigimos também X-Timestamp e X-Nonce. Clientes que não assinam continuam funcionando normalmente.

{METHOD}\n{path}\n{body}\n{X-Timestamp}\n{X-Nonce}

# ex.:  POST\n/api/gateway/charges\n{"product":...}\n1737460000000\nabc123

Boas práticas

© Jungle Pagamentos — Documentação da API · PIX na edge da Cloudflare.