Excluir uma carteira

Remove permanentemente uma carteira (conta bancária) cadastrada para recebimentos e saques. Use quando uma conta não será mais usada como destino de liquidação. A operação é irreversível e exige que não haja saques (withdrawals) pendentes vinculados à carteira.

DELETE /v1/wallets/{walletId}

Como funciona

Uma carteira representa uma conta bancária para a qual a Selectwin envia os valores das suas vendas (liquidações e saques). Excluir uma carteira a remove definitivamente da sua conta — ela deixa de aparecer em listagens e não pode mais ser usada como destino de saque.

O que o servidor faz ao receber o DELETE:

1. Valida o formato do walletId (wall_...). Se for malformado, retorna walletIdIsInvalid (400).
2. Localiza a carteira dentro do escopo da sua SelectKey. Você só pode excluir carteiras do próprio vendedor autenticado; se não existir nesse escopo, retorna walletNotFound (404).
3. Verifica se a carteira pode ser removida. Se houver saques pendentes ou outra dependência que impeça a remoção, a API recusa com bankAccountNotDeletable (422) — a carteira não é excluída.
4. Remove a carteira e dispara o webhook wallet.deleted.

A exclusão é síncrona: quando você recebe 200 OK com deleted: true, a carteira já não existe. Diferente de criar ou ler, a resposta de exclusão não traz os dados bancários — apenas uma confirmação enxuta (id, resource, deleted) mais merchant e _links.

Quando usar (e quando não usar)

Use quando uma conta bancária foi encerrada, substituída ou cadastrada por engano e você quer mantê-la fora das suas listagens e fora do alcance de saques.

Não use se:

• Você só quer trocar a conta padrão. Para isso, defina outra carteira como principal (primary: true) ao criá-la — veja Criar Carteira — sem precisar excluir a antiga.
• Há saques em andamento para essa carteira. Aguarde a liquidação; a API recusará a exclusão enquanto houver pendências.
• Você apenas quer pausar temporariamente o uso. Nesse caso, prefira manter a carteira e direcionar os saques para outra conta, em vez de excluir e recadastrar depois.

Requisição

Headers

Não há corpo nesta requisição, portanto Content-Type é dispensável. Por se tratar de uma operação destrutiva e idempotente por natureza (excluir algo já excluído resulta em walletNotFound), você pode incluir um X-Idempotency-Key em pipelines automatizados — veja Idempotência.

Parâmetros de caminho

Exemplo (curl)

curl -X DELETE "https://api.selectwin.io/v1/wallets/wall_01hqzvabc" \
  -H "SelectKey: sl_live_aBcDeFgHiJkLmNoPqRsTuVwXyZ"

Resposta

Sucesso (200 OK)

{
  "id": "wall_01hqzvabc",
  "resource": "wallet",
  "deleted": true,
  "merchant": {
    "name": "Seller Name",
    "merchantId": "bus_1234567890",
    "isSubAccount": false
  },
  "_links": {
    "self": {
      "href": "https://api.selectwin.io/v1/wallets/wall_01hqzvabc",
      "method": "DELETE",
      "description": "Delete the wallet."
    },
    "create": {
      "href": "https://api.selectwin.io/v1/wallets",
      "method": "POST",
      "description": "Create a new wallet."
    },
    "list": {
      "href": "https://api.selectwin.io/v1/wallets",
      "method": "GET",
      "description": "List all wallets."
    }
  }
}

Campos da resposta

Erros

Trate sempre pelo error.code, nunca pela message — veja o Catálogo de Códigos de Erro.

Como excluir é idempotente do ponto de vista do resultado, uma segunda chamada com o mesmo walletId retorna walletNotFound (404) — sinal de que a carteira já não existe, não necessariamente uma falha a ser tratada como erro.

Boas práticas

1. Confirme com o usuário antes de chamar o endpoint. Como a operação é irreversível, exiba uma confirmação explícita na sua interface antes de disparar o DELETE.
2. Trate bankAccountNotDeletable (422) como bloqueio temporário. Em vez de insistir, verifique saques pendentes para a carteira (veja Withdrawals) e tente novamente após a liquidação.
3. Não exclua a carteira principal sem ter uma substituta. Se a primary for removida, garanta que outra carteira esteja marcada como principal para não deixar as liquidações sem destino.
4. Trate walletNotFound (404) como sucesso silencioso em reprocessamentos. Se um retry retornar 404, a carteira já foi excluída — não é preciso alarmar o usuário.
5. Reaja ao webhook wallet.deleted para sincronizar seu próprio cadastro, em vez de assumir o estado apenas pela resposta HTTP. Nunca faça polling — veja Proibição de Polling.
6. Considere desabilitar antes de excluir. Se a sua operação tolera, mantenha a carteira fora de uso por um período antes da exclusão definitiva, como margem de segurança contra remoções acidentais.

Veja também

• Visão Geral de Carteiras — o recurso, o objeto e seu ciclo de vida.
• Criar Carteira — cadastrar uma nova conta bancária (gera novo wall_...).
• Consultar Carteira — conferir os dados antes de excluir.
• Listar Carteiras — descobrir quais carteiras existem.
• Tratamento de Erros e Catálogo de Códigos de Erro.