Skip to main content

Digital Wallet Management (Wallet)

The Wallet module manages the digital balance (Closed-Loop) of drivers. The wallet is created automatically (Lazy Creation) the moment the user queries it or attempts to deposit funds for the first time.

Balance Inquiry​

Retrieves the updated balance and wallet status of the authenticated user.

GET /wallet

Success Response (200 OK)
{
  "id": "uuid-1234-5678",
  "balance": 15050,
  "currency": "BRL",
  "status": "active",
  "lastTransactionId": "ch_987654321"
}

Add Funds (Top-up)​

Generates a deposit intent in the wallet. The system creates an isolated order in Pagar.me and returns the payment details (e.g., PIX QR Code).

POST /wallet/add-funds

Request Body (AddFundsDto)
{
  "amount": 5000,
  "payment_method": "pix"
}
Success Response (201 Created)
{
  "id": 102,
  "status": "pending",
  "amount": 5000,
  "pagarmeChargeId": "ch_123456",
  "paymentDetails": {
    "pixQrCode": "00020101021243650014br.gov.bcb.pix...",
    "pixQrCodeUrl": "https://api.pagar.me/core/v5/transactions/qr_code/..."
  }
}

Retention and Debit Rules​

The debit is strictly performed by the ChargeService at the moment the charging session reports the final energy consumption via OCPP.