Wallet

The driver's wallet: balance and withdrawable funds, the transaction ledger, the payout (withdrawal) account configuration, and payout requests. Paths are relative to the /api/v1 prefix; all routes require Authorization: Bearer {token}.

See Common errors, Driver wallet & cash debt, and Pagination for the cursor lists.

Endpoints

The /wallet/me/* routes operate on the caller's own wallet (any authenticated role); the /driver/* aliases are identical but gated to drivers. Money fields end in _usd (decimal) and are derived from integer _cents.

GET /wallet/me

The caller's balance summary. The wallet is created on first access if missing.

Response 200

{
  "balanceUSD": 124.5,
  "pendingPayoutUSD": 20.0,
  "withdrawableUSD": 104.5,
  "cashDebtUSD": 3.6,
  "cashDebtCapUSD": 20.0,
  "canGoOnline": true
}

withdrawableUSD is the balance available for payout. canGoOnline indicates whether the driver may go online.

GET /wallet/me/transactions

Cursor-paginated ledger, newest first. See Pagination → cursor-based.

Query

Response 200

{
  "items": [
    {
      "id": 88,
      "wallet_id": 4,
      "order_id": 42,
      "payout_id": null,
      "type": "ORDER_EARNING",
      "amount_cents": 1624,
      "balance_after_cents": 12450,
      "amount_usd": 16.24,
      "balance_after_usd": 124.5,
      "exchange_rate_amount": 540.043,
      "description": "Ganancia pedido #42",
      "created_at": "2026-06-26T12:40:00+00:00"
    }
  ],
  "next_cursor": "eyJpZCI6ODd9",
  "has_more": true
}

exchange_rate_amount is the BCV VES rate (Bs/USD) snapshot of the related order; null for movements without an order (PAYOUT_SENT, MANUAL_ADJUSTMENT).

GET /wallet/me/payout-config

Returns the caller's saved payout account, or null if none is configured.

Response 200

{
  "config": {
    "id": 2,
    "user_id": 7,
    "method": "PAGO_MOVIL",
    "bank_code": "0102",
    "id_number": "V12345678",
    "phone": "+584241001001",
    "account_number": null,
    "account_type": null,
    "verified_at": null,
    "created_at": "2026-06-20T10:00:00+00:00"
  }
}

config is null when the driver has not set up a payout account yet.

POST /wallet/me/payout-config

Creates or updates the payout account. PAGO_MOVIL requires bankCode, idNumber, and phone; BANK_TRANSFER requires accountNumber. If an otp is supplied it is verified against the code from POST /auth/otp/request. PUT /driver/payout-method is the driver-only alias.

Request body

Response 200 — { "config": { … } } (same shape as GET /wallet/me/payout-config).

Errors

POST /wallet/me/payouts

Requests a payout for the given amount, drawn against withdrawableUSD. POST /driver/withdrawals is the driver-only alias.

Request body

Response 200

{
  "payout": {
    "id": 9,
    "wallet_id": 4,
    "amount_cents": 2000,
    "amount_usd": 20.0,
    "method": "PAGO_MOVIL",
    "status": "PENDING",
    "created_at": "2026-06-26T13:00:00+00:00"
  }
}

Errors

GET /wallet/me/payouts

Cursor-paginated payout history, newest first. See Pagination → cursor-based.

Query

Response 200

{
  "items": [
    {
      "id": 9,
      "wallet_id": 4,
      "amount_cents": 2000,
      "amount_usd": 20.0,
      "method": "PAGO_MOVIL",
      "status": "PENDING",
      "created_at": "2026-06-26T13:00:00+00:00"
    }
  ],
  "next_cursor": "eyJpZCI6OH0",
  "has_more": false
}

Driver aliases

These behave exactly like their /wallet/me/* counterparts but are drivers only:

Examples

# Balance
curl /api/v1/wallet/me -H "Authorization: Bearer {driver_token}"

# Save a Pago Móvil payout account
curl -X POST /api/v1/wallet/me/payout-config \
  -H "Authorization: Bearer {driver_token}" \
  -H "Content-Type: application/json" \
  -d '{"method": "PAGO_MOVIL", "bankCode": "0102", "idNumber": "V12345678", "phone": "+584241001001"}'

# Request a $20 payout
curl -X POST /api/v1/wallet/me/payouts \
  -H "Authorization: Bearer {driver_token}" \
  -H "Content-Type: application/json" \
  -d '{"amountUSD": 20}'