Create an externally funded charging session

post/v1/tenants/{tenant_id}/charging-sessions

Requires an API key

Requires billing:write and settlement:write. Atomically snapshots the tariff and fixes external settlement ownership. Your backend owns checkout, processor credentials and capture. References contain no secrets. One open physical external session per connector; this does not reserve hardware against other CSMS commands.

Path parameters

tenant_idintegerRequired

Headers

idempotency-keystringRequired

Request body

station_idintegerRequired
Greater than 0
connector_idintegerRequired
Greater than 0
tariff_idintegerRequired
Tenant-owned tariff, snapshotted before charging
Greater than 0
sourceenum
One of csms, simulated · Default "csms"
application_referencestringRequired
Unique booking/session reference within your tenant. No customer data or secrets.
Pattern ^[A-Za-z0-9][A-Za-z0-9_.:/-]{0,127}$
processorstringRequired
Descriptive payment integration name. No adapter is called.
Pattern ^[a-z][a-z0-9-]{0,31}$
merchant_referencestringRequired
Your non-secret processor account reference.
Pattern ^[A-Za-z0-9][A-Za-z0-9_.:/-]{0,127}$
payment_referencestringRequired
Stable external payment reference, unique per tenant, processor and merchant.
Pattern ^[A-Za-z0-9][A-Za-z0-9_.:/-]{0,127}$

Returns · 201

idstringRequired
tenant_idintegerRequired
application_referencestringRequired
processorstringRequired
merchant_referencestringRequired
payment_referencestringRequired
created_bystringRequired
created_atstringRequired
settlement_ownerstring
Default "external"
statusenumRequired
One of prepared, starting, charging, stopping, awaiting_bill, completed, canceled, reconciliation_required
billBillRecordRequired
Child attributes
- idstringRequired
- tenant_idintegerRequired
- station_idintegerRequired
- connector_idintegerRequired
- sourceenumRequired
  One of csms, simulated
- tariff_idintegerRequired
- rate_minorstringRequired
- hold_minorintegerRequired
- currencystringRequired
- charging_tokenstringRequired
- statusenumRequired
  One of open, final
- energy_kwhstring | nullRequired
- energy_whinteger | null
  Integer Wh of the finalized usage.
- total_minorinteger | nullRequired
- transaction_idinteger | nullRequired
- created_atstringRequired
- finalized_atstring | nullRequired
- settlement_ownerenum
  One of managed, external · Default "managed"
- billing_versionstring
  Default "energy-v1"
- usageobject | null
  Single bill reads only: live matched usage after start, a final snapshot once final.
  Child attributes
  - transaction_idinteger | nullRequired
    Physical transaction resource ID; null for simulated bills.
  - activebooleanRequired
  - energy_kwhstring | nullRequired
    Decimal kWh string for display.
  - energy_whinteger | nullRequired
    Integer Wh for arithmetic.
  - estimated_minorinteger | nullRequired
    Integer minor units. On final bills this equals total_minor.
  - started_atstring | nullRequired
  - ended_atstring | nullRequired
  - power_winteger | null
    Latest reported charging power in watts; 0 once the transaction ended; null when the charger reports none.
  - soc_percentinteger | null
    Latest reported vehicle state of charge, when the charger reports it.
  - metered_atstring | null
    Timestamp of the meter sample behind power_w/soc_percent.
- start_operationobject | null
  Single bill reads only: the journaled start dispatch, if any.
  Child attributes
  - idstringRequired
  - tenant_idintegerRequired
  - statusenumRequired
    One of dispatching, succeeded, rejected, unknown
  - resultobject | nullRequired
  - created_atstringRequired
  - updated_atstringRequired
usageobject | nullRequired
Live matched usage while charging; a final snapshot once completed. Null before a transaction is observed and on canceled sessions.
Child attributes
- transaction_idinteger | nullRequired
  Physical transaction resource ID; null for simulated bills.
- activebooleanRequired
- energy_kwhstring | nullRequired
  Decimal kWh string for display.
- energy_whinteger | nullRequired
  Integer Wh for arithmetic.
- estimated_minorinteger | nullRequired
  Integer minor units. On final bills this equals total_minor.
- started_atstring | nullRequired
- ended_atstring | nullRequired
- power_winteger | null
  Latest reported charging power in watts; 0 once the transaction ended; null when the charger reports none.
- soc_percentinteger | null
  Latest reported vehicle state of charge, when the charger reports it.
- metered_atstring | null
  Timestamp of the meter sample behind power_w/soc_percent.
start_operationobject | nullRequired
Child attributes
- idstringRequired
- tenant_idintegerRequired
- statusenumRequired
  One of dispatching, succeeded, rejected, unknown
- resultobject | nullRequired
- created_atstringRequired
- updated_atstringRequired
stop_operationobject | nullRequired
Child attributes
- idstringRequired
- tenant_idintegerRequired
- statusenumRequired
  One of dispatching, succeeded, rejected, unknown
- resultobject | nullRequired
- created_atstringRequired
- updated_atstringRequired
settlementSettlementSummaryRequired
Child attributes
- verificationstring
  Default "application_reported"
- captured_minorintegerRequired
- refunded_minorintegerRequired
- net_minorintegerRequired
- uncollected_minorinteger | nullRequired
- statusenumRequired
  One of unreported, pending, unknown, failed, reported_unpaid, reported_partial, reported_paid, reported_refunded, reported_released

Errors

401 Unauthorized 403 Forbidden 404 Not found 409 Conflict 422 Invalid request 429 Rate limited 502 Upstream error 503 Unavailable

POST /v1/tenants/{tenant_id}/charging-sessions

curl --fail-with-body -X POST "https://api.ivoracharge.com/v1/tenants/1042/charging-sessions" \
  -H "Authorization: Bearer $IVORA_API_KEY" \
  -H "Idempotency-Key: order-2026-09-30-0001" \
  -H "Content-Type: application/json" \
  -d '{
  "station_id": 1,
  "connector_id": 1,
  "tariff_id": 42,
  "application_reference": "string",
  "processor": "string",
  "merchant_reference": "string",
  "payment_reference": "string"
}'

Response · 201

{
  "id": "id_0123456789abcdef",
  "tenant_id": 1042,
  "application_reference": "string",
  "processor": "string",
  "merchant_reference": "string",
  "payment_reference": "string",
  "created_by": "string",
  "created_at": "2026-09-30T17:00:00Z",
  "settlement_owner": "external",
  "status": "prepared",
  "bill": {
    "id": "id_0123456789abcdef",
    "tenant_id": 1042,
    "station_id": 1,
    "connector_id": 1,
    "source": "csms",
    "tariff_id": 42,
    "rate_minor": "string",
    "hold_minor": 1250,
    "currency": "USD",
    "charging_token": "string",
    "status": "open",
    "energy_kwh": "string",
    "energy_wh": 7500,
    "total_minor": 1250,
    "transaction_id": 1,
    "created_at": "2026-09-30T17:00:00Z",
    "finalized_at": "2026-09-30T17:00:00Z",
    "settlement_owner": "managed",
    "billing_version": "energy-v1",
    "usage": {
      "transaction_id": 1,
      "active": false,
      "energy_kwh": "string",
      "energy_wh": 7500,
      "estimated_minor": 1250,
      "started_at": "2026-09-30T17:00:00Z",
      "ended_at": "2026-09-30T17:00:00Z",
      "power_w": 1,
      "soc_percent": 1,
      "metered_at": "2026-09-30T17:00:00Z"
    },
    "start_operation": {
      "id": "id_0123456789abcdef",
      "tenant_id": 1042,
      "status": "dispatching",
      "result": {},
      "created_at": "2026-09-30T17:00:00Z",
      "updated_at": "2026-09-30T17:00:00Z"
    }
  },
  "usage": {
    "transaction_id": 1,
    "active": false,
    "energy_kwh": "string",
    "energy_wh": 7500,
    "estimated_minor": 1250,
    "started_at": "2026-09-30T17:00:00Z",
    "ended_at": "2026-09-30T17:00:00Z",
    "power_w": 1,
    "soc_percent": 1,
    "metered_at": "2026-09-30T17:00:00Z"
  },
  "start_operation": {
    "id": "id_0123456789abcdef",
    "tenant_id": 1042,
    "status": "dispatching",
    "result": {},
    "created_at": "2026-09-30T17:00:00Z",
    "updated_at": "2026-09-30T17:00:00Z"
  },
  "stop_operation": {
    "id": "id_0123456789abcdef",
    "tenant_id": 1042,
    "status": "dispatching",
    "result": {},
    "created_at": "2026-09-30T17:00:00Z",
    "updated_at": "2026-09-30T17:00:00Z"
  },
  "settlement": {
    "verification": "application_reported",
    "captured_minor": 1250,
    "refunded_minor": 1250,
    "net_minor": 1250,
    "uncollected_minor": 1250,
    "status": "unreported"
  }
}

Try it is not available here yetRequests from this page are off until the production API at https://api.ivoracharge.com is public. Use the code samples from your application server; Ivora grants production access. Keys are created in Developer tools.