Pix: cobranças

Gere QR Code e copia e cola e acompanhe o pagamento.

Criar

Crie uma cobrança com amount em centavos. Use reference para guardar o id do pedido e Idempotency-Key para repetir sem duplicar. Parâmetros completos na referência.

curl -X POST "https://api.pombopix.com/v1/charges" \
  -H "Authorization: Bearer $GATEWAY_API_KEY" \
  -H "Idempotency-Key: pedido-0001" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 15000,
    "reference": "PEDIDO-0001",
    "description": "Plano anual",
    "customer": {
      "name": "Ana Souza",
      "document": "12345678901",
      "email": "ana@example.com"
    }
  }'

Mostrar o Pix ao pagador

pix.copyPaste: código para colar no aplicativo do banco.
pix.qrCodeBase64: imagem PNG em base64, sem prefixo. Para exibir, use data:image/png;base64, antes do valor.
checkoutUrl: página pronta, sem precisar montar tela. Veja Checkout hospedado.

fee fica em zero e net igual ao valor até o pagamento. Os dois são definidos quando a cobrança é paga.

Resposta 201

{
  "id": "7c1e4f2a-3b58-4e0d-9a6c-2f8d1b7e5a10",
  "object": "charge",
  "livemode": false,
  "status": "pending",
  "amount": 15000,
  "fee": 0,
  "net": 15000,
  "currency": "BRL",
  "reference": "PEDIDO-0001",
  "description": "Plano anual",
  "customer": {
    "name": "Ana Souza",
    "document": "12345678901",
    "email": "ana@example.com"
  },
  "metadata": {
    "pedido": "0001"
  },
  "pix": {
    "copyPaste": "00020126580014br.gov.bcb.pix0136...",
    "qrCodeBase64": "iVBORw0KGgoAAAANSUhEUg..."
  },
  "checkoutUrl": "https://painel.example.com/pay/7c1e4f2a-3b58-4e0d-9a6c-2f8d1b7e5a10",
  "payer": null,
  "failureReason": null,
  "paidAt": null,
  "refundedAt": null,
  "createdAt": "2026-11-01T15:04:05.000Z"
}

Ciclo de vida

status	Significado
`pending`	Aguardando pagamento.
`paid`	Pagamento confirmado. Saldo creditado e `charge.paid` enviado.
`refunded`	Pix devolvido ao pagador. Saldo debitado e `charge.refunded` enviado.
`failed`	Não foi possível gerar o Pix. Veja `failureReason` e crie outra cobrança.

Cobranças não expiram por tempo pela API. Se a venda foi cancelada, trate isso no seu sistema: um pagamento que chegar depois ainda será creditado.

Estornos

No sandbox, simule com POST /v1/sandbox/charges/{id}/refund.

Consultar

Use GET /v1/charges/{id} e GET /v1/charges. Para ser avisado sem consultar, use webhooks.