VenddorDocumentação API
API atualAPI legada
Guia rápidoReferência completa
Carregando índice…
API atual/Referência completa/Carteiras de crédito

Ajustar, reembolsar e congelar

Lança crédito ou débito manual, reembolsa um pedido para a carteira e congela ou descongela.

Toda movimentação fica registrada no extrato e no log de ações do painel, com o administrador que a fez.

Ajustar o saldo

Credita ou debita o saldo com uma justificativa obrigatória. Use type para dar o sentido e envie amount sempre positivo.

POST/api/v1/admin/wallets/{user_id}/adjustAdmin

Ajuste manual

Parâmetros de caminho

user_iduuidobrigatório
Id do cliente dono da carteira.

Corpo da requisição

typestring
creditdebit
credit ou debit. Se omitido, vale o sinal de amount (positivo = crédito, negativo = débito).
amountintegerobrigatório
Valor em centavos, diferente de zero.
descriptionstringobrigatório
Motivo do ajuste. Obrigatório; fica no extrato.

Exemplo de requisição

Resposta

200Ajuste feito

Campos da resposta

messagestring
Texto fixo wallet adjusted.
transactionobject
A transação criada (campos do extrato).

Erros

StatusQuandoCorpo de exemplo
400Corpo inválido, type desconhecido, amount zero, description vazia, débito acima do saldo ou carteira congelada.{"error":"description is required for admin adjustments"}
401Sem token ou token inválido.{"error":"missing authorization header"}
403O usuário não tem manage_wallet nem manage_payments.{"error":"insufficient privileges","privilege_required_any":["manage_wallet","manage_payments"]}
403O módulo digital-wallet está desligado na loja.{"error":"module_disabled","module":"digital-wallet"}
500user_id malformado ou falha interna.{"error":"failed to adjust wallet","detail":"..."}
Sem idempotência

Repetir a chamada lança o ajuste de novo. Se a resposta se perder, confira o extrato antes de reenviar.

Reembolsar para a carteira

Credita na carteira o valor de um pedido, como reembolso em crédito da loja. A transação fica com reference_type: refund e reference_id igual ao pedido.

POST/api/v1/admin/wallets/{user_id}/refundAdmin

Reembolsa para a carteira

Parâmetros de caminho

user_iduuidobrigatório
Id do cliente dono da carteira.

Corpo da requisição

order_idstringobrigatório
Pedido de origem. Fica só como referência.
amountintegerobrigatório
Valor em centavos, maior que zero.

Exemplo de requisição

Resposta

200Crédito lançado

Campos da resposta

messagestring
refund credited to wallet.
transactionobject
A transação criada.

Erros

StatusQuandoCorpo de exemplo
400order_id ausente, amount não positivo ou carteira congelada.{"error":"order_id is required"}
401Sem token ou token inválido.{"error":"missing authorization header"}
403O usuário não tem manage_wallet nem manage_payments.{"error":"insufficient privileges","privilege_required_any":["manage_wallet","manage_payments"]}
403O módulo digital-wallet está desligado na loja.{"error":"module_disabled","module":"digital-wallet"}
O pedido não é conferido

A rota não verifica se o pedido existe, se é do cliente ou se o valor passa do total. Também não muda o status do pedido nem estorna o pagamento original: quem chama é responsável por essas conferências.

Congelar

POST/api/v1/admin/wallets/{user_id}/freezeAdmin

Congela a carteira

Parâmetros de caminho

user_iduuidobrigatório
Id do cliente dono da carteira.

Exemplo de requisição

Resposta

200Congelada

Erros

StatusQuandoCorpo de exemplo
401Sem token ou token inválido.{"error":"missing authorization header"}
403O usuário não tem manage_wallet nem manage_payments.{"error":"insufficient privileges","privilege_required_any":["manage_wallet","manage_payments"]}
403O módulo digital-wallet está desligado na loja.{"error":"module_disabled","module":"digital-wallet"}
500Cliente sem carteira (wallet not found for user ...) ou user_id malformado.{"error":"failed to freeze wallet","detail":"wallet not found for user ..."}

Descongelar

POST/api/v1/admin/wallets/{user_id}/unfreezeAdmin

Descongela a carteira

Parâmetros de caminho

user_iduuidobrigatório
Id do cliente dono da carteira.

Exemplo de requisição

Resposta

200Descongelada

Erros

StatusQuandoCorpo de exemplo
401Sem token ou token inválido.{"error":"missing authorization header"}
403O usuário não tem manage_wallet nem manage_payments.{"error":"insufficient privileges","privilege_required_any":["manage_wallet","manage_payments"]}
403O módulo digital-wallet está desligado na loja.{"error":"module_disabled","module":"digital-wallet"}
500Cliente sem carteira ou user_id malformado.{"error":"failed to unfreeze wallet","detail":"wallet not found for user ..."}

Veja também

  • Carteiras
Anterior
Consultar carteiras
Próxima
Antifraude
Nesta página
  • Ajustar o saldo
  • Exemplo de requisição
  • Resposta
  • Erros
  • Reembolsar para a carteira
  • Exemplo de requisição
  • Resposta
  • Erros
  • Congelar
  • Exemplo de requisição
  • Resposta
  • Erros
  • Descongelar
  • Exemplo de requisição
  • Resposta
  • Erros
  • Veja também
bash
curl -X POST "$BASE_URL/api/v1/admin/wallets/64a72542-ac9e-49aa-87bd-bad84fad96a5/adjust" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "credit",
    "amount": 2500,
    "description": "Compensação por atraso na entrega do pedido 1234"
  }'
bash
curl -X POST "$BASE_URL/api/v1/admin/wallets/64a72542-ac9e-49aa-87bd-bad84fad96a5/refund" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "order_id": "3f73310d-bfdd-4713-a664-305c08eda58b",
    "amount": 4990
  }'
bash
curl -X POST "$BASE_URL/api/v1/admin/wallets/64a72542-ac9e-49aa-87bd-bad84fad96a5/freeze" \
  -H "Authorization: Bearer $TOKEN"
bash
curl -X POST "$BASE_URL/api/v1/admin/wallets/64a72542-ac9e-49aa-87bd-bad84fad96a5/unfreeze" \
  -H "Authorization: Bearer $TOKEN"
json
{
  "message": "wallet adjusted",
  "transaction": {
    "id": "b761af68-16bd-4141-8183-9a56948050e5",
    "wallet_id": "19aae607-b66a-4637-b18e-6a14554e0443",
    "amount": 2500,
    "type": "credit",
    "reference_type": "admin",
    "reference_id": "",
    "description": "Compensação por atraso na entrega do pedido 1234",
    "balance_after": 3198,
    "created_at": "2026-09-17T05:28:00Z",
    "created_by": "2d3e4f5a-6b7c-4d8e-9f01-a2b3c4d5e6f7"
  }
}
json
{
  "message": "refund credited to wallet",
  "transaction": {
    "id": "b761af68-16bd-4141-8183-9a56948050e5",
    "wallet_id": "19aae607-b66a-4637-b18e-6a14554e0443",
    "amount": 4990,
    "type": "credit",
    "reference_type": "refund",
    "reference_id": "3f73310d-bfdd-4713-a664-305c08eda58b",
    "description": "",
    "balance_after": 5688,
    "created_at": "2026-09-17T05:28:00Z",
    "created_by": "system"
  }
}
json
{
  "message": "wallet frozen"
}
json
{
  "message": "wallet unfrozen"
}