MERCHANT DOCUMENTATION

Integre PIX sem transformar o seu site num projeto financeiro.

O PiXBrasil separa Store, routing, provider, liberação e credenciais. Esta documentação mostra o fluxo mínimo e seguro para integrar um site, e-commerce, SaaS ou funnel ao Core.

Estado atual da plataforma

A documentação distingue capacidade disponível de execução financeira ainda em validação.

API S2S

Disponível

API Keys por Merchant/Store, idempotência, PaymentIntent e consulta de status.

Merchant Webhooks

Disponível

Endpoints HTTPS assinados com HMAC-SHA256 e signing secret em Vault.

Provider execution

SHADOW / piloto controlado

A Store só cria PIX real quando o modo de execução for explicitamente ativado.

Payouts & settlement

Guarded

Liberação e payout obedecem à release policy da Store; automações continuam feature-flagged.

O modelo mental em 60 segundos

Merchant

A empresa que integra o PiXBrasil.

Store

O escopo comercial/operacional que define routing e release.

PaymentIntent

A intenção de pagamento criada de forma idempotente.

Webhook

A confirmação assíncrona enviada ao backend do merchant.

Quickstart

1Gere uma API Key
No Admin PiXBrasil, crie uma chave S2S com grants apenas às Stores necessárias.
2Guarde no servidor
Nunca envie a chave para JavaScript client-side, app móvel, GTM ou HTML.
3Crie PaymentIntent
Valide preço/pedido no seu backend e chame POST /payments/charge com Idempotency-Key.
4Configure webhook
Crie um endpoint HTTPS no seu site e registre-o no PiXBrasil.

Environment.env

# Server-side only
PIXBRASIL_API_URL=https://api.pixbrasil.org/api/v1
PIXBRASIL_API_KEY=pix_live_...
PIXBRASIL_STORE=SIGNUM

Create paymentcurl

curl -X POST https://api.pixbrasil.org/api/v1/payments/charge \
  -H "Authorization: Bearer $PIXBRASIL_API_KEY" \
  -H "Idempotency-Key: order-8472-pix-1" \
  -H "Content-Type: application/json" \
  -d '{
    "store": "SIGNUM",
    "amount": 149.90,
    "currency": "BRL",
    "reference": "ORDER-8472",
    "payer": {
      "name": "Cliente Exemplo",
      "taxId": "CPF_OU_CNPJ_VALIDO"
    },
    "metadata": {
      "orderId": "8472",
      "attribution": {
        "utm_source": "meta",
        "utm_campaign": "signum-launch"
      }
    }
  }'