Carteiras (Wallet)

O canal do WhatsApp Oficial é pré-pago: cada conta conectada tem uma carteira, criada automaticamente, de onde sai o custo das conversas. Sem saldo, os envios falham. Todas as operações usam POST /api/v1/message/SendCommand com content.type: "WALLET", variando o commandType. A resposta síncrona é sempre { "packageId": "..." }; o resultado chega no webhook do canal de feedback. Use correlationId para correlacionar.

`commandType`	Operação	Webhook de resposta
`LIST`	Lista as carteiras da conta	`WALLET_LIST_RESPONSE`
`BALANCE`	Consulta o saldo	`WALLET_BALANCE_RESPONSE`
`ADD_FUND`	Gera link de pagamento para adicionar créditos	`WALLET_ADD_FUND_RESPONSE`
`TRANSACTIONS`	Extrato de transações	`WALLET_TRANSACTIONS_RESPONSE`
`CREDIT`	Crédito administrativo (sem pagamento)	`WALLET_CREDIT_RESPONSE`

Objeto `wallet`

Presente nas respostas:

Campo	Tipo	Descrição
`id`	uuid	Identificador da carteira
`balance`	number	Saldo atual
`currency`	string	Moeda (ex.: `BRL`)
`name`	string	Nome (ex.: `Principal`)
`isDefault`	boolean	Carteira padrão da conta
`createdAt` / `updatedAt`	datetime	Datas de criação/atualização

Listar carteiras

{
  "channelId": "uuid-do-canal-oficial",
  "correlationId": "listar-carteiras-01",
  "content": { "type": "WALLET", "commandType": "LIST" }
}

Webhook:

{
  "correlationId": "listar-carteiras-01",
  "content": {
    "type": "WALLET_LIST_RESPONSE",
    "commandType": "WALLET_LIST_RESPONSE",
    "success": true,
    "count": 1,
    "wallets": [
      {
        "id": "1eed9c1d-9977-4d91-810e-1819087ca8b6",
        "balance": 0,
        "currency": "BRL",
        "name": "Principal",
        "isDefault": true,
        "createdAt": "2026-07-06T22:52:29.423565+00:00"
      }
    ]
  }
}

Consultar saldo

{
  "channelId": "uuid-do-canal-oficial",
  "correlationId": "saldo-01",
  "content": { "type": "WALLET", "commandType": "BALANCE" }
}

Webhook: WALLET_BALANCE_RESPONSE com o objeto wallet (mesmos campos acima).

Adicionar fundos

Gera um link de checkout para pagamento; após pagar, o crédito entra na carteira.

{
  "channelId": "uuid-do-canal-oficial",
  "correlationId": "fundos-01",
  "content": {
    "type": "WALLET",
    "commandType": "ADD_FUND",
    "walletId": "1eed9c1d-9977-4d91-810e-1819087ca8b6",
    "amount": 50,
    "callbackUrl": "https://suaempresa.com.br/funds-added"
  }
}

uuid

required

Id da carteira (obtenha com LIST).

number

required

Valor a adicionar, na moeda da carteira.

string

required

URL para onde o pagador é redirecionado após concluir o pagamento.

Webhook:

{
  "correlationId": "fundos-01",
  "content": {
    "type": "WALLET_ADD_FUND_RESPONSE",
    "commandType": "WALLET_ADD_FUND_RESPONSE",
    "success": true,
    "link": "https://metaguru.../checkout?state=...",
    "fundRequestId": "0023817d-6f5d-4c0d-86ab-e7f0c7e2de49"
  }
}

Entregue o link a quem vai pagar.

Extrato (transações)

{
  "channelId": "uuid-do-canal-oficial",
  "correlationId": "extrato-01",
  "content": { "type": "WALLET", "commandType": "TRANSACTIONS" }
}

Webhook:

{
  "correlationId": "extrato-01",
  "content": {
    "type": "WALLET_TRANSACTIONS_RESPONSE",
    "commandType": "WALLET_TRANSACTIONS_RESPONSE",
    "success": true,
    "count": 1,
    "transactions": [
      {
        "id": "428d7e3b-7a19-4e4e-916d-9959aea8f976",
        "walletId": "1eed9c1d-9977-4d91-810e-1819087ca8b6",
        "type": "Credit",
        "amount": 5,
        "description": "Adição de Crédito",
        "referenceId": "25adeb56-5384-4f7c-b987-55385dead5ac",
        "createdAt": "2026-07-08T19:29:45.758302+00:00",
        "wallet": { "id": "1eed9c1d-9977-4d91-810e-1819087ca8b6", "balance": 10, "currency": "BRL", "name": "Principal", "isDefault": true }
      }
    ]
  }
}

Crédito administrativo

CREDIT credita a carteira sem passar por pagamento. É uma operação administrativa, restrita a fluxos internos/autorizados:

{
  "channelId": "uuid-do-canal-oficial",
  "correlationId": "credito-admin-01",
  "content": {
    "type": "WALLET",
    "commandType": "CREDIT",
    "walletId": "1eed9c1d-9977-4d91-810e-1819087ca8b6",
    "amount": 5
  }
}

Webhook: WALLET_CREDIT_RESPONSE com success e message.

Em caso de erro em qualquer operação, o webhook chega com success: false e o campo error preenchido (o type pode vir como WALLET_RESPONSE quando a operação não é reconhecida).

Início

Contas

API Keys

Canais

WhatsApp Oficial

Tipos de Mensagem

Operações de Mensagem

Sessão e Conexão

Consultas

Interação

Carteiras (Wallet)

Carteiras (Wallet)

Objeto `wallet`

Listar carteiras

Consultar saldo

Adicionar fundos

Extrato (transações)

Crédito administrativo

​Carteiras (Wallet)

​Objeto wallet

​Listar carteiras

​Consultar saldo

​Adicionar fundos

​Extrato (transações)

​Crédito administrativo

Carteiras (Wallet)

Objeto `wallet`

Listar carteiras

Consultar saldo

Adicionar fundos

Extrato (transações)

Crédito administrativo