# Versell Pix API — Guia Completo de Integração (para humanos e agentes de IA)

> Este arquivo contém TUDO que é necessário para integrar com a API da Versell sem precisar navegar pelo site. Última atualização: 2026-07-19.
> Documentação navegável: /docs/introduction · Coleção Postman: /Versell_Pix_API.postman_collection.json

## 1. Visão geral

A Versell oferece 4 módulos de pagamento, distribuídos em DUAS APIs independentes:

| Módulo | O que faz | API | Base URL |
|---|---|---|---|
| Cash In | Receber Pix via QR Code dinâmico (cob/cobv) | QR Codes API | `https://api.pix.basspago.com.br` |
| Pix Automático | Recorrências com débito automático via Pix (padrão Bacen) | QR Codes API | `https://api.pix.basspago.com.br` |
| Cash Out | Enviar Pix (chave, QR Code, dados bancários), saldo, extrato | Accounts API | `https://pagamentos.basspago.com.br/api/v2` |
| Boleto | PAGAR boletos de terceiros (não há emissão de boleto) | Accounts API | `https://pagamentos.basspago.com.br/api/v2` |

Painel web (Finance): `https://finance.versell.com.br` — acompanhamento de transações e configuração de webhooks pela interface.

### Regras de ouro (erros mais comuns de integração)

1. **São duas APIs separadas.** Certificados mTLS, client_id/secret e tokens do Cash In NÃO funcionam no Cash Out, e vice-versa.
2. **mTLS é obrigatório nas duas APIs.** Sem apresentar o certificado de cliente (`.crt` + `.key`, entregues no kickoff), a conexão TLS é rejeitada antes mesmo do OAuth.
3. **Formatos de token diferentes** (ver seção 2): Cash In usa form-urlencoded com snake_case; Cash Out usa JSON com camelCase.
4. **Formatos de valor diferentes**: Cash In usa string em reais (`"valor": {"original": "10.00"}`); Cash Out/Boleto usam objeto (`"payment": {"currency": "BRL", "amount": 100.00}`).
5. **Idempotência**: header `x-idempotency-key` (alfanumérico, 1–50 chars, `[a-zA-Z0-9]{1,50}`) é OBRIGATÓRIO em todos os pagamentos do Cash Out e do Boleto. Reutilizar uma chave já consumida retorna HTTP 412. Cash In não usa.
6. **Tokens expiram rápido no Cash In** (300s = 5 min) vs Cash Out (3600s = 1 h). Implemente renovação automática.

## 2. Autenticação

### 2.1 Cash In / Pix Automático (QR Codes API)

```
POST https://api.pix.basspago.com.br/oauth/token
Content-Type: application/x-www-form-urlencoded

client_id={client_id}&client_secret={client_secret}&grant_type=client_credentials
```

Resposta: `{ "access_token": "...", "token_type": "Bearer", "expires_in": 300 }`

cURL com mTLS:
```bash
curl -X POST https://api.pix.basspago.com.br/oauth/token \
  --cert ./client.crt --key ./client.key \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "client_id={client_id}&client_secret={client_secret}&grant_type=client_credentials"
```

Escopos relevantes: `cob.write cob.read cobv.write cobv.read pix.write pix.read webhook.write webhook.read payloadlocation.write payloadlocation.read rec.write rec.read solicrec.write solicrec.read cobr.write cobr.read payloadlocationrec.write payloadlocationrec.read webhookrec.write webhookrec.read webhookcobr.write webhookcobr.read`

### 2.2 Cash Out / Boleto (Accounts API)

```
POST https://pagamentos.basspago.com.br/api/v2/oauth/token
Content-Type: application/json

{ "clientId": "{clientId}", "clientSecret": "{clientSecret}", "grantType": "client_credentials" }
```

Resposta: `{ "access_token": "...", "token_type": "Bearer", "expires_in": 3600, "scope": "pix.read pix.write" }`

Escopos relevantes: `pix.read pix.write billets.read billets.write webhook.read webhook.write`

### 2.3 Uso do token

Todas as chamadas subsequentes: header `Authorization: Bearer {access_token}` + `Content-Type: application/json` + certificado mTLS da API correspondente.

## 3. Cash In — Receber Pix (base: https://api.pix.basspago.com.br)

Fluxo: obter token → criar cobrança (QR Code) → cliente paga → receber webhook → (opcional) reembolsar.

| Método | Endpoint | Função |
|---|---|---|
| POST | `/cob` | Criar cobrança imediata; txid gerado pelo PSP |
| PUT | `/cob/{txid}` | Criar cobrança com txid próprio (26–35 chars `[a-zA-Z0-9]`) |
| PATCH | `/cob/{txid}` | Atualizar cobrança |
| GET | `/cob/{txid}` | Consultar cobrança |
| GET | `/cob?inicio=&fim=` | Listar cobranças |
| PUT/PATCH/GET | `/cobv/{txid}` | Cobrança com vencimento (multa, juros, desconto) |
| GET | `/cobv` | Listar cobranças com vencimento |
| PUT/GET | `/lotecobv/{id}` | Lotes de cobranças com vencimento |
| POST/GET/DELETE | `/loc`, `/loc/{id}`, `/loc/{id}/txid` | Locations de payload (reuso de QR Code) |
| GET | `/{pixUrlAccessToken}` | Payload JWS do QR Code |
| GET | `/pix/{e2eid}` · `/pix?inicio=&fim=` | Consultar Pix recebidos |
| PUT | `/pix/{e2eid}/devolucao/{id}` | Solicitar reembolso (id definido por você) |
| GET | `/pix/{e2eid}/devolucao/{id}` | Consultar reembolso |
| PUT/GET/DELETE | `/webhook/{chave}` · GET `/webhook` | Webhook por chave Pix |

### Criar cobrança (POST /cob) — request mínimo

```json
{
  "calendario": { "expiracao": 3600 },
  "devedor": { "cpf": "12345678909", "nome": "Fulano de Tal" },
  "valor": { "original": "10.00" },
  "chave": "sua-chave-pix@example.com",
  "solicitacaoPagador": "Pagamento do pedido #12345"
}
```

Resposta 201 inclui: `txid`, `status: "ATIVA"`, `location`, `pixCopiaECola` (string EMV do QR Code — use-a para gerar a imagem do QR ou o copia-e-cola). Status de cobrança: `ATIVA`, `CONCLUIDA`, `REMOVIDA_PELO_USUARIO_RECEBEDOR`, `REMOVIDA_PELO_PSP`.

### Webhook de Cash In

Configure com `PUT /webhook/{chave}` body `{ "webhookUrl": "https://seu-endpoint.com/notificacoes" }`. A URL registrada recebe automaticamente o sufixo `/pix`: as notificações chegam via `POST https://seu-endpoint.com/notificacoes/pix` com payload:

```json
{ "pix": [ { "endToEndId": "E12345678...", "txid": "...", "chave": "...", "valor": "10.00", "horario": "2026-07-19T12:00:00.000Z", "infoPagador": "..." } ] }
```

Responda HTTP 2xx. Devoluções recebidas também notificam neste endpoint (campo `devolucoes` dentro do item de `pix`).

## 4. Cash Out — Enviar Pix (base: https://pagamentos.basspago.com.br/api/v2)

Fluxo: obter token → (opcional) consultar saldo → criar pagamento com `x-idempotency-key` → acompanhar status via consulta ou webhook.

| Método | Endpoint | Função |
|---|---|---|
| GET | `/api/v2/accounts/balances` | Saldo disponível |
| POST | `/api/v2/pix/payments/dict` | Transferir por chave Pix (CPF, CNPJ, EMAIL, PHONE, EVP) |
| POST | `/api/v2/pix/payments/qrc` | Pagar QR Code (envie o pixCopiaECola/EMV) |
| POST | `/api/v2/pix/payments/manu` | Pagar por dados bancários (ISPB, agência, conta) |
| GET | `/api/v2/pix/payments/{endToEndId}` | Consultar Pix por e2eId |
| GET | `/api/v2/pix/payments/idempotencyKey/{key}` | Consultar por idempotencyKey |
| GET | `/api/v2/pix/payments/receipt/{endToEndId}` | Comprovante do Pix em PDF (base64 em `data.pdf`) |
| GET | `/api/v2/accounts/transactions` | Extrato/transações (+ `/{id}` para detalhes) |
| POST/GET/DELETE | `/api/v2/webhooks/transfer` · `/receive` · `/refund` · `/cashout` | Webhooks por tipo de evento |
| GET/POST | `/api/v2/infractions` · `/{id}` · `/{id}/defenses` | Infrações MED e defesa |

### Transferência por chave (POST /api/v2/pix/payments/dict)

Headers: `Authorization`, `Content-Type`, `x-idempotency-key: {uuid-ou-string-unica}`.

```json
{
  "priority": "HIGH",
  "paymentFlow": "INSTANT",
  "expiration": 3600,
  "payment": { "currency": "BRL", "amount": 100.00 },
  "description": "Pagamento de serviços",
  "pixKey": "email@exemplo.com",
  "pixKeyType": "EMAIL",
  "creditorDocument": "12345678909"
}
```

`amount` em reais com decimais (100.00 = R$ 100,00). `paymentFlow`: `INSTANT` (processa imediatamente) ou `APPROVAL_REQUIRED` (retém para aprovação manual no painel Finance). Status do pagamento: `ON_QUEUE` → `PROCESSING` → `SETTLED` (liquidado) | `CANCELED` | `WAITING_APPROVAL` | `WAITING_CONFIRMATION` | `REFUNDED` | `PARTIALLY_REFUNDED`.

### Webhooks de Cash Out

Configurados por TIPO DE EVENTO (não por chave): `POST /api/v2/webhooks/transfer` (Pix enviado mudou de status), `/receive` (Pix recebido na conta), `/refund` (devolução), `/cashout` (falhas de envio). Body:

```json
{ "uri": "https://seu-endpoint.com/webhook", "enabled": true, "email": "dev@empresa.com", "method": "POST", "pauseOnFail": false, "headers": { "Authorization": "Bearer seu-token-interno" } }
```

Gerenciamento: `GET /api/v2/webhooks`, `GET/DELETE /api/v2/webhooks/{id}`.

## 5. Pix Automático — Recorrências (base: https://api.pix.basspago.com.br)

Pagamentos recorrentes com débito automático via Pix: o pagador autoriza UMA vez e as cobranças de cada ciclo são liquidadas automaticamente na data de vencimento. Padrão Bacen (API Pix 2.8+). Mesma API, token e certificados do Cash In.

### 5.1 Conceitos

- **rec** — a recorrência (o "contrato" de débito automático). Status: `CRIADA` → `APROVADA` | `REJEITADA` | `EXPIRADA` | `CANCELADA`.
- **idRec** — identificador da recorrência, 29 chars: `R` + `R|N` (permite ou não retentativa pós-vencimento) + ISPB (8) + `yyyyMMdd` + sequencial (11). Ex.: `RN1234567820260801abcdefghijk`.
- **solicrec** — solicitação de confirmação enviada ao PSP do pagador (usada na Jornada 1). Status: `CRIADA`, `ENVIADA`, `RECEBIDA`, `REJEITADA`, `ACEITA`, `EXPIRADA`, `CANCELADA`.
- **cobr** — cobrança recorrente de um ciclo. Status: `CRIADA`, `ATIVA`, `CONCLUIDA`, `EXPIRADA`, `REJEITADA`, `CANCELADA`. Cada cobr tem `tentativas[]` de liquidação (tipo `AGND` = agendada original, `NTAG` = retentativa; status `SOLICITADA`, `AGENDADA`, `PAGA`, `CANCELADA`, `REJEITADA`, `EXPIRADA`).
- **locrec** — location de payload para QR Code de recorrência.
- **periodicidade**: `SEMANAL`, `MENSAL`, `TRIMESTRAL`, `SEMESTRAL`, `ANUAL`.
- **politicaRetentativa**: `NAO_PERMITE` ou `PERMITE_3R_7D` (até 3 retentativas em 7 dias após o vencimento).

### 5.2 As 4 Jornadas de autorização (como o pagador aprova a recorrência)

| Jornada | Autorização | QR Code | Cobrança inicial | Sequência de chamadas |
|---|---|---|---|---|
| 1 | Notificação externa ao Pix (app/site do recebedor) | Não | Não | `POST /rec` → `POST /solicrec` |
| 2 | Pagador lê QR Code de recorrência | Simples | Não | `POST /rec` → `GET /rec/{idRec}` SEM `txid` → usar `dadosQR.pixCopiaECola` |
| 3 | Pagador lê QR Code composto | Composto | Sim (cob imediata) | `POST /rec` (com `ativacao.dadosJornada.txid` da cob) → criar `cob` → `GET /rec/{idRec}?txid={txid}` |
| 4 | Pagador lê QR Code composto | Composto | Sim (cobv com vencimento) | igual à 3, com `cobv` |

Após a aprovação (webhook `rec` com status `APROVADA`), crie uma **cobr** a cada ciclo com pelo menos 2 dias úteis de antecedência do vencimento.

### 5.3 Endpoints

| Método | Endpoint | Escopo | Função |
|---|---|---|---|
| POST | `/rec` | rec.write | Criar recorrência → 201 |
| GET | `/rec/{idRec}` (query `txid` opcional) | rec.read | Consultar; `dadosQR` traz o QR (simples sem txid, composto com txid) |
| PATCH | `/rec/{idRec}` | rec.write | Revisar: `status` (só `CANCELADA`), `vinculo.devedor.nome`, `loc`, `calendario.dataInicial`, `ativacao.dadosJornada.txid` |
| GET | `/rec?inicio=&fim=` | rec.read | Listar (filtros: cpf XOR cnpj, status, convenio, locationPresente, paginacao.*) |
| POST | `/solicrec` | solicrec.write | Criar solicitação de confirmação (Jornada 1); só 1 ativa por idRec |
| GET | `/solicrec/{idSolicRec}` | solicrec.read | Consultar solicitação |
| PATCH | `/solicrec/{idSolicRec}` | solicrec.write | Cancelar (`{"status":"CANCELADA"}`); só se CRIADA/ENVIADA/RECEBIDA |
| PUT | `/cobr/{txid}` | cobr.write | Criar cobrança do ciclo (txid seu, 26–35 chars) → 201 |
| POST | `/cobr` | cobr.write | Idem com txid gerado pelo PSP |
| GET | `/cobr/{txid}` | cobr.read | Consultar cobrança + tentativas |
| GET | `/cobr?inicio=&fim=` | cobr.read | Listar cobranças |
| PATCH | `/cobr/{txid}` | cobr.write | Cancelar (`{"status":"CANCELADA"}`); impossível a partir da data da 1ª tentativa de liquidação |
| POST | `/cobr/{txid}/retentativa/{data}` | cobr.write | Nova tentativa (NTAG) em data futura YYYY-MM-DD; requer PERMITE_3R_7D; sem body |
| POST/GET | `/locrec` · `/locrec/{id}` | payloadlocationrec.* | Locations de payload de recorrência |
| DELETE | `/locrec/{id}/idRec` | payloadlocationrec.write | Desvincular recorrência da location (status da rec não muda) |
| PUT/GET/DELETE | `/webhookrec` | webhookrec.* | Webhook de recorrências (GLOBAL, sem chave no path) |
| PUT/GET/DELETE | `/webhookcobr` | webhookcobr.* | Webhook de cobranças recorrentes (GLOBAL) |

### 5.4 Criar recorrência (POST /rec)

```json
{
  "vinculo": {
    "contrato": "63100862",
    "devedor": { "cpf": "45164632481", "nome": "Fulano de Tal" },
    "objeto": "Serviço de streaming de música"
  },
  "calendario": { "dataInicial": "2026-08-01", "dataFinal": "2027-08-01", "periodicidade": "MENSAL" },
  "valor": { "valorRec": "35.00" },
  "politicaRetentativa": "NAO_PERMITE",
  "loc": 108,
  "ativacao": { "dadosJornada": { "txid": "33beb661beda44a8928fef47dbeb2dc5" } }
}
```

Regras: `valorRec` (valor fixo por ciclo) e `valorMinimoRecebedor` são mutuamente exclusivos; `ativacao.dadosJornada.txid` é obrigatório apenas na Jornada 3 (txid da cob imediata); devedor PJ usa `cnpj` no lugar de `cpf`. Resposta 201 traz `idRec` e `status: "CRIADA"`.

### 5.5 Criar cobrança recorrente (PUT /cobr/{txid})

```json
{
  "idRec": "RR1234567820260801abcdefghijk",
  "infoAdicional": "Serviço de streaming — ciclo 08/2026",
  "calendario": { "dataDeVencimento": "2026-08-15" },
  "valor": { "original": "35.00" },
  "ajusteDiaUtil": true,
  "devedor": { "cep": "89256140", "cidade": "Uberlândia", "email": "cliente@mail.com", "logradouro": "Alameda Franco 1056", "uf": "MG" },
  "recebedor": { "agencia": "9708", "conta": "012682", "tipoConta": "CORRENTE" }
}
```

Regras: uma única cobr ativa (status ≠ REJEITADA/CANCELADA) por idRec por ciclo; `tipoConta`: `CORRENTE` | `POUPANCA` | `PAGAMENTO`; `ajusteDiaUtil: true` empurra a liquidação para o próximo dia útil.

### 5.6 Webhooks do Pix Automático

Configure com `PUT /webhookrec` e `PUT /webhookcobr`, body `{ "webhookUrl": "https://seu-endpoint.com/webhooks/pix-automatico" }`. As notificações chegam com sufixo no path:

`POST {webhookUrl}/rec` — mudanças de status de recorrências:
```json
{ "recs": [ { "idRec": "RR1026652320260821lab77511abf", "status": "APROVADA", "atualizacao": [ { "status": "CRIADA", "data": "2026-06-16T10:12:07.567Z" }, { "status": "APROVADA", "data": "2026-06-18T12:43:53.337Z" } ], "ativacao": { "tipoJornada": "JORNADA_3", "dadosJornada": { "txid": "r9eFIFmwcZ55Nm4RsKZAAtIvvCrlcNN6" } } } ] }
```

`POST {webhookUrl}/cobr` — mudanças de status/tentativas de cobranças:
```json
{ "cobsr": [ { "idRec": "RR1234567820260801abcdefghijk", "txid": "3136957d93134f2184b369e8f1c0729d", "status": "ATIVA", "atualizacao": [ { "status": "ATIVA", "data": "2026-06-16T12:34:21.300Z" } ], "tentativas": [ { "dataLiquidacao": "2026-06-20", "tipo": "AGND", "status": "SOLICITADA", "endToEndId": "E12345678202606201221abcdef12345" } ] } ] }
```

A chamada ao seu endpoint apresenta certificado de cliente mTLS (valide a origem). Dados de notificação ficam retidos por 15 dias. Responda HTTP 2xx.

## 6. Boleto — Pagamento (base: https://pagamentos.basspago.com.br/api/v2)

IMPORTANTE: não existe EMISSÃO de boleto (nem bolepix/híbrido, nem webhook de boleto). O módulo serve para PAGAR boletos de terceiros a débito da sua conta. Mesma API, token e certificados do Cash Out. Escopos: `billets.read`, `billets.write`.

Fluxo recomendado: consultar o boleto (`/billets/info`, obtém valor atualizado com juros/multa) → pagar (`/billets/pay` com o billetCode consultado, ou `/billets/payments` direto pela linha digitável) → acompanhar status (`GET /billets/{id}`) → baixar comprovante PDF.

| Método | Endpoint | Função |
|---|---|---|
| POST | `/api/v2/billets/info` | Consultar boleto — body `{ "billetCode": "..." }` (linha digitável ou código de barras, só números, ≤50 chars). Retorna `totalUpdated` (valor atualizado), vencimento, beneficiário, `allowChangeValue` |
| POST | `/api/v2/billets/payments` | Pagar pela linha digitável — body `{ "digitableCode": "...", "description": "...", "paymentFlow": "INSTANT", "payment": { "currency": "BRL", "amount": 150.75 } }` + header `x-idempotency-key`. Resposta 202 com `status: "ON_QUEUE"` |
| POST | `/api/v2/billets/pay` | Pagar por código previamente consultado — igual, com `billetCode` no lugar de `digitableCode` |
| GET | `/api/v2/billets?page=&perPage=` | Listar pagamentos |
| GET | `/api/v2/billets/{id}` · `/{id}/details` | Consultar pagamento (details inclui billetInfo, creditorAccount, debtorAccount) |
| GET | `/api/v2/billets/payments/receipt/{id}` | Comprovante em PDF base64 (`data.pdf`) |

Status do pagamento: `ON_QUEUE` → `PROCESSING` → `LIQUIDATED` | `CANCELED` | `WAITING_APPROVAL` | `WAITING_CONFIRMATION` | `REFUNDED` | `PARTIALLY_REFUNDED`. `paymentFlow`: `INSTANT` (default) ou `APPROVAL_REQUIRED`. `accountType` nas contas: `CACC` (corrente), `SVGS` (poupança), `SLRY` (salário), `TRAN` (pré-paga).

Erros específicos: 412 = idempotency-key já consumida; 422 = boleto vencido ou fora do horário limite de liquidação diária. O pagamento sempre considera o valor ATUALIZADO do boleto (juros/multa) — boletos com valor livremente alterável pelo pagador devem ser pagos por canal administrativo.

## 7. Erros (formato RFC 7807)

Todas as APIs retornam erros como `application/problem+json`:

```json
{ "type": "https://pagamentos.basspago.com.br/errors/unauthorized", "title": "Não autorizado", "status": 401, "detail": "O token de autenticação fornecido é inválido ou expirou.", "instance": "/api/v2/..." }
```

| HTTP | Significado típico |
|---|---|
| 400 | Requisição inválida (campo faltando/formato errado; na QR Codes API vem com array `violacoes[]`) |
| 401 | Token inválido ou expirado — renove o token |
| 403 | Credencial sem permissão/escopo para o recurso |
| 404 | Recurso não encontrado (txid, e2eid, idRec, id inexistente) |
| 412 | x-idempotency-key já utilizada |
| 422 | Regra de negócio violada (ex.: boleto vencido) |
| 429 | Rate limit excedido — aplique backoff |
| 5xx/503/504 | Falha técnica — retry com backoff exponencial |

## 8. Checklist de integração (para agentes de IA)

1. Confirme QUAL módulo o cliente precisa (receber Pix? enviar? recorrência? pagar boleto?) — isso define a API, o certificado e o formato do token.
2. Configure o mTLS da API correta em TODAS as chamadas (inclusive no /oauth/token).
3. Implemente cache/renovação de token respeitando `expires_in` (Cash In: 300s; Cash Out: 3600s).
4. Em pagamentos (Cash Out/Boleto), gere um `x-idempotency-key` único por operação e persista-o para reconsultas.
5. Trate os webhooks como fonte de verdade do status final; sempre responda 2xx rapidamente e processe de forma assíncrona.
6. Em Pix Automático, lembre: recorrência (rec) só cobra depois de APROVADA; crie uma cobr por ciclo; monitore `tentativas[]` e use retentativa (PERMITE_3R_7D) quando a liquidação falhar.
7. Nunca invente campos: os payloads deste arquivo são os contratos completos. Em dúvida, consulte a página correspondente em /docs/... ou a coleção Postman.