Visão geral

Uma carteira (wallet) é uma conta bancária que você cadastra na Selectwin para receber saques do seu saldo. Você registra os dados bancários uma vez, marca uma carteira como principal e, a partir daí, os saques são liquidados na conta escolhida. Use este recurso sempre que precisar definir ou trocar o destino do dinheiro que sai da plataforma.

O que é uma carteira

Pense na carteira como um "destino de pagamento" salvo. Em vez de informar agência e conta a cada saque, você cadastra a conta uma vez (POST /v1/wallets), recebe um id opaco (ex.: wall_01hqzvabc) e passa a referenciá-la por esse identificador.

A carteira não guarda saldo — o saldo fica no recurso Finance (Balance). A carteira apenas descreve para onde o dinheiro vai quando você cria um saque (withdrawal). É a ponte entre o seu saldo na Selectwin e o sistema bancário.

Cada carteira pertence a um merchant (vendedor). As respostas completas trazem um bloco merchant identificando o titular da conta na plataforma e um bloco _links (HATEOAS) com as próximas ações possíveis. Para a convenção de _links, veja Recursos.

O modelo do objeto

Abaixo, o objeto completo retornado por POST /v1/wallets e GET /v1/wallets/{walletId}, anotado:

{
  "id": "wall_01hqzvabc",            // identificador opaco da carteira (prefixo wall_)
  "name": "Conta principal",          // rótulo livre que você escolhe (mapeia o campo "name" enviado)
  "bankName": "Nubank",               // nome do banco, resolvido pela API a partir do bankCode
  "bankCode": "260",                  // código do banco (COMPE/ISPB) que você enviou
  "holderName": "João Santos",        // titular da conta, derivado do cadastro
  "routingNumber": "0001",            // agência (branch/routing)
  "accountNumber": "12345678",        // número da conta com dígito
  "accountType": "checking",          // tipo da conta (presente só no create/read)
  "primary": true,                    // se é a carteira padrão para saques
  "enabled": true,                    // se a carteira está ativa e pode ser usada
  "updatedAt": "2026-04-12T17:56:33.000Z",
  "createdAt": "2026-04-12T17:56:33.000Z",
  "merchant": {                       // dono da carteira na plataforma
    "name": "Seller Name",
    "merchantId": "bus_1234567890",
    "isSubAccount": false
  },
  "_links": { "self": { /* ... */ }, "create": { /* ... */ }, "delete": { /* ... */ }, "list": { /* ... */ } }
}

Campos do objeto

Diferenças de payload por operação

As respostas variam conforme a operação. Conheça as diferenças para não esperar um campo que não vem:

Itens de listagem são projeções leves: alguns campos do objeto completo (como accountType) são omitidos. Para o objeto completo, consulte a carteira individual com Consultar carteira.

Ciclo de vida

Uma carteira nasce ativa quando os dados bancários são aceitos, pode ser promovida a principal e existe até ser excluída. O diagrama abaixo resume os estados observáveis pelos campos enabled, primary e pela exclusão:

• Criação: ao enviar dados bancários válidos, a API resolve o banco a partir do bankCode, cria a carteira (enabled: true) e devolve o objeto completo. Dados inválidos ou banco não suportado retornam erro (veja a tabela de erros).
• Principal (primary): apenas uma carteira deve ser a padrão de saques por vez. Definir primary: true em uma carteira é o que direciona os saques para ela. Marcar uma nova como principal desloca o papel da anterior.
• Exclusão: DELETE remove a carteira. A operação não pode ter saques pendentes vinculados — caso contrário a API recusa (bankAccountNotDeletable). A exclusão é confirmada por um payload { id, resource: "wallet", deleted: true } e é irreversível: para voltar a usar a conta, cadastre-a novamente.

Operações

Todas as requisições usam a base https://api.selectwin.io/v1 e exigem o header de autenticação SelectKey. Em produção a chave começa com sl_live_; em sandbox, com sl_test_. Nunca use Authorization: Bearer/Basic. Veja Autenticação.

Exemplo rápido — criar uma carteira

curl -X POST https://api.selectwin.io/v1/wallets \
  -H "SelectKey: sl_live_aBcDeFgHiJkLmNoPqRsTuVwXyZ" \
  -H "Content-Type: application/json" \
  -H "X-Idempotency-Key: 7f3a1b9c-0e2d-4a6b-8c1f-2d3e4f5a6b7c" \
  -d '{
    "bankCode": "260",
    "accountNumber": "12345678",
    "routingNumber": "0001",
    "name": "Conta principal",
    "primary": true
  }'

O corpo de criação aceita: bankCode, accountNumber, routingNumber e name (todos obrigatórios) e primary (opcional). O campo X-Idempotency-Key evita criar a mesma carteira duas vezes em caso de repetição da requisição — veja Chave de idempotência. Detalhes completos em Criar carteira.

Exemplo rápido — listar carteiras

curl https://api.selectwin.io/v1/wallets?limit=20&sort=descending \
  -H "SelectKey: sl_live_aBcDeFgHiJkLmNoPqRsTuVwXyZ"

A listagem aceita limit (1–100), offset, sort (ascending/descending), id (filtro por ID exato) e filtros de data (daterange, daterangegt[e], daterangelt[e]). Veja Paginação e Listar carteiras.

Erros

Trate sempre pelo error.code (estável), nunca pela message. Códigos específicos do recurso Wallets:

Erros transversais que valem para qualquer operação: invalidParameters (400), unauthorized (401 — SelectKey ausente/inválida), forbidden (403), unprocessableEntity (422), tooManyRequests (429 — respeite error.retryAfterMinutes) e serverError (500 — repita com backoff). Catálogo completo em Códigos de Erro e envelope em Tratamento de Erros.

Boas práticas

1. Cadastre antes de sacar. Crie e confirme a carteira antes de tentar um saque; um saque para conta não registrada falha (withdrawalProcessFailedByWalletNotRegistered).
2. Confira bankCode na origem. Use o código COMPE/ISPB correto do banco; um código não suportado retorna bankCodeNotSupported na criação, não na liquidação.
3. Mantenha uma só primary. Garanta que apenas uma carteira esteja marcada como principal para que o destino dos saques seja inequívoco.
4. Use rótulos descritivos em name. "Conta principal" ou "Filial SP" facilitam a identificação quando há várias carteiras.
5. Não exclua com saques pendentes. Aguarde a liquidação dos saques vinculados; do contrário a exclusão retorna bankAccountNotDeletable.
6. Confira os dados antes de sacar. Use Consultar carteira para validar agência, conta e titular antes de movimentar valores.
7. Trate o id como opaco. Armazene a string inteira (wall_…); não construa nem interprete IDs manualmente.
8. Reaja por webhooks, não por polling. Para acompanhar mudanças de estado, assine eventos de webhook em vez de consultar a API em loop — veja Proibição de polling.

Veja também

• Criar carteira — cadastrar uma nova conta bancária.
• Consultar carteira — ler os dados completos de uma carteira.
• Listar carteiras — listagem paginada e a variante listall.
• Excluir carteira — remover uma carteira.
• Convenções — camelCase, centavos, datas UTC e IDs opacos.
• Autenticação — uso do header SelectKey.
• Eventos de Webhook — notificações de mudança de estado.