API REFERENCE

Uma API pequena, server-side e orientada a PaymentIntent.

A API merchant usa Bearer API Keys e grants por Store. Todas as operações sensíveis devem acontecer no backend do merchant.

Base URL & autenticação

Production

https://api.pixbrasil.org/api/v1

Authorization

Authorization: Bearer pix_live_...

Novas chaves emitidas pelo Admin recebem os scopes payments:create e webhooks:manage. Grants limitam quais Stores a chave pode utilizar.

POST /payments/charge

Cria um PaymentIntent idempotente e resolve Store → policy → provider → economics → release.

Requesthttp

POST /api/v1/payments/charge
Authorization: Bearer pix_live_...
Idempotency-Key: order-8472-pix-1
Content-Type: application/json

{
  "store": "SIGNUM",
  "amount": 149.90,
  "currency": "BRL",
  "reference": "ORDER-8472",
  "description": "SIGNUM 312",
  "payer": {
    "name": "Cliente Exemplo",
    "taxId": "CPF_OU_CNPJ_VALIDO",
    "email": "cliente@example.com",
    "phone": "+55..."
  },
  "metadata": {
    "orderId": "8472",
    "attribution": {
      "utm_source": "meta",
      "utm_medium": "paid",
      "utm_campaign": "launch"
    }
  }
}

Response while Store is SHADOWjson

{
  "success": true,
  "data": {
    "paymentIntentId": "uuid",
    "idempotentReplay": false,
    "status": "SHADOW_ONLY",
    "amount": 149.90,
    "currency": "BRL",
    "reference": "ORDER-8472",
    "store": {
      "code": "SIGNUM",
      "name": "Signum"
    },
    "routing": {
      "mode": "SHADOW",
      "policy": "NS-SIGNUM-PIX-D0",
      "providerCode": "MISTICPAY",
      "gatewayAlias": "misticpay-primary",
      "releaseClass": "D0",
      "crossReleaseClassFailover": false
    }
  }
}

Importante: SHADOW_ONLY significa que routing/economia foram validados, mas nenhum PIX real foi criado. Não renderize QR Code se a resposta estiver em SHADOW.

GET /payments/:paymentIntentId

Requesthttp

GET /api/v1/payments/{paymentIntentId}
Authorization: Bearer pix_live_...

Use consulta de status como fallback/reconciliação. O mecanismo principal para confirmação assíncrona deve ser webhook.

Webhook endpoint management

POST /api/v1/webhook-endpoints
Authorization: Bearer pix_live_...
Content-Type: application/json

{
  "name": "Production checkout",
  "endpointUrl": "https://shop.example.com/api/webhooks/pixbrasil",
  "events": [
    "payment.pending",
    "payment.succeeded",
    "payment.failed",
    "payment.canceled"
  ]
}

GET /webhook-endpoints

Lista endpoints, eventos, status, failure count e última entrega. O signing secret nunca é reexibido.

POST /webhook-endpoints/:id/test

Envia webhook.test para validar rede, TLS e handler.

POST /webhook-endpoints/:id/revoke

Revoga o endpoint imediatamente.

Signing secret

O whsec_... é retornado uma única vez na criação e armazenado em Vault no PiXBrasil.

Erros e comportamento esperado

HTTP	Quando	Ação
400	Payload, CPF/CNPJ, URL ou metadata inválidos	Corrija o request; não faça retry cego.
401	API Key ausente/inválida	Verifique env server-side.
403	Scope/Store não autorizado	Revise grants da chave.
404	PaymentIntent/Store não encontrado	Confirme IDs e escopo do merchant.
409	Idempotency-Key reutilizada com payload diferente	Não altere dados usando a mesma chave.
5xx	Falha temporária	Retry exponencial usando a mesma Idempotency-Key.

OpenAPI

A especificação machine-readable está disponível em /openapi.json para importar em Postman, Insomnia, Bruno ou ferramentas de geração de SDK.

Precisa integrar agora?

Use o AI Setup Kit e entregue o prompt à IA que já trabalha no seu repositório.

Abrir AI Setup Kits