Wallet

The driver's wallet: balance and withdrawable funds, the transaction ledger, the payout account configuration, and settlement receipts (liquidaciones). 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": 100.9,
  "cashDebtUSD": 3.6,
  "cashDebtCapUSD": 20.0,
  "canGoOnline": true
}

withdrawableUSD is the balance available for payout, calculated as max(0, balanceUSD - pendingPayoutUSD - cashDebtUSD). Any outstanding cash debt (cashDebtUSD) is deducted so drivers must settle collected cash before withdrawing. 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,
      "type": "ORDER_EARNING",
      "direction": "CREDIT",
      "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, PROMO_BONUS). direction is CREDIT (adds to the balance) or DEBIT (subtracts from it).

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,
    "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

GET /wallet/me/settlements

Cursor-paginated list of the caller's own settlement receipts (liquidaciones), newest first. Scoped to the authenticated driver; a caller with no driver profile gets an empty page. See Pagination → cursor-based.

Query

Response 200

{
  "items": [
    {
      "id": 12,
      "receipt_number": "2026-0000042",
      "fiscal_period": "2026-07",
      "status": "PAID",
      "cutoff_from": "2026-07-24T06:00:00+00:00",
      "cutoff_to": "2026-07-31T06:00:00+00:00",
      "issued_at": "2026-07-31T06:00:00+00:00",
      "net_usd": 85.0,
      "payable_usd": 85.0,
      "total_paid_bs_cents": 340000,
      "paid_at": "2026-07-31T14:05:00+00:00",
      "created_at": "2026-07-31T06:00:00+00:00"
    }
  ],
  "next_cursor": "eyJpZCI6MTF9",
  "has_more": true
}

Money: net_usd/payable_usd are USD (decimal); total_paid_bs_cents is the amount paid in bolívares (integer cents, i.e. Bs ×100).

GET /wallet/me/settlements/{id}

A single settlement receipt owned by the caller, with its lines. Each line has a type: ORDER (a settled order earning, order_id set) or ADJUSTMENT (a settled manual wallet movement, order_id null). Another driver's — or a nonexistent — receipt returns 404 (it is invisible to the caller).

Response 200

{
  "settlement": {
    "id": 12,
    "receipt_number": "2026-0000042",
    "fiscal_period": "2026-07",
    "status": "PAID",
    "cutoff_from": "2026-07-24T06:00:00+00:00",
    "cutoff_to": "2026-07-31T06:00:00+00:00",
    "issued_at": "2026-07-31T06:00:00+00:00",
    "net_usd": 85.0,
    "payable_usd": 85.0,
    "total_paid_bs_cents": 340000,
    "paid_at": "2026-07-31T14:05:00+00:00",
    "created_at": "2026-07-31T06:00:00+00:00",
    "payout_method": "PAGO_MOVIL",
    "subtotal_usd": 100.0,
    "commission_usd": -15.0,
    "iva_prc": "16.00",
    "net_bs_cents": 340000,
    "lines": [
      {
        "line_number": 1,
        "type": "ORDER",
        "order_id": 512,
        "order_date": "2026-07-25",
        "description": "Orden #512",
        "net_usd": 42.5,
        "exchange_rate_amount": "40.000",
        "total_bs_cents": 170000
      },
      {
        "line_number": 2,
        "type": "ADJUSTMENT",
        "order_id": null,
        "order_date": "2026-07-28",
        "description": "credit manual: bono",
        "net_usd": 50.0,
        "exchange_rate_amount": "42.000",
        "total_bs_cents": 210000
      }
    ]
  }
}

Bs fields (total_paid_bs_cents, net_bs_cents, total_bs_cents) are integer bolívares cents. commission_usd is negative (Agüita's commission on the line). A line's type is ORDER or ADJUSTMENT; on ADJUSTMENT lines order_id is null and net_usd/total_bs_cents may be negative.

Errors

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"}'