Criar uma carteira

Cadastra uma nova carteira (conta bancária) para a sua conta de recebimento, informando os dados bancários para onde os saques serão enviados. Use este endpoint quando precisar registrar uma conta de destino antes de solicitar saques, ou para manter mais de uma conta cadastrada.

POST /v1/wallets

Como funciona

Uma carteira (do inglês wallet) é o registro de uma conta bancária vinculada à sua conta na Selectwin. Ela serve como destino dos seus saques (withdrawals): o saldo disponível na sua conta é transferido para a conta bancária de uma carteira cadastrada.

Quando você envia este POST, o servidor:

1. Valida o código do banco (bankCode) contra a lista de instituições suportadas. Códigos não reconhecidos são recusados com bankCodeNotSupported.
2. Valida os dados bancários (accountNumber, routingNumber, name). Dados inconsistentes resultam em invalidWallet / invalidWalletData.
3. Cria a carteira e, em caso de sucesso, devolve 201 Created com o objeto completo — incluindo o id gerado (prefixo wall_), o bankName resolvido a partir do bankCode, e os links HATEOAS (_links) para ler, listar e excluir a carteira.

A carteira pertence à conta autenticada pela sua SelectKey — ela é associada ao seu merchant, retornado no objeto de resposta. Não há campo de "vendedor" ou cliente no corpo: a vinculação é automática pela chave de API.

A carteira principal (primary)

Cada conta pode ter várias carteiras, mas apenas uma é a principal (primary: true). A carteira principal é a conta usada por padrão nos saques. Ao criar uma carteira com primary: true, ela passa a ser a principal; trate qualquer carteira marcada anteriormente como principal como tendo perdido esse status.

Quando usar

• Antes do primeiro saque, para registrar a conta bancária de destino.
• Para cadastrar contas adicionais (por exemplo, alternar entre bancos).
• Para definir uma nova conta principal ao criar a carteira já com primary: true.

Não use este endpoint para alterar uma carteira existente — não há operação de atualização. Para trocar dados bancários, crie uma nova carteira e exclua a antiga (veja DeleteWallet).

Requisição

Headers

Detalhes de autenticação em Autenticação; convenções gerais (camelCase, IDs opacos, datas UTC) em Convenções.

Corpo

Exemplo curl

curl -X POST https://api.selectwin.io/v1/wallets \
  -H "SelectKey: sl_live_aBcDeFgHiJkLmNoPqRsTuVwXyZ" \
  -H "Content-Type: application/json" \
  -H "X-Idempotency-Key: 9f1c2b3a-..." \
  -d '{
    "bankCode": "001",
    "accountNumber": "12345-6",
    "routingNumber": "0001",
    "name": "João Silva",
    "primary": true
  }'

Exemplo de corpo JSON

{
  "bankCode": "001",
  "accountNumber": "12345-6",
  "routingNumber": "0001",
  "name": "João Silva",
  "primary": true
}

Resposta

Sucesso (201 Created)

{
  "id": "wall_01hqzvabc",
  "name": "Conta principal",
  "bankName": "Nubank",
  "bankCode": "260",
  "holderName": "João Santos",
  "routingNumber": "0001",
  "accountNumber": "12345678",
  "accountType": "checking",
  "primary": true,
  "enabled": true,
  "updatedAt": "2026-04-12T17:56:33.000Z",
  "createdAt": "2026-04-12T17:56:33.000Z",
  "merchant": {
    "name": "Seller Name",
    "merchantId": "bus_1234567890",
    "isSubAccount": false
  },
  "_links": {
    "self": {
      "href": "https://api.selectwin.io/v1/wallets/wall_01hqzvabc",
      "method": "GET",
      "description": "Read a wallet."
    },
    "create": {
      "href": "https://api.selectwin.io/v1/wallets",
      "method": "POST",
      "description": "Create a new wallet."
    },
    "delete": {
      "href": "https://api.selectwin.io/v1/wallets/wall_01hqzvabc",
      "method": "DELETE",
      "description": "Delete the wallet."
    },
    "list": {
      "href": "https://api.selectwin.io/v1/wallets",
      "method": "GET",
      "description": "List all wallets."
    }
  }
}

Campos da resposta

Os campos accountType, merchant e _links.delete/_links.list aparecem no objeto individual (create/read), mas são omitidos nas projeções leves de listagem — veja ListWallets.

Erros

Trate sempre pelo error.code, nunca pela message. Catálogo completo em Códigos de Erro; estrutura do envelope em Tratamento de Erros.

Boas práticas

1. Envie X-Idempotency-Key em cada criação. Se a resposta se perder na rede, o reenvio com a mesma chave não cria uma carteira duplicada.
2. Valide o bankCode antes de enviar. Use o código COMPE/ISPB correto; um banco não suportado retorna bankCodeNotSupported — confirme o código antes de tentar de novo.
3. Confira accountNumber com o dígito verificador. Dados bancários incorretos passam na criação mas fazem o saque falhar depois; revise agência e conta com cuidado.
4. Preencha name com o titular real da conta. Esse valor vira holderName e precisa bater com o cadastro do banco para o saque ser liquidado.
5. Use primary com intenção. Defina primary: true apenas na conta que deve ser o destino padrão; lembre que isso desloca a carteira principal anterior.
6. Guarde o id (wall_...) da resposta. Você vai precisar dele para ler, listar ou excluir a carteira, e para indicar o destino de saques.
7. Não tente "atualizar" uma carteira. Não há PUT/PATCH: para corrigir dados, crie uma nova e exclua a antiga.

Veja também

• Visão geral de Carteiras
• Ler uma carteira
• Listar carteiras
• Excluir uma carteira
• Convenções da API · Idempotência · Códigos de Erro