Documentação

Visão geral

A API da PhanterPay é REST sobre HTTPS, com corpo e resposta em JSON snake_case. Toda requisição é autenticada por chave de API e todo POST financeiro exige uma chave de idempotência.

Webhooks são opcionais. Você pode integrar a PhanterPay somente com a API REST, criando a operação via POST e consultando o status pelos endpoints GET. Para atualizações automáticas em tempo real e menor uso de polling, recomendamos o uso de webhooks.

Base URL

BASEhttps://api.phanterpay.com.br/v1

Contrato estável

Respostas sempre em snake_case, IDs prefixados (chg_, pyt_) e envelope de erro único.

Webhooks assinados

HMAC-SHA256 sobre timestamp + corpo cru, com retentativas em backoff.

Idempotência

Idempotency-Key obrigatório na criação de cobranças e saques.

Rate limit previsível

600 requisições por minuto por chave, com headers de cota em toda resposta.

Ambientes

Não existe sandbox. Há um único ambiente e ele é produção: qualquer chamada pode movimentar dinheiro real na rede Pix. O valor mínimo por operação é R$ 2,00. Respostas e webhooks trazem test_mode: true quando o valor é de até R$ 5,00 — isso é apenas um rótulo para você filtrar seus próprios ensaios, não uma operação simulada: o Pix é executado e o dinheiro sai ou entra de verdade.

Primeira chamada

Gere uma chave no painel em API & Integrações, exporte-a no ambiente e consulte seu saldo:

bash

export PHANTERPAY_API_KEY="bp_a1b2c3d4_9f8e7d6c5b4a39281706f5e4d3c2b1a09f8e7d6c5b4a3928"

curl -s "https://api.phanterpay.com.br/v1/balance" \
  -H "Authorization: Bearer $PHANTERPAY_API_KEY"

Convenções

Item	Regra
Formato	JSON em snake_case na requisição e na resposta
Valores	Números decimais em reais (150.00), nunca centavos em string
Mínimo	R$ 2,00 por cobrança e por saque
Datas	ISO 8601 em UTC (2026-01-31T12:00:00.000Z)
IDs	chg_ para cobranças, pyt_ para saques, inf_ para infrações, evt_ para eventos
Paginação	Cursor: limit + starting_after (sem offset)
request_id	Presente em toda resposta de erro e no header x-request-id

Esta página foi útil?

Sua opinião nos ajuda a melhorar nossa documentação.