Docs/Carteiras

Carteiras

Crie carteiras para separar saldos e operações dentro da sua conta. Cada carteira tem seu próprio saldo — independente do saldo da empresa e das demais carteiras. Útil para organizar recebimentos por cliente, filial, produto ou parceiro sem misturar valores.

Como funciona

Saldos totalmente separados

O saldo de uma carteira nunca se mistura com o saldo da empresa nem com o de outras carteiras. Cada uma mantém seu próprio controle de entradas e saídas.

Ativação por header

Envie X-Api-Wallet em qualquer chamada para direcionar a operação à carteira. Sem o header, tudo segue para a conta principal da empresa, como hoje.

Ativação pela AurePay

A funcionalidade precisa ser habilitada pelo time da AurePay para a sua conta. Fale com o suporte para ativar.

Split direto para a carteira

No split de depósito, basta informar o ID da carteira como destino — a AurePay identifica automaticamente que é uma carteira e direciona o valor para ela.

Header `X-Api-Wallet`

O header é opcional e não diferencia maiúsculas de minúsculas — tanto X-Api-Wallet quanto x-api-wallet funcionam. Quando presente, todos os depósitos, saques e listagens passam a operar dentro daquela carteira automaticamente, sem precisar de parâmetros adicionais.

Headers com carteira

X-Api-Key: pk_live_******
X-Api-Secret: sk_live_******
X-Api-Wallet: ID_DA_CARTEIRA
Content-Type: application/json

Criar carteira

Cria uma nova carteira com saldo zerado. O campo externalId é opcional e serve para vincular a carteira ao ID do seu sistema. Se uma carteira com o mesmo externalId já existir, a API devolve a existente em vez de criar uma duplicata.

POST /v1/wallets

curl -X POST "https://api.aurepay.com.br/v1/wallets" \
  -H "X-Api-Key: pk_live_******" \
  -H "X-Api-Secret: sk_live_******" \
  -H "Content-Type: application/json" \
  -d '{"name":"Carteira A","externalId":"conta_001"}'

Body

{
  "name": "Carteira A",
  "externalId": "conta_001"
}

Resposta (201)

{
  "success": true,
  "data": {
    "id": "ID_DA_CARTEIRA",
    "name": "Carteira A",
    "externalId": "conta_001",
    "status": "enabled",
    "balance": {
      "total": 0,
      "available": 0,
      "blocked": 0
    },
    "createdAt": "2025-01-01T00:00:00.000Z"
  }
}

Carteiras com verificação (KYC)

Quando a conta está em modo kyc, a criação exige taxId (CNPJ), email e phone. A API envia o convite de verificação e devolve onboardingUrl. Operações com X-Api-Wallet só são aceitas após verification.status = approved (carteiras legadas sem verificação continuam operáveis). Erros: WALLET_KYC_NOT_APPROVED e WALLET_KYC_REJECTED_TERMINAL.

POST /v1/wallets (KYC)

curl -X POST "https://api.aurepay.com.br/v1/wallets" \
  -H "X-Api-Key: pk_live_******" \
  -H "X-Api-Secret: sk_live_******" \
  -H "Content-Type: application/json" \
  -d '{"name":"Empresa XPTO","taxId":"00000000000100","email":"contato@empresaxpto.com.br","phone":"11999999999"}'

Body KYC

{
  "name": "Empresa XPTO",
  "taxId": "00.000.000/0001-00",
  "email": "contato@empresaxpto.com.br",
  "phone": "(11) 99999-9999",
  "externalId": "opcional"
}

POST /v1/wallets/{id}/verification/resend

curl -X POST "https://api.aurepay.com.br/v1/wallets/ID_DA_CARTEIRA/verification/resend" \
  -H "X-Api-Key: pk_live_******" \
  -H "X-Api-Secret: sk_live_******" \
  -H "Content-Type: application/json" \
  -d '{"email":"contato@empresaxpto.com.br"}'

Listar carteiras

Retorna as carteiras ativas da sua conta. Para ver carteiras arquivadas, use o filtro ?status=disabled. Suporta paginação via ?page e ?limit.

GET /v1/wallets

curl -X GET "https://api.aurepay.com.br/v1/wallets" \
  -H "X-Api-Key: pk_live_******" \
  -H "X-Api-Secret: sk_live_******"

Resposta (200)

{
  "success": true,
  "data": {
    "items": [
      {
        "id": "ID_DA_CARTEIRA",
        "name": "Carteira A",
        "externalId": "conta_001",
        "status": "enabled",
        "balance": {
          "total": 150000,
          "available": 150000,
          "blocked": 0
        }
      }
    ],
    "total": 1,
    "page": 1,
    "limit": 20
  }
}

Detalhe da carteira

GET /v1/wallets/{id}

curl -X GET "https://api.aurepay.com.br/v1/wallets/ID_DA_CARTEIRA" \
  -H "X-Api-Key: pk_live_******" \
  -H "X-Api-Secret: sk_live_******"

Saldo da carteira

Retorna o saldo disponível da carteira, lido direto do banco — sem cache. Útil para verificar o saldo atualizado antes de criar um saque ou tomar uma decisão de negócio.

GET /v1/wallets/{id}/balance

curl -X GET "https://api.aurepay.com.br/v1/wallets/ID_DA_CARTEIRA/balance" \
  -H "X-Api-Key: pk_live_******" \
  -H "X-Api-Secret: sk_live_******"

Resposta (200)

{
  "success": true,
  "data": {
    "balance": {
      "total": 150000,
      "available": 150000,
      "blocked": 0
    },
    "currency": "brl"
  }
}

Editar carteira

Atualiza o nome, o ID externo, os bloqueios de depósito/saque ou os metadados da carteira. Também reativa uma carteira arquivada — basta enviar "status": "enabled".

PATCH /v1/wallets/{id}

curl -X PATCH "https://api.aurepay.com.br/v1/wallets/ID_DA_CARTEIRA" \
  -H "X-Api-Key: pk_live_******" \
  -H "X-Api-Secret: sk_live_******" \
  -H "Content-Type: application/json" \
  -d '{"name":"Novo nome"}'

Arquivar carteira

Arquiva a carteira. Uma carteira arquivada sai da listagem padrão e deixa de aceitar operações via X-Api-Wallet. Para arquivar, o saldo disponível e o saldo bloqueado precisam estar zerados em todas as moedas — isso garante que não há nenhuma operação em andamento (saque pendente, chargeback, etc.).

Erro WALLET_HAS_BALANCE (409): a carteira ainda tem saldo disponível ou valores bloqueados. Saque ou transfira o saldo antes de arquivar.

DELETE /v1/wallets/{id}

curl -X DELETE "https://api.aurepay.com.br/v1/wallets/ID_DA_CARTEIRA" \
  -H "X-Api-Key: pk_live_******" \
  -H "X-Api-Secret: sk_live_******"

Escopo automático nas listagens

Ao enviar X-Api-Wallet, os endpoints de depósitos, saques, transações e chargebacks retornam automaticamente apenas os registros daquela carteira. Não há parâmetro de URL adicional — o header é suficiente. O campo wallet também aparece no payload de cada pagamento e nos webhooks, para facilitar a conciliação.

Listagem escopada à carteira

curl -X GET "https://api.aurepay.com.br/v1/deposits" \
  -H "X-Api-Key: pk_live_******" \
  -H "X-Api-Secret: sk_live_******" \
  -H "X-Api-Wallet: ID_DA_CARTEIRA"

Split de depósito com carteiras

No campo splits do depósito, envie apenas { id, percent } — o mesmo formato de hoje. A AurePay identifica automaticamente o destino pelo ID informado:

ID de uma carteira da sua conta → o valor vai direto para o saldo daquela carteira, sem passar pela conta principal.
ID da própria conta (em depósito feito via X-Api-Wallet) → o valor vai para o saldo geral da empresa, saindo da carteira.
ID de outra empresa → repasse normal de split, igual ao comportamento atual.

Ver documentação de split de pagamentos →