1) Fluxo de integração
- Registre uma cobrança em
POST /registrar.
- 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>.
- 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 | /registrar | API key | Cria cobrança PIX/BTC/OUTRA. |
GET | /pixqrcode/<unique_id> | Pública | Retorna payload e QRCode (PIX/cripto). |
GET | /status/<unique_id> | Pública | Status da cobrança (do grupo, em multi-método), redirect_url enviado + campos cripto. |
POST | IPN (callback para seu endpoint) | IPN Secret no payload | Pangeia 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_status | Aceitar e processar normalmente. |
Mudança invertida (ex.: paid -> canceled) | Tratar como atualização válida de estado. |
| Novo IPN para a mesma cobrança | Processar de forma idempotente por unique_id + order_status. |
9) Arquivos oficiais
/apidoc/openapi.yaml
/apidoc/examples