Criar uma carteira

Visão Geral

Este endpoint permite criar uma nova carteira (conta bancária) para um vendedor. A carteira criada poderá ser utilizada para receber valores de transações e saques.

Precauções

• Certifique-se de fornecer todos os campos obrigatórios (name, bankCode, routingNumber, accountNumber).
• O campo primary determina se esta carteira será definida como a principal. Se definido como true, qualquer outra carteira principal será automaticamente definida como secundária. A primeira carteira criada vira principal automaticamente.
• Os dados bancários fornecidos devem ser válidos e corresponder a uma conta bancária existente.
• A criação é idempotente (use a header X-Idempotency-Key) e faz dedupe: dados bancários idênticos a uma carteira já existente retornam 409 Conflict.
• O holderName é preenchido automaticamente a partir dos dados cadastrais da empresa autenticada — não é informado no corpo.
• Step-up (sessão de dashboard): Em uma sessão interativa (JWT), criar uma carteira exige autenticação recente + fator forte (TOTP/código de backup) re-provado via POST /v1/authentication/step-up; caso contrário a API retorna 401 stepUpRequired. O mesmo vale para PATCH /v1/wallets/:id/set-primary. Chamadas com API key não passam por step-up.
• Carência para saque: Uma carteira recém-criada só pode receber saque após o período de carência de segurança (padrão 24h, configurável pela plataforma) — ver Criar Saque. Os administradores da conta são notificados sempre que um destino de saque é adicionado ou alterado.

Descrição

A criação de carteiras permite configurar múltiplas contas bancárias para recebimento de valores, possibilitando maior flexibilidade na gestão financeira. Cada vendedor pode ter várias carteiras, mas apenas uma pode ser definida como principal.

Requisição

POST /v1/wallets

Parâmetros do Corpo

Exemplo de Requisição

{
  "name": "Minha Carteira Principal",
  "bankCode": "341",
  "routingNumber": "1234",
  "accountNumber": "12345678901234",
  "primary": true
}

Resposta

Sucesso (201 Created)

{
  "id": "wall_01hqzvabc",
  "name": "Minha Carteira Principal",
  "holderName": "João Santos",
  "bankName": null,
  "bankCode": "341",
  "routingNumber": "1234",
  "accountNumber": "12345678901234",
  "accountType": "checking",
  "pixKey": null,
  "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."
    },
    "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."
    }
  }
}

Atributos da Resposta

Erros Comuns

Melhores Práticas

1. Forneça nomes descritivos para facilitar a identificação das carteiras.
2. Valide os dados bancários antes de enviá-los para evitar problemas de liquidação.
3. Considere a necessidade de múltiplas carteiras, utilizando nomes claros para diferenciá-las.
4. Designe uma carteira como principal (primary: true na criação ou PATCH /set-primary) quando apropriado.
5. Armazene o ID da carteira para uso em operações subsequentes, como consultas e exclusões.