Start Charge Session

POST/v1/sessions

Call this once the driver has picked an amount — either the full quote from Quote Charge Session, or a reduced amount if their balance doesn't cover the full quote. Atomically checks the sub-wallet balance, debits it, writes a ledger entry, and authorizes the session to start.

Auth

Authorization: Bearer <driver token> — the same token used for Quote Charge Session.

Request parameters

Field	Type	Required	Description
`chargerId`	string	Yes	The LotGrids charger the driver is at.
`connectorId`	string	Yes	Same connector you quoted against.
`driverEmail`	string	Yes	Must match the email your driver token was minted for.
`amount`	number	Yes	NGN amount to debit — the full quote, or a reduced amount the driver chose.

Example request

curl https://api.lotgrids.com/v1/sessions \
  -X POST \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{
    "chargerId": "chg_04af1c",
    "connectorId": "conn_02",
    "driverEmail": "adaeze.driver@fleetco.com",
    "amount": 12000
  }'

Example success response

200 OK
{
  "sessionId": "sess_9f3ac2e1",
  "debited": 12000,
  "remainingBalance": 0
}

This debits the driver's sub-wallet and authorizes the charger to dispense — it does not, by itself, mean the session finished successfully. If the charger later reports it dispensed less than debited (interrupted, or stopped early), LotGrids automatically credits the difference back to the driver's sub-wallet. There's nothing your app needs to call for that — it's handled server-side.

Error responses

402 insufficient_balance

{ "error": { "code": "insufficient_balance", "message": "Sub-wallet balance 8000 is less than 12000." } }

Returned even for the reduced amount the driver chose — re-quote or ask for a smaller amount.

401 token_expired

{ "error": { "code": "token_expired", "message": "Driver token expired." } }

404 driver_not_found

{ "error": { "code": "driver_not_found", "message": "adaeze.driver@fleetco.com is not a fleet driver." } }