# Pangeia PAY API - Examples

Este arquivo traz exemplos práticos de uso dos endpoints documentados em `apidoc/openapi.yaml`.

## Base URL

- Produção: `https://pay.pangeialabs.com`
- Local: `http://localhost:5000`

## 1) Registrar cobrança (conta com PIX ativo)

> O request de `/registrar` não envia `payment_method`; a API define as opções pelo que está ativo na conta (`pix_enabled`, `bitcoin_enabled`, `outracoin_enabled`).

> **`buyer_taxid` aceita CPF ou CNPJ.** O backend só valida que é uma string não vazia — sem checagem de tamanho/formato. O valor nem entra no payload PIX (o BR Code só leva dados do recebedor), serve só de registro na transação.

```bash
curl -X POST "https://pay.pangeialabs.com/registrar" \
  -H "Content-Type: application/json" \
  -d '{
    "buyer_name": "Joao da Silva",
    "buyer_taxid": "12345678901",
    "order_amount": 149.90,
    "order_id": "PED-10001",
    "api_key": "SUA_API_KEY",
    "redirect_url": "https://seusite.com/retorno"
  }'
```

Resposta esperada (201) para conta com somente PIX ativo:

```json
{
  "order_id": "PED-10001",
  "order_status": "pending",
  "payment_method": "pix",
  "allowed_payment_methods": ["pix"],
  "order_group_id": "",
  "unique_amount": 149.90,
  "unique_id": "65f5b0b6c2ab1d8b8f6a1234",
  "url": "https://pay.pangeialabs.com/pagar/65f5b0b6c2ab1d8b8f6a1234",
  "checkout_options": [
    {
      "payment_method": "pix",
      "unique_id": "65f5b0b6c2ab1d8b8f6a1234",
      "url": "https://pay.pangeialabs.com/pagar/65f5b0b6c2ab1d8b8f6a1234",
      "quote_available": true,
      "quote_unavailable_reason": ""
    }
  ],
  "pixcode": "00020126...6304ABCD",
  "qrcode": "iVBORw0KGgoAAAANS..."
}
```

> **A resposta já traz tudo para um checkout próprio.** `pixcode` é o BR Code "copia e cola" pronto para exibir, e `qrcode` é a imagem PNG do QR desse código em base64 (sem o prefixo `data:`; use `<img src="data:image/png;base64,{qrcode}">`). O QR tem o logo PIX no centro e correção de erro alta. Não precisa gerar QR do seu lado nem redirecionar para `url`, a menos que queira usar o checkout hospedado.
>
> `order_group_id` e `checkout_options` vêm sempre: com um só método ativo, `order_group_id` é `""` e `checkout_options` tem um item só.

### `order_id`: texto opaco, devolvido intacto

`order_id` aceita qualquer string não vazia. O backend não valida formato nem tamanho, não coloca esse valor no BR Code e não o interpreta: ele volta exatamente igual na resposta de `/registrar` e em todo IPN. Por isso dá para usar um **token assinado pelo seu backend** (ex.: `base64url(dados do pedido) + "." + HMAC`) e, ao receber o IPN, validar a assinatura e recuperar o contexto do pedido sem consultar banco.

Cuidados:
- `order_id` **não é secreto**: aparece para o comprador no checkout hospedado (`/pagar`, como "Fatura: ..."), no painel, nas notificações push, no extrato e nos logs do Pangeia PAY. Não coloque dado sensível em texto claro. Se usar o checkout hospedado, um token longo vai aparecer inteiro na tela do comprador; com checkout próprio (usando `pixcode`/`qrcode`) isso não acontece.
- `order_id` **não é único** na plataforma: registrar o mesmo valor duas vezes cria duas cobranças independentes. Para identificar a cobrança exata, use `unique_id`.

## 2) Registrar cobrança Bitcoin

> Este exemplo depende da conta estar com apenas `Bitcoin` ativo.

```bash
curl -X POST "https://pay.pangeialabs.com/registrar" \
  -H "Content-Type: application/json" \
  -d '{
    "buyer_name": "Maria Souza",
    "buyer_taxid": "98765432100",
    "order_amount": 250.00,
    "order_id": "PED-BTC-9001",
    "api_key": "SUA_API_KEY",
    "crypto_confirmations": 6
  }'
```

## 2.1) Registrar cobrança com múltiplos métodos (PIX + BTC + OUTRA)

> Para retornar múltiplas opções, ative `pix_enabled`, `bitcoin_enabled` e `outracoin_enabled` na conta.

```bash
curl -X POST "https://pay.pangeialabs.com/registrar" \
  -H "Content-Type: application/json" \
  -d '{
    "buyer_name": "Joao da Silva",
    "buyer_taxid": "12345678901",
    "order_amount": 149.90,
    "order_id": "PED-10002",
    "api_key": "SUA_API_KEY",
    "redirect_url": "https://seusite.com/retorno"
  }'
```

Resposta esperada (201) inclui:
- `allowed_payment_methods`
- `order_group_id` (UUID que liga as cobranças de cada método do mesmo pedido)
- `checkout_options`: um item por método, cada um com seu próprio `unique_id`, `url`, `quote_available` e `quote_unavailable_reason`
- `checkout_quote_snapshot` com equivalentes congelados no cadastro para os métodos cripto ativos (ex.: BTC/OUTRA)

> **Qual método vem no nível raiz da resposta?** Quando a conta tem PIX habilitado, PIX é **sempre** o `payment_method` primário — mesmo com Bitcoin/Outracoin também ativos na mesma conta. Por isso `pixcode`/`qrcode` sempre aparecem direto na raiz da resposta sempre que PIX estiver entre os métodos habilitados, independente de quantos outros métodos também estejam ativos. O array `checkout_options` só traz `payment_method`/`unique_id`/`url` por método — **não** tem código/endereço inline; para os demais métodos da mesma cobrança, siga a `url` de cada opção (ela abre o checkout específico daquele método, com o QR/endereço correto). Se você já assume PIX como principal e usa a `url` como plano B para os outros métodos, está certo — é exatamente assim que o sistema funciona hoje.

## 3) Consultar status

```bash
curl "https://pay.pangeialabs.com/status/65f5b0b6c2ab1d8b8f6a1234"
```

Resposta (200), cobrança PIX registrada com `redirect_url`:

```json
{
  "status": "paid",
  "translated": "Pagamento Confirmado",
  "payment_method": "pix",
  "requested_payment_method": "pix",
  "status_source_unique_id": "65f5b0b6c2ab1d8b8f6a1234",
  "redirect_url": "https://seusite.com/retorno"
}
```

- `redirect_url` é o mesmo valor enviado em `/registrar`; só aparece quando foi informado. O checkout hospedado só redireciona o comprador para ele se começar com `http://` ou `https://`.
- Em cobrança com vários métodos, o status é o do **grupo**. Se você consultar o `unique_id` do PIX depois que o comprador pagou em BTC, a resposta vem com `status: "paid"`, `payment_method: "bitcoin"`, `requested_payment_method: "pix"` e o `unique_id` do BTC em `status_source_unique_id`.
- Quando a cobrança-fonte é cripto, a resposta também traz os campos `crypto_*` (endereço, valor exigido, recebido confirmado/não confirmado, confirmações atuais/faltantes, último TXID etc.; lista completa em `StatusResponse` no OpenAPI).
- `unique_id` inválido retorna 400 e inexistente retorna 404, ambos com `{"status": "invalid", "translated": "..."}`.

Status possíveis no retorno de `GET /status/{unique_id}`:
- `pending`
- `confirming`
- `paid`
- `canceled`
- `processing`
- `shipped`
- `delivered`
- `expired` (status derivado por tempo de expiração, quando aplicável)

### Janelas de expiração

Duas janelas distintas, configuráveis via env vars no servidor:

- `MINUTES_TO_PAY` (padrão **30 min**): prazo mostrado ao comprador na tela de checkout. Depois disso, `GET /status/{unique_id}` já retorna `status: "expired"` — mas a transação **ainda está `pending`** no banco.
- `MINUTES_TO_EXPIRE` (padrão **60 min**): prazo real até o worker de expiração cancelar a transação (`order_status: "canceled"`) e liberar o `unique_amount` para reuso em outra cobrança. É só nesse momento que o IPN é enviado. **O worker só cancela transações ainda em `pending`** — uma transação em `confirming` (ex.: pagamento cripto já detectado, aguardando confirmações) não é auto-cancelada por tempo e fica pendente até ser resolvida por outro fluxo.

**`expired` nunca chega por IPN.** Não é persistido como `order_status` no banco — é só um valor calculado na hora pelo `GET /status/{unique_id}` enquanto a transação segue `pending`. O único IPN automático de "não pago a tempo" é `order_status: "canceled"`, disparado pelo worker de expiração depois de `MINUTES_TO_EXPIRE`. Não espere/trate um IPN com status `expired` na sua integração — ele não existe.

Ou seja, há uma folga de até 30 min entre o comprador ver "expirado" na tela e a cobrança ser efetivamente cancelada/o IPN de `canceled` chegar no backend do lojista.

## 3.1) `unique_amount`: quando ele diverge de `order_amount`

Por padrão, `unique_amount` é **exatamente igual** a `order_amount` — não há variação artificial em cada cobrança. Só existe desvio quando já há outra cobrança `pending`/`confirming` no mesmo escopo (mesma chave PIX para PIX; mesma `api_key` para cripto) com o **mesmo valor**: nesse caso de colisão, o backend tenta `-0.01` repetidas vezes e, se chegar a zero, inverte e soma `+0.01` até achar um valor livre (até 100 tentativas).

A baixa automática por e-mail (conciliação PIX) casa pelo **valor exato** — não há tolerância de centavos nessa comparação. Se o valor recebido no e-mail do banco não bater centavo a centavo com o `unique_amount` da cobrança pendente, ela não é conciliada automaticamente.

## 4) Obter payload/QR da cobrança

```bash
curl "https://pay.pangeialabs.com/pixqrcode/65f5b0b6c2ab1d8b8f6a1234"
```

Resposta para PIX:

```json
{
  "payment_method": "pix",
  "pixcode": "00020126...6304ABCD",
  "qrcode": "iVBORw0KGgoAAAANS..."
}
```

Resposta para cripto: `payment_method`, `payment_uri` (URI `bitcoin:`/`outracoin:` com endereço e valor), `crypto_address`, `crypto_required_amount`, `crypto_quote_unavailable`, `crypto_quote_error` e `qrcode`. Se a cotação estiver indisponível, retorna **409** com `crypto_quote_unavailable: true` e `error` explicando o motivo.

Útil para pegar o QR de outro método da mesma cobrança: use o `unique_id` do item correspondente em `checkout_options`. Este endpoint não confere o status: ele devolve o código mesmo para cobrança paga ou cancelada, então consulte `/status` antes de exibir.

## 5) Payload de IPN que seu endpoint recebe

> **De onde vem o `ipn_secret`?** Ele **não** é algo que você escolhe/gera no seu lado e espera que o Pangeia PAY reconheça — é o contrário: a plataforma **gera automaticamente** um `ipn_secret` aleatório por conta, no momento em que você configura a `ipn_url` dessa conta no painel administrativo (`/dashboard/minha-conta`, linha expandida da conta — campo copiável). Você precisa copiar esse valor gerado e usar como o secret da sua integração. Se você definiu um secret próprio no seu `.env` esperando que o Pangeia PAY usasse o mesmo valor, a validação nunca vai bater — o valor certo é o que a plataforma gerou, não o que você escolheu.
>
> **`ipn_url` é por conta, não por cobrança.** `POST /registrar` não aceita um `ipn_url` no payload da cobrança — a notificação de uma cobrança sempre vai para a `ipn_url` configurada na conta (`api_key`) usada naquele registro. Hoje não há override por cobrança.

Quando uma cobrança muda de status, o Pangeia PAY envia `POST application/json` para a `ipn_url` da conta com este formato:

```json
{
  "unique_id": "65f5b0b6c2ab1d8b8f6a1234",
  "order_id": "PIXIA-1772489488-3468fc7e",
  "order_status": "paid",
  "order_amount": 10.0,
  "unique_amount": 10.0,
  "ipn_secret": "SEU_IPN_SECRET_DA_CONTA",
  "paid_on": "2026-03-02T22:23:51.160000",
  "paid_with": "pix",
  "redirect_url": "https://seusite.com/retorno",
  "description": null
}
```

Campos:
- `unique_id`: id da cobrança, o mesmo de `/registrar`, `/pagar`, `/pixqrcode` e `/status`. **Use este campo para identificar a cobrança** (o `order_id` pode se repetir). Em cobrança com vários métodos, o IPN de `paid` traz o `unique_id` do método que foi efetivamente pago.
- `order_id`: exatamente o valor enviado em `/registrar`. Se você mandou um token assinado, valide-o aqui (ver seção 1).
- `paid_on`: ISO 8601 em UTC **sem offset**; string vazia (`""`) quando a cobrança não foi paga (ex.: IPN de `canceled`).
- `paid_with`: `pix`, `bitcoin` ou `outracoin`.
- `redirect_url`: o valor enviado em `/registrar`, ou `null`.
- `description`: hoje sempre `null`, porque `/registrar` não aceita esse campo.
- IPN de `paid` vindo da conciliação cripto também traz `crypto_currency`, `crypto_symbol`, `crypto_required_amount`, `crypto_received_confirmed` e `crypto_refunded_total`.

Notas importantes:
- Entrega: timeout de ~15 s e só HTTP **200** conta como entregue. A partir da v1.7.14 a entrega é assíncrona (fila) com **retentativa contínua** em backoff exponencial (1 min, dobrando até um teto de 4h, pra sempre enquanto não entregar) — não precisa mais esperar uma mudança de status manual pra reenviar. Use `GET /status/{unique_id}` como fonte de verdade enquanto isso.
- Depois de muitas tentativas falhando pra uma conta, o admin do Pangeia PAY pode **pausar** o IPN dela (o dono recebe e-mail explicando o motivo — ex.: URL não alcançável, ou resposta fora do contrato documentado aqui). Cobranças continuam normais, só a notificação fica em espera; o dono reativa a qualquer momento em `Contas` no painel, e a entrega retoma de onde a fila estava.
- A partir da v1.7.14 o IPN vem assinado em headers (ver abaixo); o campo `ipn_secret` continua também no corpo, pra integrações antigas que só validam por ele.
- O campo de status enviado é `order_status` (não `status`).
- Sua integração deve aceitar qualquer transição de status a qualquer momento (sem restrição de máquina de estados), incluindo `paid -> canceled` e `canceled -> paid`.
- **Não existe status de estorno.** Se a conta do recebedor for desativada/banida pela plataforma enquanto um pagamento já estava em curso, a baixa acontece normal (`order_status: paid`, IPN como qualquer outro) — o Pangeia PAY não é custodiante, o dinheiro já caiu direto na chave/endereço do recebedor antes da baixa. Um eventual estorno nesse caso é resolvido manualmente pela administração da plataforma, fora do sistema; não gera nenhum IPN adicional nem campo diferenciando esse `paid` de um pagamento normal.

### Assinatura do IPN (headers)

Toda entrega (e cada retentativa) vem com três headers:
- `X-Pangeia-Signature`: `sha256=<hex>` — HMAC-SHA256 de `"<timestamp>.<corpo_json_compacto>"` usando o `ipn_secret` da conta como chave. `<corpo_json_compacto>` é exatamente o corpo recebido, sem espaços (`json.dumps(..., separators=(",", ":"))` do lado do Pangeia PAY) — não o re-serialize antes de validar, use os bytes crus do request.
- `X-Pangeia-Timestamp`: timestamp Unix da tentativa de entrega (entra no HMAC, protege contra replay).
- `X-Pangeia-Event-Id`: mesmo valor em toda tentativa do mesmo evento — use pra deduplicar se o seu endpoint processar o mesmo IPN mais de uma vez.

Verificação em Python:
```python
import hmac, hashlib

def ipn_signature_valida(raw_body: bytes, timestamp: str, signature_header: str, ipn_secret: str) -> bool:
    esperado = hmac.new(
        ipn_secret.encode(),
        f"{timestamp}.".encode() + raw_body,
        hashlib.sha256,
    ).hexdigest()
    recebido = signature_header.removeprefix("sha256=")
    return hmac.compare_digest(esperado, recebido)
```

Status possíveis em `order_status`:
- `pending`
- `confirming`
- `paid`
- `canceled`
- `processing`
- `shipped`
- `delivered`

Quando o IPN é disparado (comportamento atual):
- **Automático, só `paid` e `canceled`:** os workers de conciliação PIX/cripto só disparam IPN com `order_status: "paid"`; o worker de expiração só dispara com `"canceled"`. Nenhum outro status (`pending`, `confirming`, `processing`, `shipped`, `delivered`) é enviado automaticamente pelo fluxo normal de pagamento — **não espere IPN automático desses status**.
- **Manual, qualquer status:** o painel administrativo permite ao lojista/operador alterar o status de um pedido manualmente para qualquer um dos 7 valores (`pending`, `confirming`, `paid`, `canceled`, `processing`, `shipped`, `delivered`) — útil para refletir etapas de logística (ex.: `shipped`/`delivered`) em produtos físicos. Essa alteração manual **dispara um IPN real** com o status escolhido.
- Mudanças de status (e, portanto, novos IPNs para a mesma cobrança) são possíveis a qualquer momento; trate o IPN como evento de estado atual, sem supor progressão fixa, e processe de forma idempotente por `unique_id` + `order_status`.

## Notas de consistência operacional

- `/registrar` não lê mais `payment_method` do payload; as opções de checkout vêm da configuração da conta (`pix_enabled`, `bitcoin_enabled`, `outracoin_enabled`).
- `VALID_PAYMENT_METHODS` efetivo em runtime: `pix`, `bitcoin`, `outracoin`.
