Pangeia Labs Pangeia PAY
Ir para Home

API Doc

Documentação completa para integrar sua plataforma com Pangeia PAY.

Versão da documentação: 1.1.0

1) Fluxo de integração

  1. Registre uma cobrança em POST /registrar.
  2. Redirecione o cliente para /pagar/<unique_id> ou monte checkout próprio: a resposta já traz pixcode (copia e cola) e qrcode (PNG base64), também disponíveis em /pixqrcode/<unique_id>.
  3. Acompanhe o resultado por polling em GET /status/<unique_id> e/ou receba IPN no seu backend.

Base URL produção: https://pay.pangeialabs.com

order_id é texto livre devolvido intacto em todo IPN: pode ser um token assinado pelo seu backend, validado no IPN sem consultar banco (mas não é secreto; o checkout hospedado o exibe ao comprador). unique_id é o id da cobrança: use-o para identificá-la.

2) Endpoints principais

Método Endpoint Auth Uso
POST/registrarAPI keyCria cobrança PIX/BTC/OUTRA.
GET/pixqrcode/<unique_id>PúblicaRetorna payload e QRCode (PIX/cripto).
GET/status/<unique_id>PúblicaStatus da cobrança (do grupo, em multi-método), redirect_url enviado + campos cripto.
POSTIPN (callback para seu endpoint)IPN Secret no payloadPangeia PAY envia atualizações de status para sua ipn_url.

Documentação full: OpenAPI YAML.

3) Exemplo cURL - criar cobrança

O request não envia payment_method; a API usa os métodos ativos na conta (pix_enabled, bitcoin_enabled, outracoin_enabled).

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"
  }'

3.1) Resposta - conta só com PIX ativo (201)

{
  "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..."
}

unique_amount vem igual a order_amount, salvo colisão de valor no mesmo escopo (mesma chave PIX). order_group_id e checkout_options vêm sempre; com um só método ativo, order_group_id é "".

3.2) Resposta - conta com cripto ativo (201)

Mesmo endpoint POST /registrar; muda o formato quando o método primário é Bitcoin/Outracoin em vez de PIX (conta sem PIX habilitado).

{
  "order_id": "PED-BTC-9001",
  "order_status": "pending",
  "payment_method": "bitcoin",
  "allowed_payment_methods": ["bitcoin"],
  "order_group_id": "",
  "unique_amount": 250.0,
  "unique_id": "65f5b0b6c2ab1d8b8f6a1235",
  "url": "https://pay.pangeialabs.com/pagar/65f5b0b6c2ab1d8b8f6a1235",
  "checkout_options": [
    {
      "payment_method": "bitcoin",
      "unique_id": "65f5b0b6c2ab1d8b8f6a1235",
      "url": "https://pay.pangeialabs.com/pagar/65f5b0b6c2ab1d8b8f6a1235",
      "quote_available": true,
      "quote_unavailable_reason": ""
    }
  ],
  "crypto_currency": "Bitcoin",
  "crypto_symbol": "BTC",
  "crypto_address": "bc1qxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "crypto_node_account_label": "pedido_250_btc9001",
  "crypto_quote_brl": 350000.0,
  "crypto_quote_brl_effective": 357000.0,
  "crypto_quote_source": "binance",
  "crypto_quote_fetched_on": "Sun, 11 Oct 2026 19:02:40 GMT",
  "crypto_agio_percent": 2.0,
  "crypto_required_base_amount": 0.00071429,
  "crypto_required_amount": 0.00072857,
  "crypto_confirmations_required": 6,
  "crypto_quote_unavailable": false,
  "crypto_quote_error": "",
  "payment_uri": "bitcoin:bc1qxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx?amount=0.00072857",
  "qrcode": "iVBORw0KGgoAAAANS..."
}

Se a cotação falhar, a resposta vem com 502 (falha de cotação/geração de endereço) ou 503 (RPC indisponível) em vez de 201. Quando PIX e cripto estão ativos na mesma conta, PIX sempre é o método primário da raiz (ver 3.1); o checkout_options traz a url dos demais métodos.

Erro de validação (400): {"error": "mensagem explicando o campo"}.

4) Exemplo cURL + resposta - QR/payload da cobrança

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

Resposta (200) para PIX:

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

Resposta (200) para cripto:

{
  "payment_method": "bitcoin",
  "payment_uri": "bitcoin:bc1qxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx?amount=0.00072857",
  "crypto_address": "bc1qxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "crypto_required_amount": 0.00072857,
  "crypto_quote_unavailable": false,
  "crypto_quote_error": "",
  "qrcode": "iVBORw0KGgoAAAANS..."
}

Não confere status: devolve o código mesmo para cobrança paga/cancelada (consulte /status antes de exibir). Cotação cripto indisponível retorna 409 com crypto_quote_unavailable: true e error explicando o motivo; unique_id inválido/inexistente retorna 400/404.

5) Exemplo cURL + resposta - consultar status

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

Resposta (200), cobrança PIX já paga, com redirect_url informado no registro:

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

Resposta (200), cobrança cripto em confirmação (campos crypto_* só aparecem quando a cobrança-fonte é cripto):

{
  "status": "confirming",
  "translated": "Pagamento em confirmação",
  "payment_method": "bitcoin",
  "requested_payment_method": "bitcoin",
  "status_source_unique_id": "65f5b0b6c2ab1d8b8f6a1235",
  "crypto_currency": "Bitcoin",
  "crypto_symbol": "BTC",
  "crypto_address": "bc1qxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "crypto_node_account_label": "pedido_250_btc9001",
  "crypto_quote_brl": 350000.0,
  "crypto_quote_brl_effective": 357000.0,
  "crypto_quote_source": "binance",
  "crypto_quote_fetched_on": "Sun, 11 Oct 2026 19:02:40 GMT",
  "crypto_quote_unavailable": false,
  "crypto_quote_error": "",
  "crypto_agio_percent": 2.0,
  "crypto_required_base_amount": 0.00071429,
  "crypto_required_amount": 0.00072857,
  "crypto_confirmations_required": 6,
  "crypto_confirmations_current": 2,
  "crypto_confirmations_remaining": 4,
  "crypto_latest_txid": "a1b2c3d4e5f6...",
  "crypto_received_total": 0.00072857,
  "crypto_received_confirmed": 0.0,
  "crypto_received_unconfirmed": 0.00072857,
  "crypto_missing_amount": 0.0,
  "crypto_overpaid_amount": 0.0,
  "crypto_refunded_total": 0.0
}

Erro (400 ID inválido ou 404 inexistente):

{
  "status": "invalid",
  "translated": "ID inválido"
}

status pode vir expired (derivado por tempo, enquanto a transação ainda está pending no banco) além de pending, confirming, paid, canceled, processing, shipped, delivered. Em cobrança multi-método, o status é do grupo: consultar o unique_id do PIX após pagamento em BTC retorna payment_method: "bitcoin", requested_payment_method: "pix" e o unique_id do BTC em status_source_unique_id.

6) Exemplo JavaScript (Node/fetch)

const BASE_URL = "https://pay.pangeialabs.com";

async function criarCobranca() {
  const res = await fetch(`${BASE_URL}/registrar`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      buyer_name: "Joao da Silva",
      buyer_taxid: "12345678901",
      order_amount: 149.90,
      order_id: "PED-10001",
      api_key: process.env.PANGEIA_API_KEY
    })
  });

  if (!res.ok) {
    const err = await res.json();
    throw new Error(err.error || `HTTP ${res.status}`);
  }

  const charge = await res.json();
  console.log("unique_id:", charge.unique_id);
  console.log("checkout_url:", charge.url);
  return charge;
}

async function esperarPagamento(uniqueId, timeoutMs = 10 * 60 * 1000) {
  const startedAt = Date.now();
  while ((Date.now() - startedAt) < timeoutMs) {
    const res = await fetch(`${BASE_URL}/status/${uniqueId}`);
    const st = await res.json();
    if (st.status === "paid") return st;
    if (st.status === "canceled" || st.status === "expired") throw new Error(`Status final: ${st.status}`);
    await new Promise(r => setTimeout(r, 3000));
  }
  throw new Error("Timeout aguardando pagamento");
}

7) Exemplo Python (requests)

import time
import requests

BASE_URL = "https://pay.pangeialabs.com"

def criar_cobranca(api_key: str):
    payload = {
        "buyer_name": "Joao da Silva",
        "buyer_taxid": "12345678901",
        "order_amount": 149.90,
        "order_id": "PED-10001",
        "api_key": api_key,
    }
    r = requests.post(f"{BASE_URL}/registrar", json=payload, timeout=20)
    r.raise_for_status()
    return r.json()

def esperar_status_pago(unique_id: str, max_wait_sec: int = 600):
    t0 = time.time()
    while time.time() - t0 < max_wait_sec:
        r = requests.get(f"{BASE_URL}/status/{unique_id}", timeout=15)
        r.raise_for_status()
        data = r.json()
        if data.get("status") == "paid":
            return data
        if data.get("status") in ("canceled", "expired"):
            raise RuntimeError(f"Status final: {data.get('status')}")
        time.sleep(3)
    raise TimeoutError("Tempo limite aguardando pagamento")

# uso:
# charge = criar_cobranca("SUA_API_KEY")
# print(charge["url"])
# pago = esperar_status_pago(charge["unique_id"])

8) Payload de IPN (callback)

{
  "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
}

Valide a autenticidade comparando o ipn_secret recebido com o secret salvo na sua integração — ou, de forma mais forte, verificando os headers de assinatura abaixo.

unique_id identifica a cobrança (o order_id pode se repetir); em multi-método, o IPN de paid traz o unique_id do método pago. paid_on é UTC sem offset (vazio se não pago). Só HTTP 200 conta como entregue; a entrega é assíncrona com retentativa contínua em backoff exponencial (1 min até um teto de 4h) enquanto não for aceita — use /status como fonte de verdade nesse meio tempo.

Depois de muitas tentativas falhando, o admin pode pausar o IPN dessa conta (você recebe e-mail explicando o motivo); suas cobranças continuam normais, só a notificação fica em espera até você reativar em Contas.

Headers de assinatura

Toda tentativa de entrega vem com três headers: X-Pangeia-Signature (sha256=<hex>, HMAC-SHA256 de "<timestamp>.<corpo_json_compacto>" usando o ipn_secret da conta), X-Pangeia-Timestamp (unix, entra no HMAC contra replay) e X-Pangeia-Event-Id (igual em toda tentativa do mesmo evento, use pra deduplicar).

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)

raw_body precisa ser os bytes crus recebidos, sem re-serializar — o HMAC é calculado sobre o corpo exatamente como foi enviado.

Status possíveis em order_status: pending, confirming, paid, canceled, processing, shipped, delivered.

Importante: seu endpoint deve aceitar qualquer transição de status a qualquer momento (sem máquina de estados restritiva), incluindo paid -> canceled e canceled -> paid.

Não existe status de estorno. Se a conta do recebedor for desativada/banida enquanto um pagamento já estava em curso, a baixa acontece normal (order_status: paid) — o Pangeia PAY não é custodiante, o dinheiro já caiu direto na chave/endereço do recebedor. Um eventual estorno é resolvido manualmente pela administração, fora do sistema; não gera IPN nem campo adicional.

Cenário Comportamento esperado na integração
Qualquer order_statusAceitar e processar normalmente.
Mudança invertida (ex.: paid -> canceled)Tratar como atualização válida de estado.
Novo IPN para a mesma cobrançaProcessar de forma idempotente por unique_id + order_status.