Criar uma carteira

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.

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.

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

Parâmetro	Tipo	Obrigatório	Descrição	Exemplo
`name`	string	Sim	Nome descritivo para a carteira (4–50 caracteres)	`"Minha Carteira Principal"`
`bankCode`	string	Sim	Código do banco (1–10 caracteres)	`"341"`
`routingNumber`	string	Sim	Número da agência (1–60 caracteres)	`"1234"`
`accountNumber`	string	Sim	Número da conta (1–60 caracteres)	`"12345678901234"`
`primary`	boolean	Não	Indica se é a carteira padrão do vendedor	`true`

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

Atributo	Tipo	Descrição
`id`	string	`wall_*`
`name`	string	Nome descritivo
`holderName`	string	Titular (derivado da empresa)
`bankName`	string \| null	Nome do banco (atualmente sempre `null`)
`bankCode`	string \| null	Código do banco
`routingNumber`	string \| null	Agência
`accountNumber`	string \| null	Conta
`accountType`	string	Tipo de conta — sempre `checking`
`pixKey`	string \| null	Chave PIX (atualmente sempre `null`)
`primary`	boolean	Principal
`enabled`	boolean	Habilitada
`createdAt` / `updatedAt`	string	Timestamps
`merchant`	object	Merchant
`_links`	object	HATEOAS

Erros Comuns

Código	`code`	Descrição
400	`bankCodeNotSupported`	O código do banco informado não é suportado
409	`walletAlreadyExists`	Já existe uma carteira com os mesmos dados bancários

Melhores Práticas

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

Criar uma carteira

On this page