MERCHANT DOCUMENTATION

Integre PIX sem transformar o seu site num projeto financeiro.

O PiXBrasil separa Stores, pagamentos, liberações, Wallet BRL e credenciais. Esta documentação mostra o fluxo mínimo e seguro para integrar um site, e-commerce, SaaS ou funnel.

Estado atual da plataforma

A documentação reflete a operação de produção: cobrança PIX, status, webhooks, settlement e Wallet BRL.

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.

Execução PIX

Produção

Stores ativas criam PIX real e retornam QR Code e Copia e Cola por uma interface única do PiXBrasil.

Settlement & payouts

Operacional

As liberações alimentam a Wallet BRL conforme a regra comercial da Store. Payouts podem ser solicitados diretamente pelo portal.

O modelo mental em 60 segundos

Merchant

A empresa que integra o PiXBrasil.

Store

O escopo comercial que organiza pagamentos, regras e liberações.

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