Modo compatível (conector)

Plataformas de corretora integram gateways via conectores pré-construídos. O gateway expõe uma facade compatível com esse conector: a corretora só aponta o conector para o nosso endpoint — zero código novo. Base URL: https://api.swytchpay.app/compat Envelope { success, data, errors } · valores em BRL decimal. Credenciais (modo test, para validar a integração):

clientId (Client ID):     pk_test_…   (fornecido pela plataforma)
password (Client Secret): sk_test_…   (fornecido pela plataforma · só aparece uma vez)

Autenticação

POST /compat/cli/client/authenticate

{ "clientId": "<sua chave pública>", "password": "<sua chave secreta>" }
→ { "success": true, "data": { "clientId": "…", "name": "…", "token": "<Bearer 8h>" } }

Envie o token como Authorization: Bearer … nas demais chamadas.

Gerar PIX (cobrança)

POST /compat/cli/payment/pix/generate-pix

{
  "value": 50.00,
  "expiration": 3600,
  "externalId": "pedido-42",
  "payerName": "João da Silva",
  "payerDocument": "12345678901",
  "payerEmail": "joao@gmail.com",
  "payerPhone": "+5511999998888"
}
→ { "success": true, "data": { "pix": "000201…", "value": 50, "clientId": "…", "paymentId": "dep_…", "movId": "…" } }

pix é o copia-e-cola (renderize o QR no front). paymentId identifica a cobrança e volta no webhook.

Novos campos de identificação do depositante — comece a enviar agora.payerName · payerDocument (CPF/CNPJ, só números) · payerEmail · payerPhone — os dados reais do cliente que vai pagar a cobrança. São opcionais hoje, mas passarão a ser obrigatórios em breve: os provedores de pagamento exigem a identificação do depositante na criação da cobrança (prevenção a fraude e lavagem). Transações identificadas também têm prioridade de roteamento e melhor taxa de aprovação.payerDocument inválido (dígito verificador) é recusado com 400.

Saque

POST /compat/cli/payment/pix/pix-key

{
  "externalId": "saque-7",
  "pixKey": "12345678901",
  "payment": { "amount": "100.00" },
  "receiverName": "João da Silva",
  "receiverDocument": "12345678901",
  "receiverEmail": "joao@gmail.com",
  "receiverPhone": "+5511999998888"
}

Novos campos de identificação do recebedor — comece a enviar agora.receiverName · receiverDocument (CPF/CNPJ, só números) · receiverEmail · receiverPhone — os dados reais de quem recebe o saque. Opcionais hoje, obrigatórios em breve (mesma exigência dos provedores que vale para o depósito). receiverDocument inválido é recusado com 400.

Saldo

GET  /compat/cli/client/balance        → { accountBalance, precautionaryBlocking, availableBalance, availableBalanceUsdt }

Webhook (confirmações de pagamento)

Registre uma vez a URL que recebe as confirmações + a securityParaphrase que você usa pra validar: PUT /compat/cli/client/update/notification-url

{ "notificationUrl": [{ "url": "https://suacorretora.com/webhook", "permission": ["PIX_IN", "PIX_OUT"] }], "securityParaphrase": "sua-frase-secreta" }

As confirmações chegam no formato do conector — depósito (PixIn) e saque (PixOut):

// depósito pago
{ "status": "CONFIRMED", "type": "PixIn",  "externalId": "pedido-42", "paymentId": "dep_…", "movId": "…", "amount": 50,  "securityParaphrase": "…" }
// saque pago
{ "status": "CONFIRMED", "type": "PixOut", "externalId": "saque-7",   "paymentId": "pyt_…", "movId": "…", "amount": 100, "securityParaphrase": "…" }

Valide cada webhook pela securityParaphrase (a mesma que você cadastrou em notification-url).

Integrações antigas que usam o prefixo de URL anterior seguem funcionando normalmente — mas atualize para /compat/cli/… quando puder: é o caminho canônico daqui em diante.

O “Token IP” do conector aqui é self-serve: é a allowlist de IP por conta (IPv4/IPv6 · CIDR). Cadastre pela API (PUT /v1/ip-allowlist) ou pelo painel — veja Restrição de IP. Não há token separado: a autenticação continua sendo clientId/password; o IP só restringe de onde as chaves podem ser usadas.

Introdução

API

Integração de corretora

Modo compatível (conector)

Autenticação

Gerar PIX (cobrança)

Saque

Saldo

Webhook (confirmações de pagamento)

​Autenticação

​Gerar PIX (cobrança)

​Saque

​Saldo

​Webhook (confirmações de pagamento)

Autenticação

Gerar PIX (cobrança)

Saque

Saldo

Webhook (confirmações de pagamento)