Skip to main content

Charge Orchestration

The Charges microservice acts as the orchestrator between the Financial Gateway (Pagar.me V5) and the OCPP hardware Gateway. We implemented the Pre-Authorization with Late Capture (Auth and Capture) pattern, ensuring the driver only pays for the energy value (kWh) actually transferred to the electric vehicle.

Start Charging Session​

Initiates the financial authorization flow. The API supports traditional methods and Wallets (Apple Pay and Google Pay) for maximum security (PCI-DSS).

POST /charge/start

Request Body (StartChargeDto)
{
  "stationId": 10,
  "chargePointId": "EVSE-001",
  "connectorId": 1,
  "method": "CREDIT_CARD",
  "amount": 5000,
  "email": "driver@company.com",
  "cpf": "12345678900",
  "cardToken": "tok_123456789",
  "saveCard": true,
  "charger": {
    "price": 1.50,
    "fixed_connection_cost": 2.00
  }
}

Payload Details​

  • chargePointId: Unique identifier of the equipment (e.g., EVSE-001).
  • method: PIX, CREDIT_CARD, WALLET, VIP, GOOGLE_PAY or APPLE_PAY.
  • amount: Pre-authorization amount in cents (e.g., 5000 = R$ 50.00).
  • networkToken: Encrypted payload returned by Apple Pay / Google Pay.
Success Response (200 OK)
{
  "success": true,
  "sessionId": "abc123xyz-firestore-id",
  "paymentData": {
    "orderId": "or_12345",
    "chargeId": "ch_12345",
    "status": "pending",
    "pixQrCode": null,
    "pixExpiresAt": null
  }
}

Stop Charging Session​

If the charging is in progress (CHARGING), the command is routed to the hardware via OCPP. If it is in pre-authorization, the financial order is canceled immediately (Void).

POST /charge/stop

Request Body
{
  "sessionId": "abc123xyz-firestore-id"
}

Asynchronous Financial Flow​

The architecture guarantees financial accuracy through routines managed by BullMQ:

  1. Dynamic Capture: At the end of the recharge, if the consumption is lower than the pre-authorization, a partial capture is requested.
  2. Refunds Queue: In case of error, it makes progressive attempts to guarantee the refund.
  3. Receipts Queue: Generates and sends the detailed fiscal receipt by email.