> ## Documentation Index
> Fetch the complete documentation index at: https://docs.swytchpay.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Modo compatível (conector)

> Drop-in para corretoras com conector pré-built

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`

```json theme={null}
{ "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`

```json theme={null}
{
  "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.

<Warning>
  **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`.
</Warning>

## Saque

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

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

<Warning>
  **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`.
</Warning>

## 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`

```json theme={null}
{ "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`):

```json theme={null}
// 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`).

<Info>
  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.
</Info>

<Info>
  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](/reference/ip-allowlist).
  Não há token separado: a autenticação continua sendo `clientId`/`password`; o IP só restringe de onde
  as chaves podem ser usadas.
</Info>