Create a hosted authorization for a bill

post/payment/{service}/v1/tenants/{tenant_id}/payments

Requires an API key

service is stripe or simulator. One payment per bill across providers and keys. The tariff supplies the hold. return_surface selects where hosted checkout returns: the developer sandbox (default) or the driver charging page for the bill's station and connector, with URLs chosen by the API. Retry this request with the same key if the outcome is unknown.

Path parameters

tenant_idintegerRequired
servicestringRequired

Headers

idempotency-keystringRequired

Request body

bill_idstringRequired
Pattern ^bill_[0-9a-f]{32}$
return_surfaceenum
Where hosted checkout returns: the developer sandbox page, or the driver charging page for this bill's station and connector (server-selected URLs).
One of developer, driver · Default "developer"
return_referencestring | null
Driver surface only: your session identifier appended to the server-selected return path (/charging/<evse>/<reference>) so the driver page can resume this session. Not a URL.
Pattern ^[A-Za-z0-9_-]{1,128}$

Returns · 201

idstringRequired
bill_idstringRequired
tenant_idintegerRequired
servicestringRequired
statusenumRequired
One of preparing, pending, authorized, captured, canceled, refund_pending, refund_failed, refunded
hold_minorintegerRequired
captured_minorintegerRequired
refunded_minorintegerRequired
currencystring
Default "USD"
payment_modeenumRequired
live only for a Stripe payment taken in live mode on a connected account, as the provider recorded it at authorization; test otherwise.
One of test, live
authorized_atstring (date-time) | null
When Stripe authorized the hold (the Charge's creation time); null before authorization and for the simulator.
next_actionobject | nullRequired

Errors

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

POST /payment/{service}/v1/tenants/{tenant_id}/payments

curl --fail-with-body -X POST "https://api.ivoracharge.com/payment/simulator/v1/tenants/1042/payments" \
  -H "Authorization: Bearer $IVORA_API_KEY" \
  -H "Idempotency-Key: order-2026-09-30-0001" \
  -H "Content-Type: application/json" \
  -d '{
  "bill_id": "bill_0123456789abcdef0123456789abcdef"
}'

Response · 201

{
  "id": "id_0123456789abcdef",
  "bill_id": "bill_0123456789abcdef",
  "tenant_id": 1042,
  "service": "simulator",
  "status": "preparing",
  "hold_minor": 1250,
  "captured_minor": 1250,
  "refunded_minor": 1250,
  "currency": "USD",
  "payment_mode": "test",
  "authorized_at": "2026-09-30T17:00:00Z",
  "next_action": {}
}

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.