Introdução

A API da SimPix permite integrar pagamentos Pix, solicitar saques (cashout), consultar saldo e receber notificações em tempo real via webhooks. Todos os endpoints exigem os headers x-api-key e x-token.

Base URL de produção:

Base URL

https://api.simpixpagamentos.com

Autenticação

Toda requisição deve incluir:

Header	Obrigatório	Descrição
Content-Type	Sim	Sempre application/json
x-api-key	Sim	Sua API key
x-token	Sim	Seu token de acesso

Requisições POST também exigem:

Header	Obrigatório	Descrição
idempotency-key	Sim (POST)	Chave única por operação. Garante que a mesma requisição não seja processada duas vezes.

Headers opcionais:

Header	Obrigatório	Descrição
x-timezone	Não	Timezone para campos de data/hora (ex.: America/Sao_Paulo). Padrão: UTC.

Exemplo de requisição autenticada

curl --request GET \
  --url https://api.simpixpagamentos.com/api/balance \
  --header 'x-api-key: <API_KEY>' \
  --header 'x-token: <TOKEN>' \
  --header 'x-timezone: America/Sao_Paulo'

Envelope de resposta

Todas as respostas de sucesso seguem o mesmo envelope, com os campos code, content, message e timestamp:

Resposta de sucesso

{
  "code": 200,
  "content": {
    "currency": "BRL",
    "balance": 1250.75,
    "blocked": 120.00,
    "reserve": 80.00,
    "processing": 45.50
  },
  "message": "Balance returned",
  "timestamp": "2025-02-19T17:15:26.703Z"
}

Respostas de erro usam o formato:

Resposta de erro (400)

{
  "error": 400,
  "message": "Invalid request payload"
}

Endpoints

Transações

POST /api/transactions cria uma transação Pix; GET /api/transactions consulta com filtros (magic_id, status, external_ref, end_to_end, limit, resend).

Saques (Cashout)

POST /api/withdrawals solicita um cashout Pix; GET /api/withdrawals consulta com os mesmos filtros.

Saldo

GET /api/balance retorna o saldo com breakdowns balance, blocked, reserve e processing.

Webhooks

POST, GET e DELETE /api/webhooks para registrar, listar e remover endpoints de notificação.

Exports

GET /api/export/charges e GET /api/export/withdrawals enfileiram exportações por date_range.

Próximos passos

QuickstartCrie sua primeira transação Pix em minutos.

Guia de WebhooksReceba confirmações em tempo real e valide a assinatura HMAC.

Dicas

• Use magic_id ou external_ref para conciliação.
• Valide o header x-webhook-signature com HMAC SHA256.
• Use o query param resend=true para reenviar webhooks.
• Mantenha seus handlers de webhook idempotentes.
• Use o header x-timezone para timestamps localizados.