# Get Billing Details Source: https://docs.cariqa.com/api-reference/billing-details/get-billing-details /openapi.yaml get /api/v1/users/{user_id}/billing-details/ Retrieve billing details of the user # Update Billing Details Source: https://docs.cariqa.com/api-reference/billing-details/update-billing-details /openapi.yaml put /api/v1/users/{user_id}/billing-details/ Update billing details of the user # Get Charging Session Source: https://docs.cariqa.com/api-reference/charging-sessions/get-charging-session /openapi.yaml get /api/v1/users/{user_id}/charging-sessions/{session_id}/ Retrieve charging session of the user # List Charging Sessions Source: https://docs.cariqa.com/api-reference/charging-sessions/list-charging-sessions /openapi.yaml get /api/v1/users/{user_id}/charging-sessions/ Retrieve list of user charging sessions # Rate charging session Source: https://docs.cariqa.com/api-reference/charging-sessions/rate-charging-session /openapi.yaml patch /api/v1/users/{user_id}/charging-sessions/{session_id}/ Rate charging session # Start Charging Session Source: https://docs.cariqa.com/api-reference/charging-sessions/start-charging-session /openapi.yaml post /api/v1/users/{user_id}/charging/start/ Start charging session synchronously # Stop Charging Session Source: https://docs.cariqa.com/api-reference/charging-sessions/stop-charging-session /openapi.yaml post /api/v1/users/{user_id}/charging/stop/{session_id}/ Stop charging session # List Charging Debts Source: https://docs.cariqa.com/api-reference/debts/list-charging-debts /openapi.yaml get /api/v1/users/{user_id}/charging/debts/ Fetch the list of charging session debts of the user # List invoices of the user Source: https://docs.cariqa.com/api-reference/invoices/list-invoices-of-the-user /openapi.yaml get /api/v1/users/{user_id}/invoices/ List invoices of the user # Delete Payment Method Source: https://docs.cariqa.com/api-reference/payments/delete-payment-method /openapi.yaml delete /api/v1/users/{user_id}/payment-methods/{pm}/ Remove payment methods from the user # Get Setup Intent Source: https://docs.cariqa.com/api-reference/payments/get-setup-intent /openapi.yaml get /api/v1/users/{user_id}/setup-intents/ Retrieve client secret which is used in payment method creation # List Payment Methods Source: https://docs.cariqa.com/api-reference/payments/list-payment-methods /openapi.yaml get /api/v1/users/{user_id}/payment-methods/ Retrieve list of user payment methods # Set Payment Method as Default Source: https://docs.cariqa.com/api-reference/payments/set-payment-method-as-default /openapi.yaml post /api/v1/users/{user_id}/payment-methods/{pm}/default/ Set payment method as default # Get Map Tile Source: https://docs.cariqa.com/api-reference/stations/get-map-tile /openapi.yaml get /api/v1/stations/tile/ Fetch tile # Get Station Details Source: https://docs.cariqa.com/api-reference/stations/get-station-details /openapi.yaml get /api/v1/stations/details/ Retrieve station details # Get Stations Around Source: https://docs.cariqa.com/api-reference/stations/get-stations-around /openapi.yaml get /api/v1/stations/around/ List stations around # Partners list Source: https://docs.cariqa.com/api-reference/stations/partners-list /openapi.yaml get /api/v1/stations/partners/ Retrieve the list of partner names to use it for filtering # Create User Source: https://docs.cariqa.com/api-reference/users/create-user /openapi.yaml post /api/v1/users/ Create user **Requires one of these roles:** CustomerManager, PlatformManager, ProgramManager, RetailManager, RiskManager, StoreManager # Get User Source: https://docs.cariqa.com/api-reference/users/get-user /openapi.yaml get /api/v1/users/{user_id}/ Retrieve user # List Users Source: https://docs.cariqa.com/api-reference/users/list-users /openapi.yaml get /api/v1/users/ Retrieve list of the users # Soft-delete User Source: https://docs.cariqa.com/api-reference/users/soft-delete-user /openapi.yaml delete /api/v1/users/{user_id}/ Soft-delete user # Update User Source: https://docs.cariqa.com/api-reference/users/update-user /openapi.yaml patch /api/v1/users/{user_id}/ Update user **Requires one of these roles:** CustomerManager, PlatformManager, ProgramManager, RetailManager, RiskManager, StoreManager # Authentication Source: https://docs.cariqa.com/authentication Token-based authentication for the Cariqa Connect API The Cariqa Connect API uses **JWT-based Bearer tokens** for authentication. All requests to protected endpoints must include a valid token in the `Authorization` header. ## Access Token 1. Contact **Cariqa** to request an **Access Token** 2. Tokens are provided through **private communication channels** during onboarding ## Using the Bearer Token Include the Authorization header in all API requests: ```bash cURL theme={null} curl -X GET "https://connect.cariqa.com/api/v1/stations/around/?latitude=49.630383&longitude=8.368902&distance=10" \ -H "Authorization: Bearer YOUR_API_TOKEN" \ -H "Content-Type: application/json" ``` ```python Python theme={null} import requests headers = { "Authorization": "Bearer YOUR_API_TOKEN", "Content-Type": "application/json" } response = requests.get( "https://connect.cariqa.com/api/v1/stations/around/", headers=headers, params={ "latitude": 49.630383, "longitude": 8.368902, "distance": 10 } ) ``` ```javascript JavaScript theme={null} const response = await fetch('https://connect.cariqa.com/api/v1/stations/around/?latitude=49.630383&longitude=8.368902&distance=10', { headers: { 'Authorization': 'Bearer YOUR_API_TOKEN', 'Content-Type': 'application/json' } }); ``` ## Token Expiration * Access tokens are currently issued **without an expiration date** * Tokens may be **revoked by the Cariqa team upon client request** * Multiple tokens can be issued for service continuity and zero-downtime rotation ## Security Recommendations 1. Store secrets in a secure environment 2. Use **HTTPS** for all API requests 3. Rotate credentials periodically 4. Do no log sensitive credentials # Changelog Source: https://docs.cariqa.com/changelog Changelog of all notable changes made to the Cariqa Connect API over time organized by version and date. *** ## \[1.0.0] - 2026-06-09 ### Added 1. Public release of Connect API v1.0.0 # End-to-end example Source: https://docs.cariqa.com/complete-examples An end-to-end flow, from user registration to charging completion. ## User Journey This guide demonstrates a complete user journey through the Cariqa Connect API, showing how all the endpoints work together to deliver a seamless charging experience. ## Flow Overview 1. **User Registration** - Create user account 2. **Payment Setup** - Add and configure payment method via Stripe 3. **Station Discovery** - Find nearby charging stations 4. **Start Charging** - Initiate a charging session 5. **Monitor Session** - Track charging progress 6. **Stop Charging** - End session and get receipt *** ## 1. User Registration First, create a user account in the system: ```bash cURL theme={null} curl -X POST "https://connect.cariqa.com/api/v1/users/" \ -H "Authorization: Bearer YOUR_API_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "email": "alice@example.com", "locale": "en" }' ``` ```python Python theme={null} import requests headers = { "Authorization": "Bearer YOUR_API_TOKEN", "Content-Type": "application/json" } user_data = { "email": "alice@example.com", "locale": "en" } response = requests.post( "https://connect.cariqa.com/api/v1/users/", headers=headers, json=user_data ) user = response.json() user_id = user["id"] # Save this for subsequent calls ``` ```javascript JavaScript theme={null} const headers = { 'Authorization': 'Bearer YOUR_API_TOKEN', 'Content-Type': 'application/json' }; const userData = { email: 'alice@example.com', locale: 'en' }; const response = await fetch('https://connect.cariqa.com/api/v1/users/', { method: 'POST', headers, body: JSON.stringify(userData) }); const user = await response.json(); const userId = user.id; // Save this for subsequent calls ``` **Response:** ```json theme={null} { "id": "123", "email": "alice@example.com", "locale": "en" } ``` *** ## 2. Payment Method Setup ### 2.1 Create Setup Intent Get a Stripe setup intent to securely collect payment information: ```bash cURL theme={null} curl -X GET "https://connect.cariqa.com/api/v1/users/123/setup-intents/?pm_type=card" \ -H "Authorization: Bearer YOUR_API_TOKEN" ``` ```python Python theme={null} response = requests.get( f"https://connect.cariqa.com/api/v1/users/{user_id}/setup-intents/?pm_type=card", headers=headers ) setup_intent = response.json() client_secret = setup_intent["client_secret"] ``` ```javascript JavaScript theme={null} const setupResponse = await fetch(`https://connect.cariqa.com/api/v1/users/${userId}/setup-intents/?pm_type=card`, { headers }); const setupIntent = await setupResponse.json(); const clientSecret = setupIntent.client_secret; ``` **Response:** ```json theme={null} { "client_secret": "seti_1ABC123_secret_DEF456" } ``` ### 2.2 Frontend Stripe Integration The following Stripe integration MUST happen on your frontend for PSD2/SCA compliance. Follow the [Payment Frontend Setup](/payments-frontend-setup) guide to confirm the Setup Intent on the client side (iOS, Android, Web). ### 2.3 Verify Payment Method Added ```bash cURL theme={null} curl -X GET "https://connect.cariqa.com/api/v1/users/123/payment-methods/" \ -H "Authorization: Bearer YOUR_API_TOKEN" ``` ```python Python theme={null} response = requests.get( f"https://connect.cariqa.com/api/v1/users/{user_id}/payment-methods/", headers=headers ) payment_methods = response.json() default_pm = next(pm for pm in payment_methods["results"] if pm["is_default"]) payment_method_id = default_pm["id"] ``` ```javascript JavaScript theme={null} const pmResponse = await fetch(`https://connect.cariqa.com/api/v1/users/${userId}/payment-methods/`, { headers }); const paymentMethods = await pmResponse.json(); const defaultPm = paymentMethods.results.find(pm => pm.is_default); const paymentMethodId = defaultPm.id; ``` **Response:** ```json theme={null} { "count": 1, "next": null, "previous": null, "results": [ { "id": "pm_1TD1LuHtgZxQ1KXxNj5sKkKM", "default": true, "type": "card", "card": { "brand": "visa", "last4": "4242", "expiration_date": "04/2044", "cardholder_name": null }, "created_at": "2026-03-20T11:36:30Z" } ] } ``` *** ## 3. Station Discovery Find nearby charging stations: ```bash cURL theme={null} curl -X GET "https://connect.cariqa.com/api/v1/stations/around/?latitude=49.630383&longitude=8.368902&distance=10" \ -H "Authorization: Bearer YOUR_API_TOKEN" \ -H "Content-Type: application/json" ``` ```python Python theme={null} import requests headers = { "Authorization": "Bearer YOUR_API_TOKEN", "Content-Type": "application/json" } response = requests.get( "https://connect.cariqa.com/api/v1/stations/around/", headers=headers, params={ "latitude": 49.630383, "longitude": 8.368902, "distance": 10 } ) stations = response.json() chosen_station = stations["results"][0] # Pick first available station evse_id = chosen_station["evses"][0]["evse_id"] # Pick first available EVSE ``` ```javascript JavaScript theme={null} const response = await fetch('https://connect.cariqa.com/api/v1/stations/around/?latitude=49.630383&longitude=8.368902&distance=10', { headers: { 'Authorization': 'Bearer YOUR_API_TOKEN', 'Content-Type': 'application/json' } }); const stations = await response.json(); const chosenStation = stations.results[0]; // Pick first available station const evseId = chosenStation.evses[0].evse_id; // Pick first available EVSE ``` **Response (partial):** ```json expandable theme={null} { "id": "b475f4c35249ae698157660941050322", "name": "EVA Charge", "speed": "slow", "address": "Ludwigstraße, 9, 67547, Worms", "status": "free", "coordinates": { "latitude": "49.630383", "longitude": "8.368902" }, "opening_times": { "twentyfourseven": true, "regular_hours": [] }, "operator": { "name": "EVA Charge", "contact": { "phone": "+4971134214480" } }, "evses": [ { "evse_id": "DE*CIQ*EELDF6XWZU41P*2", "status": "AVAILABLE" }, { "evse_id": "DE*CIQ*EWBNHHLM82TLA*2", "status": "AVAILABLE" }, { "evse_id": "DE*CIQ*EELDF6XWZU41P*1", "status": "AVAILABLE" }, { "evse_id": "DE*CIQ*EWBNHHLM82TLA*1", "status": "CHARGING" } ], "last_updated": "2026-04-02T10:42:22Z", "amenities": [], "is_partner": true, "price_groups": [ { "type": "IEC_62196_T2", "power": 22, "evse_ids": [ "DE*CIQ*EELDF6XWZU41P*2", "DE*CIQ*EWBNHHLM82TLA*2", "DE*CIQ*EELDF6XWZU41P*1", "DE*CIQ*EWBNHHLM82TLA*1" ], "prices": { "time_price": null, "kwh_price": { "MONDAY": [ { "time_from": "00:00", "time_to": "01:00", "date_from": "2025-12-17", "date_to": null, "gross_price": "0.1950", "user_facing_price": "0.23", "grace_period_minutes": null, "tax": 19, "blocking_cap": null }, ... ] }, "blocking_fee": { "ALL": [ { "time_from": null, "time_to": null, "date_from": "2025-12-17", "date_to": null, "gross_price": "4.02", "user_facing_price": "0.08", "grace_period_minutes": 0, "tax": 19, "blocking_cap": null } ] }, "session_fee": null, "starting_fee": null }, "local_datetime": "2026-04-02T12:42:22.671636+02:00", "currency": "eur", "pre_authorization_amount": "30.00", "is_fallback": false } ], "logo_url": "https://storage.googleapis.com/cariqa-cpo-logos/custom_evacharge_dev_station_logo.png?generation=1766404007574021&md5_hash=e1e6197d26b8de242509afbbdd66a71a&size=4150" } ``` *** ## 4. Start Charging Session Initiate charging with the selected EVSE and payment method: ```bash cURL theme={null} curl -X POST "https://connect.cariqa.com/api/v1/users/123/charging/start/" \ -H "Authorization: Bearer YOUR_API_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "evse_id": "DE*CIQ*EELDF6XWZU41P*2", "payment_method_id": "pm_1TD1LuHtgZxQ1KXxNj5sKkKM" }' ``` ```python Python theme={null} start_data = { "evse_id": evse_id, "payment_method_id": payment_method_id } response = requests.post( f"https://connect.cariqa.com/api/v1/users/{user_id}/charging/start/", headers=headers, json=start_data ) session_start = response.json() session_id = session_start["id"] ``` ```javascript JavaScript theme={null} const startData = { evse_id: evseId, payment_method_id: paymentMethodId }; const startResponse = await fetch(`https://connect.cariqa.com/api/v1/users/${userId}/charging/start/`, { method: 'POST', headers, body: JSON.stringify(startData) }); const sessionStart = await startResponse.json(); const sessionId = sessionStart.id; ``` **Response:** ```json theme={null} { "id": "ab7ae756-b663-43b9-a025-40c51dd503d9", "start_time": "2026-04-02T13:51:18.754610Z", "end_time": null, "duration": 0, "consumed_energy": "0.000", "is_active": true, "evse_id": "DE*CIQ*EELDF6XWZU41P*2", "station_info": { "station_name": "EVA Charge", "station_address": "Ludwigstraße, 9, 67547, Worms", "country": "DE", "station_speed": "slow", "connector_standard": "IEC_62196_T2", "connector_power": 22, "support_phone": "+4971134214480", "latitude": "49.630383", "longitude": "8.368902" }, "is_partner": true, "logo_url": "https://storage.googleapis.com/cariqa-cpo-logos/evacharge.png?generation=1739874740770603&md5_hash=8dcf9c9d17149760b1c9033218ed1c19&size=11759", "user_facing_session_prices": { "kwh_price": "0.54", "time_price": null, "session_fee": null, "blocking_fee": null, "starting_fee": null, "grace_period_minutes": null, "blocking_cap": null, "currency": "eur" }, "session_cost": null, "rates": null } ``` *** ## 5. Monitor Charging Session Poll the session status to track progress: ```bash cURL theme={null} curl -X GET "https://connect.cariqa.com/api/v1/users/123/charging-sessions/ab7ae756-b663-43b9-a025-40c51dd503d9/" \ -H "Authorization: Bearer YOUR_API_TOKEN" ``` ```python Python theme={null} # Poll session status every 30 seconds import time def monitor_session(user_id, session_id): while True: response = requests.get( f"https://connect.cariqa.com/api/v1/users/{user_id}/charging-sessions/{session_id}/", headers=headers ) session = response.json() print(f"Status: {session['is_active']}") print(f"Energy: {session.get('consumed_energy', 0)} kWh") print(f"Duration: {session.get('duration', 0)} seconds") if not session["is_active"]: return session time.sleep(30) # Wait 30 seconds before next check # Start monitoring final_session = monitor_session(user_id, session_id) ``` ```javascript JavaScript theme={null} // Monitor session with polling const monitorSession = async (userId, sessionId) => { while (true) { const response = await fetch(`https://connect.cariqa.com/api/v1/users/${userId}/charging-sessions/${sessionId}/`, { headers }); const session = await response.json(); console.log(`Status: ${session.is_active}`); console.log(`Energy: ${session.consumed_energy || 0} kWh`); console.log(`Duration: ${session.duration || 0} seconds`); if (!session.is_active) { return session; } // Wait 30 seconds before next check await new Promise(resolve => setTimeout(resolve, 30000)); } }; // Start monitoring const finalSession = await monitorSession(userId, sessionId); ``` **Response (during charging):** ```json theme={null} { "id": "ab7ae756-b663-43b9-a025-40c51dd503d9", "start_time": "2024-03-24T14:30:00Z", "duration": 45, "consumed_energy": "12.50", "is_active": true, "evse_id": "DE*CIQ*EELDF6XWZU41P*2", ... } ``` *** ## 6. Stop Charging Session When charging is complete, stop the session: ```bash cURL theme={null} curl -X POST "https://connect.cariqa.com/api/v1/users/123/charging/stop/ab7ae756-b663-43b9-a025-40c51dd503d9/" \ -H "Authorization: Bearer YOUR_API_TOKEN" ``` ```python Python theme={null} response = requests.post( f"https://connect.cariqa.com/api/v1/users/{user_id}/charging/stop/{session_id}/", headers=headers ) stop_result = response.json() ``` ```javascript JavaScript theme={null} const stopResponse = await fetch(`https://connect.cariqa.com/api/v1/users/${userId}/charging/stop/${sessionId}/`, { method: 'POST', headers }); const stopResult = await stopResponse.json(); ``` **Response:** ```http theme={null} 204 ``` *** ## 7. Get completed charging session Retrieve the complete session details with final costs: ```bash cURL theme={null} curl -X GET "https://connect.cariqa.com/api/v1/users/123/charging-sessions/ab7ae756-b663-43b9-a025-40c51dd503d9/" \ -H "Authorization: Bearer YOUR_API_TOKEN" ``` ```python Python theme={null} response = requests.get( f"https://connect.cariqa.com/api/v1/users/{user_id}/charging-sessions/{session_id}/", headers=headers ) final_receipt = response.json() # Print receipt summary print(f"Charging Session Complete!") print(f"Energy consumed: {final_receipt['consumed_energy']} kWh") print(f"Duration: {final_receipt['duration']} minutes") print(f"Total cost: €{final_receipt['payg_summary']['invoice_summary']}") print(f"Invoice URL: {final_receipt['payg_summary']['invoice_download']}") ``` ```javascript JavaScript theme={null} const receiptResponse = await fetch(`https://connect.cariqa.com/api/v1/users/${userId}/charging-sessions/${sessionId}/`, { headers }); const finalReceipt = await receiptResponse.json(); // Display receipt summary console.log('Charging Session Complete!'); console.log(`Energy consumed: ${finalReceipt.consumed_energy} kWh`); console.log(`Duration: ${finalReceipt.duration} minutes`); console.log(`Total cost: €${finalReceipt.payg_summary.invoice_summary}`); console.log(`Invoice URL: ${finalReceipt.payg_summary.invoice_download}`); ``` **Response:** ```json theme={null} { "id": "ab7ae756-b663-43b9-a025-40c51dd503d9", "start_time": "2026-04-02T13:51:18.754610Z", "end_time": "2026-04-02T13:51:28.754611Z", "duration": 10, "consumed_energy": "10.000", "is_active": false, "evse_id": "DE*CIQ*EELDF6XWZU41P*2", "station_info": { "station_name": "EVA Charge", "station_address": "Ludwigstraße, 9, 67547, Worms", "country": "DE", "station_speed": "slow", "connector_standard": "IEC_62196_T2", "connector_power": 22, "support_phone": "+4971134214480", "latitude": "49.630383", "longitude": "8.368902" }, "is_partner": true, "logo_url": "https://storage.googleapis.com/cariqa-cpo-logos/evacharge.png?generation=1739874740770603&md5_hash=8dcf9c9d17149760b1c9033218ed1c19&size=11759", "user_facing_session_prices": { "kwh_price": "0.54", "time_price": null, "session_fee": null, "blocking_fee": null, "starting_fee": null, "grace_period_minutes": null, "blocking_cap": null, "currency": "eur" }, "session_cost": { "kwh_cost": "5.39", "time_cost": "0.00", "session_fee_cost": "0.00", "blocking_fee_cost": "0.00", "starting_fee_cost": "0.00", "invoice_download": "https://connect.cariqa.com/download/?", "invoice_vat": "0.86", "invoice_summary": "5.39", "invoice_credits": "0.00", "invoice_discount": "0.00", "currency": "eur" }, "rates": 5 } ``` *** ## Error Handling Best Practices Throughout this flow, implement proper error handling: ```javascript Example Error Handling theme={null} const handleApiCall = async (apiCall) => { try { const response = await apiCall(); if (!response.ok) { const error = await response.json(); switch (response.status) { case 402: // User has outstanding debt console.error('Payment required:', error.debt_details); break; case 403: console.error('Authentication failed'); break; case 404: console.error('Resource not found'); break; default: console.error('API error:', error); } return null; } return await response.json(); } catch (error) { console.error('Network error:', error); return null; } }; ``` ## Summary This complete flow demonstrates how to: 1. ✅ **Create user accounts** with proper authentication 2. ✅ **Securely collect payment methods** via Stripe integration 3. ✅ **Discover charging stations** with location-based search 4. ✅ **Initiate charging sessions** with payment authorization 5. ✅ **Monitor session progress** with real-time status updates 6. ✅ **Complete sessions** and generate detailed receipts The entire process is designed around the backend-to-backend authentication model, where your backend manages users on behalf of your customers while maintaining full control over the user experience. # Country-Specific Requirements Source: https://docs.cariqa.com/country-specific-requirements Additional requirements that apply in specific countries # Country-Specific Billing Requirements Some countries require additional billing information before invoices can be issued correctly. These requirements depend on: 1. the customer's country of residence 2. the customer's account type 3. the country where the charging session takes place (and therefore where the station is located) ## Italy Italy has stricter invoicing requirements than many other countries, especially because electronic invoicing is widely used through the national **Sistema di Interscambio**, commonly called **SdI**. The Italian Revenue Agency describes SdI as the exchange system used to transmit electronic invoices, with invoices prepared in XML format such as **FatturaPA** [\[1\]](https://www.agenziaentrate.gov.it/portale/web/english/electronic-invoicing). For customers in Italy, billing details should include complete identity and address information, plus the correct tax identifier depending on whether the account is personal or business. ### Personal Accounts For a personal account of Italian customer, they should provide: * Country: `it` * First name * Last name * Billing address: * Street address * City * Postal code * **Codice fiscale** in the `tax_id` field The **codice fiscale** is the Italian tax code used to identify individuals for tax and administrative purposes. For personal invoices, this is the appropriate identifier to collect instead of a VAT number. Example: ```json theme={null} { "country": "it", "city": "Rome", "tax_id": "RSSMRA80A01H501U", "account_type": "personal", "line1": "Via Roma 10", "postal_code": "00100", "first_name": "Mario", "last_name": "Rossi" } ``` For a personal account of customer from different country, they should provide: * Country: `de` * First name * Last name * Billing address: * Street address * City * Postal code Example: ```json theme={null} { "country": "de", "city": "Berlin", "tax_id": null, "account_type": "personal", "line1": "Street in Berlin", "postal_code": "10000", "first_name": "Mario", "last_name": "Rossi" } ``` ### Business Accounts For a business account of Italian customer, the customer should provide: * Country: `it` * Company name * Billing address: * Street address * City * Postal code * **VAT ID / Partita IVA** in the `vat_id` field * Contact first name and last name, if available The Italian VAT number is commonly referred to as **Partita IVA**. It is required for businesses and professional invoices. Example: ```json theme={null} { "country": "it", "city": "Rome", "account_type": "business", "company_name": "CompanyName", "vat_id": "IT123456789", "line1": "Via Roma 10", "postal_code": "00100" } ``` For a business account of customer from different country, the customer should provide: * Country: `de` * Company name * Billing address: * Street address * City * Postal code * **VAT ID** in the `vat_id` field * Contact first name and last name, if available Example: ```json theme={null} { "country": "de", "city": "Berlin", "account_type": "business", "company_name": "CompanyName", "vat_id": "DE123456789", "line1": "Street in Berlin", "postal_code": "10000" } ``` ### Validation Expectations for stations in Italy When user is from Italy: * If `account_type` is `personal`, require `tax_id`. * If `account_type` is `business`, require `company_name` and `vat_id`. * Require complete billing address details for both personal and business accounts. * Use `tax_id` for the Italian **codice fiscale**. * Use `vat_id` for the Italian **Partita IVA**. When user is NOT from Italy: * If `account_type` is `personal` - `tax_id` is OPTIONAL. * If `account_type` is `business`, require `company_name` and `vat_id`. * Require complete billing address details for both personal and business accounts. ### Notes Italy has mandatory electronic invoicing rules for many domestic invoice flows. Invoices are transmitted through the Italian Revenue Agency's SdI system, and official guidance states that electronic invoices are exchanged in XML format [\[1\]](https://www.agenziaentrate.gov.it/portale/web/english/electronic-invoicing). Because of this, collecting accurate billing details is especially important for Italian customers. Missing or incorrect identifiers may prevent invoice generation or cause invoices to be rejected by downstream invoicing systems. # Demo playground Source: https://docs.cariqa.com/demo-playground The Connect API can be tested via the playground — a demo-only version of a backend-to-backend API.

In a real-world scenario, these operations must be performed on a secure backend server. The only genuinely frontend part is the manual payment confirmation, which is meant to happen via the Stripe SDK. Two modes are available: * Development * Production **Playground:** [https://play.connect.cariqa.com/](https://play.connect.cariqa.com/) **Source code:** [https://github.com/Cariqa/connect-playground](https://github.com/Cariqa/connect-playground) # Environments and Testing Source: https://docs.cariqa.com/environments-and-testing Learn how Cariqa Connect API environments work and what to expect when testing charging sessions in development. Cariqa Connect API is available in two separate environments: **development** and **production**. Each environment is isolated and intended for a different stage of your integration lifecycle. ## Environments API credentials are environment-specific: development credentials won't work in production, and production credentials won't work in development. | Environment | Purpose | URL | | :----------------------------- | :---------------------- | :-------------------------------- | | **Development**
**(DEV)** | Integration and testing | `https://dev.connect.cariqa.com/` | | **Production**
**(PROD)** | Real-life charging | `https://connect.cariqa.com/` | #### Capabilities | Environment | Payments | EV-Charging | Locations data | | :----------------------------- | :------- | :---------- | -------------- | | **Development**
**(DEV)** | Fake | Fake | Real + fake | | **Production**
**(PROD)** | Real | Real | Real | #### Connect API Playground The Connect API Playground lets you explore every supported use case hands-on, no code needed. It's the fastest way to understand what the API can do before writing a single line of integration code. If you have your API keys ready, try it at [play.connect.cariqa.com](http://play.connect.cariqa.com). ## Development Environment The **development environment** is designed to help you test the complete Connect API integration without relying on live charging infrastructure behavior. You should use DEV to validate flows such as: * Creating and managing users * Adding payment methods in test mode * Discovering stations and connectors * Starting and stopping charging sessions * Reading charging session history * Handling charging session updates ## Production Environment The **production environment** is connected to live operational flows and should be used only after your integration has been reviewed and validated. Before going live, make sure that: * Your backend securely stores the production API token * Your frontend payment integration is configured correctly * Your backend and user-facing flows handle charging errors gracefully * Your team has completed end-to-end testing in DEV Production charging sessions may involve real users, live charging infrastructure, and real financial transactions. Do not use production for exploratory testing. ## Testing Charging Sessions in development environment The development environment uses **Virtual Charging Points** (VCPs) to help you test charging session flows without relying on live charging infrastructure. There are currently **two types of VCPs** available in development environment: 1. **Shared VCP without progress updates** 2. **VCP with progress updates** VCP behavior is independent from the charging session status returned in station details responses or station tile responses. A station may appear available in station data while the underlying VCP is busy, or vice versa. ### Type 1: Shared VCP without Progress Updates This type of VCP allows you to test the basic charging lifecycle: * Starting a charging session * Stopping a charging session * Receiving the final CDR This type does **not** send progress updates, so you should not expect consumed kWh to increase while the session is active. The final CDR is the confirmation that the session was processed. The VCP is **shared between multiple external parties**. This means another integration partner may start a charging session on the same VCP while you are testing. As a result, a start charging request may fail because the VCP is busy, even if the station details response shows the station as available. Because this VCP is shared, stop your test charging session as soon as possible. Keeping a session open for longer than necessary may prevent other parties from testing and can cause service interruption for them. #### Testing Busy Station Behavior You can use this Virtual Charging Point type to simulate a busy station scenario. To test this: 1. Start a charging session with one test user. 2. While the first session is still active, try to start another session on the same station with a different test user. 3. The second start attempt should behave as a busy-station scenario. #### Example EVSE IDs Try to use the following EVSE IDs to trigger the test at this VCP type: * `DE*CIQ*EWBNHHLM82TLA*1` * `IT*PWY*EP0078*01*02` * `DEQRMEF7GRC21` * `AT*VIE*E2334770022*2` ### Type 2: VCP with Progress Updates This type of VCP supports **charging progress messages**. You can use it to test how consumed kWh values appear in charging session details while a session is ongoing. This is useful for validating UI behavior such as: * Showing an active charging session * Displaying consumed kWh * Updating session details over time * Handling the final CDR after charging is complete **Quite some Charge Point Operators do not support progress messages. This means that even if a charging session has started successfully, the final CDR may be the only confirmation that charging was actually ongoing. Take this into account when designing and developing your UI in production.** Progress messages for this VCP type are **hard-coded** in the testing environment. They may continue to arrive even if you send a stop charging request. You should expect: * Up to 10 progress messages * Consumed kWh values to update during the test flow * The final CDR to arrive automatically eventually Busy-station behavior cannot be tested with this VCP type. Use the shared VCP without progress updates if you need to test busy-session scenarios. #### Example EVSE IDs Use the following EVSE IDs to test this VCP type: * `DE*PWA*EALP22541X01617*01` * `DE*2GO*EMCD1520*1B*3` * `DE*EUL*EAUT0002*01` * `AT*HTB*EOCPI1*1` ## Recommended Testing Checklist Use the checklist below before requesting production access or enabling the integration for real users. ### Backend Integration * API token is stored securely * Requests include the correct Bearer token * User creation and lookup flows are implemented * Charging start and stop flows are implemented * Charging session polling is implemented * API errors are logged and handled safely ### Frontend Integration * Payment method collection is implemented * Test payment methods are validated * Charging status is visible to the user * Stop charging action is available where applicable * Error messages are user-friendly * Loading and retry states are handled ## Before go-live Once your DEV testing is complete, contact the Cariqa team to coordinate production enablement. Before production access is enabled, Cariqa may review: * Your implemented user journey * Payment method setup * Charging session handling * Error handling behavior * Support readiness * Country-specific requirements, if applicable # Overview Source: https://docs.cariqa.com/getting-started Quick guide to the Cariqa Connect API Download the full OpenAPI 3.0 spec This guide walks you through the essential endpoints and workflows for integrating with the Cariqa Connect API. ## Prerequisites Before starting, ensure you have: * **API Token** - Contact Cariqa for your access token * **Stripe Integration** - Frontend Stripe SDK setup is mandatory for payments * **HTTPS Environment** - All API calls must use HTTPS ## Core Workflows ### 1. User Management All endpoints starting with `/users` require users to be created in the system first. ```bash cURL theme={null} # Create User curl -X POST "https://connect.cariqa.com/api/v1/users/" \ -H "Authorization: Bearer YOUR_API_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "email": "user@example.com", "locale": "de" }' # Get User curl -X GET "https://connect.cariqa.com/api/v1/users/123/" \ -H "Authorization: Bearer YOUR_TOKEN" # Update User curl -X PATCH "https://connect.cariqa.com/api/v1/users/123/" \ -H "Authorization: Bearer YOUR_TOKEN" \ -H "Content-Type: application/json" \ -d '{"locale": "en"}' ``` ```python Python theme={null} import requests headers = { "Authorization": "Bearer YOUR_TOKEN", "Content-Type": "application/json" } # Create User user_data = { "first_name": "John", "last_name": "Doe", "email": "john@example.com" } response = requests.post( "https://connect.cariqa.com/api/v1/users/", headers=headers, json=user_data ) # Get User response = requests.get( "https://connect.cariqa.com/api/v1/users/123/", headers=headers ) # Update User update_data = {"first_name": "Jane"} response = requests.patch( "https://connect.cariqa.com/api/v1/users/123/", headers=headers, json=update_data ) ``` ```javascript JavaScript theme={null} const headers = { 'Authorization': 'Bearer YOUR_TOKEN', 'Content-Type': 'application/json' }; // Create User const createUser = await fetch('https://connect.cariqa.com/api/v1/users/', { method: 'POST', headers, body: JSON.stringify({ first_name: 'John', last_name: 'Doe', email: 'john@example.com' }) }); // Get User const getUser = await fetch('https://connect.cariqa.com/api/v1/users/123/', { headers }); // Update User const updateUser = await fetch('https://connect.cariqa.com/api/v1/users/123/', { method: 'PATCH', headers, body: JSON.stringify({ first_name: 'Jane' }) }); ``` **Supported operations:** * `POST /users/` - Create user * `GET /users/` - List all users * `GET /users//` - Get user by ID * `PATCH /users//` - Update user * `DELETE /users//` - Soft delete user ### 2. Billing Details User accounts are divided into **Personal** (default) and **Business** types. ```bash Update Billing Details theme={null} curl -X PUT "https://connect.cariqa.com/api/v1/users/123/billing-details/" \ -H "Authorization: Bearer YOUR_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "account_type": "business", "company_name": "Example Corp", "vat_number": "DE123456789" }' ``` ```bash Get Billing Details theme={null} curl -X GET "https://connect.cariqa.com/api/v1/users/123/billing-details/" \ -H "Authorization: Bearer YOUR_TOKEN" ``` * **Business accounts** include company name and VAT number on invoices * **Personal accounts** use first and last names on invoices ### 3. Payment Methods Payment method data is handled by Stripe. Use [Stripe's SDK](https://docs.stripe.com/payments/mobile/set-up-future-payments?platform=ios\&mobile-ui=payment-element#collect-payment-details) to collect payment details securely. ```bash List Payment Methods theme={null} curl -X GET "https://connect.cariqa.com/api/v1/users/123/payment-methods/" \ -H "Authorization: Bearer YOUR_TOKEN" ``` ```bash Setup Intent for Card theme={null} curl -X GET "https://connect.cariqa.com/api/v1/users/123/setup-intents/?pm_type=card" \ -H "Authorization: Bearer YOUR_TOKEN" ``` ```bash Set Default Payment Method theme={null} curl -X POST "https://connect.cariqa.com/api/v1/users/123/payment-methods/pm_abc123/default/" \ -H "Authorization: Bearer YOUR_TOKEN" ``` **Supported operations:** * `GET /users//payment-methods/` - List payment methods * `DELETE /users//payment-methods//` - Remove payment method * `POST /users//payment-methods//default/` - Set as default * `GET /users//setup-intents/?pm_type=card` - Connect payment method (supports `card` and `paypal`) ### 4. Station Discovery Station endpoints are **not tied to specific users** - they're general lookup endpoints. ```bash Stations Around Location theme={null} curl -X GET "https://connect.cariqa.com/api/v1/stations/around/" \ -H "Authorization: Bearer YOUR_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "latitude": 52.520008, "longitude": 13.404954, "distance": 5000 }' ``` ```bash Station Details theme={null} curl -X GET "https://connect.cariqa.com/api/v1/stations/details/?type=station_id&id=station_1234" \ -H "Authorization: Bearer YOUR_TOKEN" ``` ```bash Station Tile Data theme={null} curl -X GET "https://connect.cariqa.com/api/v1/stations/tile/?z=12&x=1234&y=5678" \ -H "Authorization: Bearer YOUR_TOKEN" ``` **Available endpoints:** * `GET /stations/around/` - Find stations near a location * `GET /stations/details/` - Get detailed station information * `GET /stations/tile/` - Get map tile data for visualization ### 5. Charging Sessions ```bash Start Charging theme={null} curl -X POST "https://connect.cariqa.com/api/v1/users/123/charging/start/" \ -H "Authorization: Bearer YOUR_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "payment_method_id": "pm_abc123", "evse_id": "DEBLA0034232" }' ``` ```bash Stop Charging theme={null} curl -X POST "https://connect.cariqa.com/api/v1/users/123/charging/stop/456/" \ -H "Authorization: Bearer YOUR_TOKEN" ``` ```bash List Sessions theme={null} curl -X GET "https://connect.cariqa.com/api/v1/users/123/charging-sessions/" \ -H "Authorization: Bearer YOUR_TOKEN" ``` **Session management:** * `POST /users//charging/start/` - Start charging session * `POST /users//charging/stop//` - Stop charging session * `GET /users//charging-sessions/` - List charging sessions * `GET /users//charging-sessions//` - Get session details ## Typical Integration Flow 1. **Create user** in the Cariqa system 2. **Set up Stripe** payment methods using Stripe SDK 3. **Connect payment method** via setup intents 4. **Search stations** around user's location 5. **Start charging session** with payment method and EVSE ID 6. **Monitor session** status and handle completion 7. **Process invoicing** through automated CDR generation ## Next Steps * Explore [Authentication](/authentication) for token setup * Review [API Reference](/api-reference) for complete endpoint documentation * Check integration examples for your platform * Set up error handling and monitoring Remember that Stripe SDK integration on your frontend is mandatory for PSD2/SCA compliance - payments cannot be processed backend-only. # What is Cariqa Connect API Source: https://docs.cariqa.com/introduction Cariqa Connect API is a backend-to-backend API that enables OEMs, mobility services and platforms to seamlessly offer EV charging through a single API integration, unlocking direct charge point operator prices for their end users while removing operational complexity and ensuring full regulatory compliance. Cariqa Connect Diagram Cariqa Connect Diagram ## Why using it 1. Skip intermediary markups and access Europe’s charging networks at charge point operator **direct prices**, with transparent **revenue sharing** built in. 2. **Avoid** the **complexity** of energy resale, pricing structures, and cross-border regulatory requirements. Cariqa Connect handles the underlying **compliance** and market-specific constraints, so mobility services and platforms can operate confidently without navigating fragmented legal frameworks. 3. Deliver a **complete charging experience**, from station discovery and availability to session management and payments, through a single RESTful API that replaces the need for multiple operator integrations and reduces operational overhead. ## Who is it for * **OEMs and automotive manufacturers** - Native in-vehicle charging experiences * **Fleet management companies** - Integrated operations solutions * **Mobility service providers** - Complete transportation platforms * **Enterprise customers** - Employee/customer-facing charging features * **Technology partners** - Add EV charging without complex integrations ## Key benefits ### Direct marketplace access * No middleman markups - operator-set pricing * Transparent revenue sharing model * Direct CPO relationships ### Complete integration * Station discovery with live stations data and blazing fast map tiles (map rendering) * Session management (start/stop/monitor) * Secure payment processing via [Stripe](https://stripe.com/) (PSD2 compliant) * Invoice and billing (for both B2C and B2B customers) ### Developer-friendly * A Single API which replaces a jungle of integrations * Complexity is abstracted and managed by Cariqa, so you can focus on building your product rather than dealing with EV charging complexity ## Authentication Backend-to-backend token authentication: * Your backend authenticates once, operates on behalf of any user * Secure API tokens with optional rotation support * You control the customer experience ## Next Steps 1. [Quick Start](/quickstart) - Get to Your first API call 2. [Authentication setup](/authentication) - Learn more about our API security 3. [API Reference](/api-reference) - Complete endpoint documentation **Manual onboarding**: Currently, all partner onboarding is handled manually by the Cariqa team. # MCP server Source: https://docs.cariqa.com/mcp-server The Connect API MCP server gives your AI coding agents native access to the entire Connect API knowledge base: documentation, code examples, API reference, and guides.\ Your agent can search across the docs, read specific pages, and explore the full API structure directly. No more copy-pasting documentation into your context, your agent understands Connect API out of the box, and can help you build your desired use-case without leaving your IDE. Just point your MCP-compatible agent at [**docs.cariqa.com/mcp**](https://docs.cariqa.com/mcp), and you're ready to go! # Billing Details Source: https://docs.cariqa.com/patterns-billing Usage patterns for billing and account type management ## Account Type Configuration Billing details control invoice formatting and account type handling. Some countries has specific constraints. [Check this page before proceed](/country-specific-requirements). ### Retrieve Current Billing Details ```bash cURL theme={null} curl -X GET "https://connect.cariqa.com/api/v1/users/9405cf8c-8375-4373-b4d3-b61f9a0c01eb/billing-details/" \ -H "Authorization: Bearer YOUR_API_TOKEN" \ -H "Content-Type: application/json" ``` ```python Python theme={null} import requests headers = { "Authorization": "Bearer YOUR_API_TOKEN", "Content-Type": "application/json" } response = requests.get( "https://connect.cariqa.com/api/v1/users/9405cf8c-8375-4373-b4d3-b61f9a0c01eb/billing-details/", headers=headers ) ``` ```javascript JavaScript theme={null} const response = await fetch('https://connect.cariqa.com/api/v1/users/9405cf8c-8375-4373-b4d3-b61f9a0c01eb/billing-details/', { headers: { 'Authorization': 'Bearer YOUR_API_TOKEN', 'Content-Type': 'application/json' } }); ``` Response: ```json theme={null} { "country": null, "city": null, "tax_id": null, "account_type": "personal", "company_name": null, "vat_id": null, "line1": null, "postal_code": null, "first_name": null, "last_name": null } ``` ### Configure Personal Account ```bash cURL theme={null} curl -X PUT "https://connect.cariqa.com/api/v1/users/9405cf8c-8375-4373-b4d3-b61f9a0c01eb/billing-details/" \ -H "Authorization: Bearer YOUR_API_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "country": "de", "city": "Berlin", "tax_id": "DE123456789", "account_type": "personal", "line1": "BeKarl-Marx-Alleerlin", "postal_code": "10243", "first_name": "Example", "last_name": "Sample" }' ``` ```python Python theme={null} import requests headers = { "Authorization": "Bearer YOUR_API_TOKEN", "Content-Type": "application/json" } data = { "country": "de", "city": "Berlin", "tax_id": "DE123456789", "account_type": "personal", "line1": "BeKarl-Marx-Alleerlin", "postal_code": "10243", "first_name": "Example", "last_name": "Sample" } response = requests.put( "https://connect.cariqa.com/api/v1/users/9405cf8c-8375-4373-b4d3-b61f9a0c01eb/billing-details/", headers=headers, json=data ) ``` ```javascript JavaScript theme={null} const response = await fetch('https://connect.cariqa.com/api/v1/users/9405cf8c-8375-4373-b4d3-b61f9a0c01eb/billing-details/', { method: 'PUT', headers: { 'Authorization': 'Bearer YOUR_API_TOKEN', 'Content-Type': 'application/json' }, body: JSON.stringify({ country: 'de', city: 'Berlin', tax_id: 'DE123456789', account_type: 'personal', line1: 'BeKarl-Marx-Alleerlin', postal_code: '10243', first_name: 'Example', last_name: 'Sample' }) }); ``` Response: ```json theme={null} { "country": "de", "city": "Berlin", "tax_id": "DE123456789", "account_type": "personal", "company_name": null, "vat_id": null, "line1": "BeKarl-Marx-Alleerlin", "postal_code": "10243", "first_name": "Example", "last_name": "Sample" } ``` ### Configure Business Account ```bash cURL theme={null} curl -X PUT "https://connect.cariqa.com/api/v1/users/9405cf8c-8375-4373-b4d3-b61f9a0c01eb/billing-details/" \ -H "Authorization: Bearer YOUR_API_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "country": "de", "city": "Berlin", "account_type": "business", "company_name": "CompanyName", "vat_id": "DE123456789", "line1": "BeKarl-Marx-Alleerlin", "postal_code": "10243", "first_name": "Example", "last_name": "Sample" }' ``` ```python Python theme={null} import requests headers = { "Authorization": "Bearer YOUR_API_TOKEN", "Content-Type": "application/json" } data = { "country": "de", "city": "Berlin", "account_type": "business", "company_name": "CompanyName", "vat_id": "DE123456789", "line1": "BeKarl-Marx-Alleerlin", "postal_code": "10243", "first_name": "Example", "last_name": "Sample" } response = requests.put( "https://connect.cariqa.com/api/v1/users/9405cf8c-8375-4373-b4d3-b61f9a0c01eb/billing-details/", headers=headers, json=data ) ``` ```javascript JavaScript theme={null} const response = await fetch('https://connect.cariqa.com/api/v1/users/9405cf8c-8375-4373-b4d3-b61f9a0c01eb/billing-details/', { method: 'PUT', headers: { 'Authorization': 'Bearer YOUR_API_TOKEN', 'Content-Type': 'application/json' }, body: JSON.stringify({ country: 'de', city: 'Berlin', account_type: 'business', company_name: 'CompanyName', vat_id: 'DE123456789', line1: 'BeKarl-Marx-Alleerlin', postal_code: '10243', first_name: 'Example', last_name: 'Sample' }) }); ``` Response: ```json theme={null} { "country": "de", "city": "Berlin", "tax_id": null, "account_type": "business", "company_name": "CompanyName", "vat_id": "DE123456789", "line1": "BeKarl-Marx-Alleerlin", "postal_code": "10243", "first_name": "Example", "last_name": "Sample" } ``` ## Account Type Impact * **Personal Account**: Uses first and last names on invoices, personal TAX ID in case of need * **Business Account**: Uses company name and VAT ID for professional invoices with proper tax handling * **Invoice Generation**: Billing details ensure proper identity and formatting for payment flows # Charging Sessions Source: https://docs.cariqa.com/patterns-charging Usage patterns for retrieving charging session data and history ## Session History and Details ### List User's Charging Sessions ```bash cURL theme={null} curl -X GET "https://connect.cariqa.com/api/v1/users/9405cf8c-8375-4373-b4d3-b61f9a0c01eb/charging-sessions/" \ -H "Authorization: Bearer YOUR_API_TOKEN" \ -H "Content-Type: application/json" ``` ```python Python theme={null} import requests headers = { "Authorization": "Bearer YOUR_API_TOKEN", "Content-Type": "application/json" } response = requests.get( "https://connect.cariqa.com/api/v1/users/9405cf8c-8375-4373-b4d3-b61f9a0c01eb/charging-sessions/", headers=headers ) ``` ```javascript JavaScript theme={null} const response = await fetch('https://connect.cariqa.com/api/v1/users/9405cf8c-8375-4373-b4d3-b61f9a0c01eb/charging-sessions/', { headers: { 'Authorization': 'Bearer YOUR_API_TOKEN', 'Content-Type': 'application/json' } }); ``` Response includes comprehensive session data: ```json theme={null} { "count": 1, "next": null, "previous": null, "results": [ { "id": "ab7ae756-b663-43b9-a025-40c51dd503d9", "start_time": "2026-04-02T13:51:18.754610Z", "end_time": "2026-04-02T13:51:28.754611Z", "duration": 10, "consumed_energy": "10.000", "is_active": false, "evse_id": "DE*CIQ*EELDF6XWZU41P*2", "station_info": { "station_name": "EVA Charge", "station_address": "Ludwigstraße, 9, 67547, Worms", "country": "DE", "station_speed": "slow", "connector_standard": "IEC_62196_T2", "connector_power": 22, "support_phone": "+4971134214480", "latitude": "49.630383", "longitude": "8.368902" }, "is_partner": true, "logo_url": "https://storage.googleapis.com/cariqa-cpo-logos/evacharge.png?generation=1739874740770603&md5_hash=8dcf9c9d17149760b1c9033218ed1c19&size=11759", "user_facing_session_prices": { "kwh_price": "0.54", "time_price": null, "session_fee": null, "blocking_fee": null, "starting_fee": null, "grace_period_minutes": null, "blocking_cap": null, "currency": "eur" }, "session_cost": { "kwh_cost": "5.39", "time_cost": "0.00", "session_fee_cost": "0.00", "blocking_fee_cost": "0.00", "starting_fee_cost": "0.00", "invoice_download": "https://connect.cariqa.com/download/?", "invoice_vat": "0.86", "invoice_summary": "5.39", "invoice_credits": "0.00", "invoice_discount": "0.00", "currency": "eur" }, "rates": 5 } ] } ``` ### Get Single Session Details ```bash cURL theme={null} curl -X GET "https://connect.cariqa.com/api/v1/users/9405cf8c-8375-4373-b4d3-b61f9a0c01eb/charging-sessions/ab7ae756-b663-43b9-a025-40c51dd503d9/" \ -H "Authorization: Bearer YOUR_API_TOKEN" \ -H "Content-Type: application/json" ``` ```python Python theme={null} import requests headers = { "Authorization": "Bearer YOUR_API_TOKEN", "Content-Type": "application/json" } response = requests.get( "https://connect.cariqa.com/api/v1/users/9405cf8c-8375-4373-b4d3-b61f9a0c01eb/charging-sessions/ab7ae756-b663-43b9-a025-40c51dd503d9/", headers=headers ) ``` ```javascript JavaScript theme={null} const response = await fetch('https://connect.cariqa.com/api/v1/users/9405cf8c-8375-4373-b4d3-b61f9a0c01eb/charging-sessions/ab7ae756-b663-43b9-a025-40c51dd503d9/', { headers: { 'Authorization': 'Bearer YOUR_API_TOKEN', 'Content-Type': 'application/json' } }); ``` Response provides the same detailed session object with complete station information, pricing breakdown, and invoice links. ### Patch Single Session Details Rate the charging session: ```bash cURL theme={null} curl -X PATCH "https://connect.cariqa.com/api/v1/users/9405cf8c-8375-4373-b4d3-b61f9a0c01eb/charging-sessions/ab7ae756-b663-43b9-a025-40c51dd503d9/" \ -H "Authorization: Bearer YOUR_API_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "rates": 5, }' ``` ```python Python theme={null} import requests headers = { "Authorization": "Bearer YOUR_API_TOKEN", "Content-Type": "application/json" } data = { "rates": 5, } response = requests.patch( "https://connect.cariqa.com/api/v1/users/9405cf8c-8375-4373-b4d3-b61f9a0c01eb/charging-sessions/ab7ae756-b663-43b9-a025-40c51dd503d9/", headers=headers, json=data ) ``` ```javascript JavaScript theme={null} const response = await fetch('https://connect.cariqa.com/api/v1/users/9405cf8c-8375-4373-b4d3-b61f9a0c01eb/charging-sessions/ab7ae756-b663-43b9-a025-40c51dd503d9/', { method: 'PATCH', headers: { 'Authorization': 'Bearer YOUR_API_TOKEN', 'Content-Type': 'application/json' }, body: JSON.stringify({ rates: 5, }) }); ``` Response provides the same detailed session object with complete station information, pricing breakdown, and invoice links. ## Start-Stop-CDR Flow The complete charging lifecycle consists of starting a session, monitoring progress, stopping the session, and receiving the final Charge Detail Record (CDR). ### Start Charging Session Initiate a charging session by providing the EVSE ID and payment method: ```bash cURL theme={null} curl -X POST "https://connect.cariqa.com/api/v1/users/9405cf8c-8375-4373-b4d3-b61f9a0c01eb/charging/start/" \ -H "Authorization: Bearer YOUR_API_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "evse_id": "DE*CIQ*EELDF6XWZU41P*2", "payment_method_id": "pm_1TD1M3HtgZxQ1KXx5wMzfx15" }' ``` ```python Python theme={null} import requests headers = { "Authorization": "Bearer YOUR_API_TOKEN", "Content-Type": "application/json" } start_data = { "evse_id": "DEALLEGO0034232", "payment_method_id": "pm_1ABC123DEF456" } response = requests.post( "https://connect.cariqa.com/api/v1/users/9405cf8c-8375-4373-b4d3-b61f9a0c01eb/charging/start/", headers=headers, json=start_data ) session_start = response.json() ``` ```javascript JavaScript theme={null} const response = await fetch('https://connect.cariqa.com/api/v1/users/9405cf8c-8375-4373-b4d3-b61f9a0c01eb/charging/start/', { method: 'POST', headers: { 'Authorization': 'Bearer YOUR_API_TOKEN', 'Content-Type': 'application/json' }, body: JSON.stringify({ evse_id: 'DEALLEGO0034232', payment_method_id: 'pm_1ABC123DEF456' }) }); const sessionStart = await response.json(); ``` **Response:** ```json theme={null} { "id": "ab7ae756-b663-43b9-a025-40c51dd503d9", "start_time": "2026-04-02T13:51:18.754610Z", "end_time": null, "duration": 0, "consumed_energy": "0.000", "is_active": true, "evse_id": "DE*CIQ*EELDF6XWZU41P*2", "station_info": { "station_name": "EVA Charge", "station_address": "Ludwigstraße, 9, 67547, Worms", "country": "DE", "station_speed": "slow", "connector_standard": "IEC_62196_T2", "connector_power": 22, "support_phone": "+4971134214480", "latitude": "49.630383", "longitude": "8.368902" }, "is_partner": true, "logo_url": "https://storage.googleapis.com/cariqa-cpo-logos/evacharge.png?generation=1739874740770603&md5_hash=8dcf9c9d17149760b1c9033218ed1c19&size=11759", "user_facing_session_prices": { "kwh_price": "0.54", "time_price": null, "session_fee": null, "blocking_fee": null, "starting_fee": null, "grace_period_minutes": null, "blocking_cap": null, "currency": "eur" }, "session_cost": null, "rates": null } ``` ### Stop Charging Session End the charging session manually by providing the session ID: ```bash cURL theme={null} curl -X POST "https://connect.cariqa.com/api/v1/users/9405cf8c-8375-4373-b4d3-b61f9a0c01eb/charging/stop/ab7ae756-b663-43b9-a025-40c51dd503d9/" \ -H "Authorization: Bearer YOUR_API_TOKEN" \ -H "Content-Type: application/json" ``` ```python Python theme={null} import requests headers = { "Authorization": "Bearer YOUR_API_TOKEN", "Content-Type": "application/json" } response = requests.post( "https://connect.cariqa.com/api/v1/users/9405cf8c-8375-4373-b4d3-b61f9a0c01eb/charging/stop/ab7ae756-b663-43b9-a025-40c51dd503d9/", headers=headers ) stop_result = response.json() ``` ```javascript JavaScript theme={null} const response = await fetch('https://connect.cariqa.com/api/v1/users/9405cf8c-8375-4373-b4d3-b61f9a0c01eb/charging/stop/ab7ae756-b663-43b9-a025-40c51dd503d9/', { method: 'POST', headers: { 'Authorization': 'Bearer YOUR_API_TOKEN', 'Content-Type': 'application/json' } }); const stopResult = await response.json(); ``` ### CDR Processing and Final Receipt After the charging session ends (either manually stopped or automatically), the system receives a Charge Detail Record (CDR) from the charging network that contains the final consumption and cost data. This process happens automatically in the backend: 1. **CDR Reception**: The charging station operator sends consumption data 2. **Session Update**: Final energy consumption, duration, and costs are calculated 3. **Payment Processing**: Pre-authorized amount is captured based on actual consumption 4. **Invoice Generation**: Detailed invoice with breakdown is created 5. **Receipt Availability**: Session data includes final costs and invoice links Retrieve the final session details with complete CDR data: ```bash cURL theme={null} curl -X GET "https://connect.cariqa.com/api/v1/users/9405cf8c-8375-4373-b4d3-b61f9a0c01eb/charging-sessions/ab7ae756-b663-43b9-a025-40c51dd503d9/" \ -H "Authorization: Bearer YOUR_API_TOKEN" \ -H "Content-Type: application/json" ``` ```python Python theme={null} import requests headers = { "Authorization": "Bearer YOUR_API_TOKEN", "Content-Type": "application/json" } response = requests.get( "https://connect.cariqa.com/api/v1/users/9405cf8c-8375-4373-b4d3-b61f9a0c01eb/charging-sessions/ab7ae756-b663-43b9-a025-40c51dd503d9/", headers=headers ) final_session = response.json() ``` ```javascript JavaScript theme={null} const response = await fetch('https://connect.cariqa.com/api/v1/users/9405cf8c-8375-4373-b4d3-b61f9a0c01eb/charging-sessions/ab7ae756-b663-43b9-a025-40c51dd503d9/', { headers: { 'Authorization': 'Bearer YOUR_API_TOKEN', 'Content-Type': 'application/json' } }); const finalSession = await response.json(); ``` **CDR-Enhanced Response:** ```json theme={null} { "id": "ab7ae756-b663-43b9-a025-40c51dd503d9", "start_time": "2026-04-02T13:51:18.754610Z", "end_time": "2026-04-02T13:51:28.754611Z", "duration": 10, "consumed_energy": "10.000", "is_active": false, "evse_id": "DE*CIQ*EELDF6XWZU41P*2", "station_info": { "station_name": "EVA Charge", "station_address": "Ludwigstraße, 9, 67547, Worms", "country": "DE", "station_speed": "slow", "connector_standard": "IEC_62196_T2", "connector_power": 22, "support_phone": "+4971134214480", "latitude": "49.630383", "longitude": "8.368902" }, "is_partner": true, "logo_url": "https://storage.googleapis.com/cariqa-cpo-logos/evacharge.png?generation=1739874740770603&md5_hash=8dcf9c9d17149760b1c9033218ed1c19&size=11759", "user_facing_session_prices": { "kwh_price": "0.54", "time_price": null, "session_fee": null, "blocking_fee": null, "starting_fee": null, "grace_period_minutes": null, "blocking_cap": null, "currency": "eur" }, "session_cost": { "kwh_cost": "5.39", "time_cost": "0.00", "session_fee_cost": "0.00", "blocking_fee_cost": "0.00", "starting_fee_cost": "0.00", "invoice_download": "https://connect.cariqa.com/download/?", "invoice_vat": "0.86", "invoice_summary": "5.39", "invoice_credits": "0.00", "invoice_discount": "0.00", "currency": "eur" }, "rates": 5 } ``` ### Session Status Tracking The charging session lifecycle is managed through several key fields that change as the session progresses from start to completion: **Session Lifecycle States:** 1. **Session Initiated** (Start Command Sent): ```json theme={null} { "is_active": true, "end_time": null, "consumed_energy": "0.000", "session_cost": null } ``` 2. **Active Charging** (Energy Consumption Updates): ```json theme={null} { "is_active": true, "end_time": null, "consumed_energy": "5.420", "session_cost": null } ``` 3. **Stop Command Sent** (Manual or Automatic): ```json theme={null} { "is_active": false, "end_time": null, "consumed_energy": "8.750", "session_cost": null } ``` 4. **CDR Received and Processed** (Final State): ```json theme={null} { "is_active": false, "end_time": "2026-04-02T13:51:28.754611Z", "consumed_energy": "10.000", "payg_summary": { "kwh_cost": "5.39", "time_cost": "0.00", "session_fee_cost": "0.00", "blocking_fee_cost": "0.00", "starting_fee_cost": "0.00", "invoice_download": "https://connect.cariqa.com/download/?", "invoice_vat": "0.86", "invoice_summary": "5.39", "invoice_credits": "0.00", "invoice_discount": "0.00", "currency": "eur" } } ``` **Recommendations:** * Poll every 10-30 seconds while `is_active: true` for real-time updates * Continue polling after `is_active: false` until `end_time` is populated but with extended period * Session is complete when `end_time` is not null * Check error handling guide for [Start Charging Session](/start-charging-errors-handling) and [Stop Charging Session](/stop-charging-errors-handling). # Invoices Source: https://docs.cariqa.com/patterns-invoices Usage patterns for retrieving user invoices ## Invoices History and Details ### List User's Invoices ```bash cURL theme={null} curl -X GET "https://connect.cariqa.com/api/v1/users/9405cf8c-8375-4373-b4d3-b61f9a0c01eb/invoices/" \ -H "Authorization: Bearer YOUR_API_TOKEN" \ -H "Content-Type: application/json" ``` ```python Python theme={null} import requests headers = { "Authorization": "Bearer YOUR_API_TOKEN", "Content-Type": "application/json" } response = requests.get( "https://connect.cariqa.com/api/v1/users/9405cf8c-8375-4373-b4d3-b61f9a0c01eb/invoices/", headers=headers ) ``` ```javascript JavaScript theme={null} const response = await fetch('https://connect.cariqa.com/api/v1/users/9405cf8c-8375-4373-b4d3-b61f9a0c01eb/invoices/', { headers: { 'Authorization': 'Bearer YOUR_API_TOKEN', 'Content-Type': 'application/json' } }); ``` Response includes comprehensive invoice data: ```json theme={null} { "size": 1, "next_page_id": null, "prev_page_id": null, "data": [ { "view_link": "https://invoice.stripe.com/i/acct_1LKJg9HtgZxQ1KXx/test_YWNjdF8xTEtKZzlIdGdaeFExS1h4LF9VR0lGVXZ1ckhJRFlMaTJPZVoyTzR3R1dsbE81NXJaLDE2NTY3ODcyNA02000P98cfsJ?s=ap", "link": "https://pay.stripe.com/invoice/acct_1LKJg9HtgZxQ1KXx/test_YWNjdF8xTEtKZzlIdGdaeFExS1h4LF9VR0lGVXZ1ckhJRFlMaTJPZVoyTzR3R1dsbE81NXJaLDE2NTY3ODcyNA02000P98cfsJ/pdf?s=ap", "total": "5.39", "date": "2026-04-02T13:52:35Z", "refund": false, "currency": "eur", "charging_session_id": "ab7ae756-b663-43b9-a025-40c51dd503d9" }, ] } ``` # Payment Methods Source: https://docs.cariqa.com/patterns-payments Usage patterns for Stripe payment method management ## Payment Method Setup Flow Payment methods must be added using [Stripe SDK and native UI elements](/payments-frontend-setup) for PSD2/SCA compliance. ### 1. Fetch Setup Intent ```bash cURL theme={null} curl -X GET "https://connect.cariqa.com/api/v1/users/9405cf8c-8375-4373-b4d3-b61f9a0c01eb/setup-intents/?pm_type=card" \ -H "Authorization: Bearer YOUR_API_TOKEN" \ -H "Content-Type: application/json" ``` ```python Python theme={null} import requests headers = { "Authorization": "Bearer YOUR_API_TOKEN", "Content-Type": "application/json" } response = requests.get( "https://connect.cariqa.com/api/v1/users/9405cf8c-8375-4373-b4d3-b61f9a0c01eb/setup-intents/?pm_type=card", headers=headers ) ``` ```javascript JavaScript theme={null} const response = await fetch('https://connect.cariqa.com/api/v1/users/9405cf8c-8375-4373-b4d3-b61f9a0c01eb/setup-intents/?pm_type=card', { headers: { 'Authorization': 'Bearer YOUR_API_TOKEN', 'Content-Type': 'application/json' } }); ``` Response: ```json theme={null} { "client_secret": "seti_1THkgXHtgZxQ1KXxOhLbYQKU_secret_UGHFCX0iihdboXkwx4QfiR9V2ma55vk" } ``` ### 2. Frontend Integration Initialize Stripe on the client using: * Stripe SDK with publishable key from onboarding * Native Stripe UI elements (required) * Complete payment method creation client-side ### 3. Confirm Setup with Stripe Use the `client_secret` to complete payment method attachment through Stripe SDK. ## Payment Method Management ### List User Payment Methods Common use cases: * Show saved cards in settings page * Let user choose default payment method * Allow payment method removal Response includes various payment types: `card`, `google_pay`, `apple_pay` ### List Payment Methods ```bash cURL theme={null} curl -X GET "https://connect.cariqa.com/api/v1/users/9405cf8c-8375-4373-b4d3-b61f9a0c01eb/payment-methods/" \ -H "Authorization: Bearer YOUR_API_TOKEN" \ -H "Content-Type: application/json" ``` ```python Python theme={null} import requests headers = {"Authorization": "Bearer YOUR_API_TOKEN"} response = requests.get( "https://connect.cariqa.com/api/v1/users/9405cf8c-8375-4373-b4d3-b61f9a0c01eb/payment-methods/", headers=headers ) ``` ```javascript JavaScript theme={null} const response = await fetch('https://connect.cariqa.com/api/v1/users/9405cf8c-8375-4373-b4d3-b61f9a0c01eb/payment-methods/', { method: 'GET', headers: { 'Authorization': 'Bearer YOUR_API_TOKEN' } }); ``` Response: ```json theme={null} { "count": 2, "next": null, "previous": null, "results": [ { "id": "pm_1TD1M3HtgZxQ1KXx5wMzfx15", "default": false, "type": "apple_pay", "card": { "brand": "visa", "last4": "4242", "expiration_date": "12/2027", "cardholder_name": "John Doe" }, "created_at": "2026-03-20T11:36:39Z" }, { "id": "pm_1TD1LuHtgZxQ1KXxNj5sKkKM", "default": true, "type": "card", "card": { "brand": "visa", "last4": "4242", "expiration_date": "04/2044", "cardholder_name": null }, "created_at": "2026-03-20T11:36:30Z" } ] } ``` ### Set Default Payment Method ```bash cURL theme={null} curl -X POST "https://connect.cariqa.com/api/v1/users/9405cf8c-8375-4373-b4d3-b61f9a0c01eb/payment-methods/pm_abc123/default/" \ -H "Authorization: Bearer YOUR_API_TOKEN" ``` ```python Python theme={null} import requests headers = {"Authorization": "Bearer YOUR_API_TOKEN"} response = requests.post( "https://connect.cariqa.com/api/v1/users/9405cf8c-8375-4373-b4d3-b61f9a0c01eb/payment-methods/pm_abc123/default/", headers=headers ) ``` ```javascript JavaScript theme={null} const response = await fetch('https://connect.cariqa.com/api/v1/users/9405cf8c-8375-4373-b4d3-b61f9a0c01eb/payment-methods/pm_abc123/default/', { method: 'POST', headers: { 'Authorization': 'Bearer YOUR_API_TOKEN' } }); ``` ### Remove Payment Method ```bash cURL theme={null} curl -X DELETE "https://connect.cariqa.com/api/v1/users/9405cf8c-8375-4373-b4d3-b61f9a0c01eb/payment-methods/pm_abc123/" \ -H "Authorization: Bearer YOUR_API_TOKEN" ``` ```python Python theme={null} import requests headers = {"Authorization": "Bearer YOUR_API_TOKEN"} response = requests.delete( "https://connect.cariqa.com/api/v1/users/9405cf8c-8375-4373-b4d3-b61f9a0c01eb/payment-methods/pm_abc123/", headers=headers ) ``` ```javascript JavaScript theme={null} const response = await fetch('https://connect.cariqa.com/api/v1/users/9405cf8c-8375-4373-b4d3-b61f9a0c01eb/payment-methods/pm_abc123/', { method: 'DELETE', headers: { 'Authorization': 'Bearer YOUR_API_TOKEN' } }); ``` ## Removal Restrictions Payment method removal may fail if: * Charging session is in progress * Payment method is attached to active session * Payment method is set as default * Active charging session present * CDR processing incomplete * User debt exists (402 Payment Required) # Outstanding payments Source: https://docs.cariqa.com/patterns-payments-outstanding Users may occasionally encounter a situation where the backend is unable to charge the payment method and the user has to perform client-side payment confirmation.
This occurs if the pre-authorization amount is insufficient to cover the final cost, or if a remote charge fails for reasons such as insufficient funds or a requirement for 3D Secure (3DS) user confirmation. In these cases, the platform will block specific operations and return a **402** error status code from various endpoints: 1. [Start charging](https://docs.cariqa.com/api-reference/charging-sessions/start-charging-session) 2. [Delete payment method](https://docs.cariqa.com/api-reference/payments/delete-payment-method) 3. [Soft-delete user](https://docs.cariqa.com/api-reference/users/soft-delete-user) After receiving these error statuses, the backend can request the [List Charging Debts endpoint](https://docs.cariqa.com/api-reference/debts/list-charging-debts) to get a **200** status code response with a `payment_intent_client_secret`: ```json theme={null} { "count": 1, "next": null, "previous": null, "results": [ { "session_id": "77c3290c-3bb7-4e66-9598-a22688909bac", "payment_intent_client_secret": "pi_3U3xkHHtgZxQ1KXx0MYJq3tK_secret_hrTOjCju9rCKoYncqW9rvoh5p", "amount": "5.50", "currency": "eur" } ] } ``` 4. It's also possible to get a `payment_intent_client_secret` as part of a **402** error response for a failed pre-authorization (see [Start charging error handling guide](https://docs.cariqa.com/start-charging-errors-handling)). ### Client-side payment confirmation To resolve the payment, initialize the frontend Stripe SDK using the publishable key provided during onboarding. Provide the `payment_intent_client_secret` and payment method ID to the respective SDK methods: [Android](https://stripe.dev/stripe-android/payments-core/com.stripe.android/-stripe/confirm-payment.html): confirmPayment(...) [iOS](https://stripe.dev/stripe-ios/stripe/documentation/stripe/stppaymenthandler/confirmpaymentintent\(params:authenticationcontext:\)): confirmPaymentIntent(...) [Web](https://docs.stripe.com/js/payment_intents/confirm_card_payment): confirmCardPayment(...) The SDK will automatically redirect the user to their bank issuer's portal to complete the authentication process.
It may skip 3DS and complete the payment immediately (testable with the \*4242 card in development mode) # Station Discovery Source: https://docs.cariqa.com/patterns-stations Usage patterns for station discovery and visualization endpoints Station endpoints are general lookup endpoints that are **not tied to specific users**. They provide three primary ways to access charging station information. ## Map Rendering Flow Use the tile endpoint for map-based station visualization and clustering. ```bash cURL theme={null} curl -X GET "https://connect.cariqa.com/api/v1/stations/tile/?x=274332&y=178643&z=19&only_partners=true" \ -H "Authorization: Bearer YOUR_API_TOKEN" \ -H "Content-Type: application/json" ``` ```python Python theme={null} import requests headers = { "Authorization": "Bearer YOUR_API_TOKEN", "Content-Type": "application/json" } response = requests.get( "https://connect.cariqa.com/api/v1/stations/tile/", headers=headers, params={ "z": 19, "x": 274332, "y": 178643, "only_partners": "true" } ) ``` ```javascript JavaScript theme={null} const response = await fetch('https://connect.cariqa.com/api/v1/stations/tile/?x=274332&y=178643&z=19&only_partners=true', { headers: { 'Authorization': 'Bearer YOUR_API_TOKEN', 'Content-Type': 'application/json' } }); ``` Response includes station features and clusters for map rendering: ```json theme={null} { "type": "FeatureCollection", "features": [ { "type": "Feature", "station_id": "8125a4fb3197c72f9db92c8c2253e9dd", "geometry": { "type": "Point", "coordinates": [ "49.630383", "8.368902" ] }, "properties": { "count": 1, "speed": "slow", "status": "free", "operator_id": "EVA Charge" }, "custom_properties": { "is_partner": true, }, "price_properties": { "price": "0.2", "type": "charging_price", "currency": "eur" } }, { "type": "Feature", "cluster_id": "07b3c818cedbbe34b2568cd7d84069f1", "geometry": { "type": "Point", "coordinates": [ "43.630383", "7.368902" ] }, "properties": { "count": 42, "expansion_zoom": 14 } } ] } ``` ## Detail View Flow Get complete station information when displaying station details. ```bash cURL theme={null} curl -X GET "https://connect.cariqa.com/api/v1/stations/details/?type=evse_id&id=DE*CIQ*EELDF6XWZU41P*1" \ -H "Authorization: Bearer YOUR_API_TOKEN" \ -H "Content-Type: application/json" ``` ```python Python theme={null} import requests headers = { "Authorization": "Bearer YOUR_API_TOKEN", "Content-Type": "application/json" } response = requests.get( "https://connect.cariqa.com/api/v1/stations/details/", headers=headers, params={ "type": "evse_id", "id": "DE*CIQ*EELDF6XWZU41P*1" } ) ``` ```javascript JavaScript theme={null} const response = await fetch('https://connect.cariqa.com/api/v1/stations/details/?type=evse_id&id=DE*CIQ*EELDF6XWZU41P*1', { headers: { 'Authorization': 'Bearer YOUR_API_TOKEN', 'Content-Type': 'application/json' } }); ``` Response provides the same comprehensive station data structure as the nearby search, including all connector details, pricing information, and operational status: ```json expandable theme={null} { "id": "8125a4fb3197c72f9db92c8c2253e9dd", "name": "EVA Charge", "speed": "slow", "address": "Ludwigstraße, 9, 67547, Worms", "status": "free", "coordinates": { "latitude": "49.630383", "longitude": "8.368902" }, "opening_times": { "twentyfourseven": true, "regular_hours": [] }, "operator": { "name": "EVA Charge", "contact": { "phone": "+4971134214480" } }, "evses": [ { "evse_id": "DE*CIQ*EELDF6XWZU41P*2", "status": "AVAILABLE" }, { "evse_id": "DE*CIQ*EWBNHHLM82TLA*2", "status": "AVAILABLE" }, { "evse_id": "DE*CIQ*EELDF6XWZU41P*1", "status": "AVAILABLE" }, { "evse_id": "DE*CIQ*EWBNHHLM82TLA*1", "status": "CHARGING" } ], "last_updated": "2026-04-02T10:42:22Z", "amenities": [], "is_partner": true, "price_groups": [ { "type": "IEC_62196_T2", "power": 22, "evse_ids": [ "DE*CIQ*EELDF6XWZU41P*2", "DE*CIQ*EWBNHHLM82TLA*2", "DE*CIQ*EELDF6XWZU41P*1", "DE*CIQ*EWBNHHLM82TLA*1" ], "prices": { "time_price": null, "kwh_price": { "MONDAY": [ { "time_from": "00:00", "time_to": "01:00", "date_from": "2025-12-17", "date_to": null, "gross_price": "0.1950", "user_facing_price": "0.23", "grace_period_minutes": null, "tax": 19, "blocking_cap": null }, { "time_from": "01:00", "time_to": "02:00", "date_from": "2025-12-17", "date_to": null, "gross_price": "0.1950", "user_facing_price": "0.23", "grace_period_minutes": null, "tax": 19, "blocking_cap": null }, { "time_from": "02:00", "time_to": "03:00", "date_from": "2025-12-17", "date_to": null, "gross_price": "0.1950", "user_facing_price": "0.23", "grace_period_minutes": null, "tax": 19, "blocking_cap": null }, { "time_from": "03:00", "time_to": "04:00", "date_from": "2025-12-17", "date_to": null, "gross_price": "0.1950", "user_facing_price": "0.23", "grace_period_minutes": null, "tax": 19, "blocking_cap": null }, { "time_from": "04:00", "time_to": "05:00", "date_from": "2025-12-17", "date_to": null, "gross_price": "0.1950", "user_facing_price": "0.23", "grace_period_minutes": null, "tax": 19, "blocking_cap": null }, { "time_from": "05:00", "time_to": "06:00", "date_from": "2025-12-17", "date_to": null, "gross_price": "0.1950", "user_facing_price": "0.23", "grace_period_minutes": null, "tax": 19, "blocking_cap": null }, { "time_from": "06:00", "time_to": "07:00", "date_from": "2025-12-17", "date_to": null, "gross_price": "0.1950", "user_facing_price": "0.23", "grace_period_minutes": null, "tax": 19, "blocking_cap": null }, { "time_from": "07:00", "time_to": "08:00", "date_from": "2025-12-17", "date_to": null, "gross_price": "0.1950", "user_facing_price": "0.23", "grace_period_minutes": null, "tax": 19, "blocking_cap": null }, { "time_from": "08:00", "time_to": "09:00", "date_from": "2025-12-17", "date_to": null, "gross_price": "0.1950", "user_facing_price": "0.23", "grace_period_minutes": null, "tax": 19, "blocking_cap": null }, { "time_from": "09:00", "time_to": "10:00", "date_from": "2025-12-17", "date_to": null, "gross_price": "0.1950", "user_facing_price": "0.23", "grace_period_minutes": null, "tax": 19, "blocking_cap": null }, { "time_from": "10:00", "time_to": "11:00", "date_from": "2025-12-17", "date_to": null, "gross_price": "0.1950", "user_facing_price": "0.23", "grace_period_minutes": null, "tax": 19, "blocking_cap": null }, { "time_from": "11:00", "time_to": "12:00", "date_from": "2025-12-17", "date_to": null, "gross_price": "0.1950", "user_facing_price": "0.23", "grace_period_minutes": null, "tax": 19, "blocking_cap": null }, { "time_from": "12:00", "time_to": "13:00", "date_from": "2025-12-17", "date_to": null, "gross_price": "0.1690", "user_facing_price": "0.20", "grace_period_minutes": null, "tax": 19, "blocking_cap": null }, { "time_from": "13:00", "time_to": "14:00", "date_from": "2025-12-17", "date_to": null, "gross_price": "0.1690", "user_facing_price": "0.20", "grace_period_minutes": null, "tax": 19, "blocking_cap": null }, { "time_from": "14:00", "time_to": "15:00", "date_from": "2025-12-17", "date_to": null, "gross_price": "0.1690", "user_facing_price": "0.20", "grace_period_minutes": null, "tax": 19, "blocking_cap": null }, { "time_from": "15:00", "time_to": "16:00", "date_from": "2025-12-17", "date_to": null, "gross_price": "0.1950", "user_facing_price": "0.23", "grace_period_minutes": null, "tax": 19, "blocking_cap": null }, { "time_from": "16:00", "time_to": "17:00", "date_from": "2025-12-17", "date_to": null, "gross_price": "0.1950", "user_facing_price": "0.23", "grace_period_minutes": null, "tax": 19, "blocking_cap": null }, { "time_from": "17:00", "time_to": "18:00", "date_from": "2025-12-17", "date_to": null, "gross_price": "0.1690", "user_facing_price": "0.20", "grace_period_minutes": null, "tax": 19, "blocking_cap": null }, { "time_from": "18:00", "time_to": "19:00", "date_from": "2025-12-17", "date_to": null, "gross_price": "0.1690", "user_facing_price": "0.20", "grace_period_minutes": null, "tax": 19, "blocking_cap": null }, { "time_from": "19:00", "time_to": "20:00", "date_from": "2025-12-17", "date_to": null, "gross_price": "0.1690", "user_facing_price": "0.20", "grace_period_minutes": null, "tax": 19, "blocking_cap": null }, { "time_from": "20:00", "time_to": "21:00", "date_from": "2025-12-17", "date_to": null, "gross_price": "0.1690", "user_facing_price": "0.20", "grace_period_minutes": null, "tax": 19, "blocking_cap": null }, { "time_from": "21:00", "time_to": "22:00", "date_from": "2025-12-17", "date_to": null, "gross_price": "0.1690", "user_facing_price": "0.20", "grace_period_minutes": null, "tax": 19, "blocking_cap": null }, { "time_from": "22:00", "time_to": "23:00", "date_from": "2025-12-17", "date_to": null, "gross_price": "0.1690", "user_facing_price": "0.20", "grace_period_minutes": null, "tax": 19, "blocking_cap": null }, { "time_from": "23:00", "time_to": "00:00", "date_from": "2025-12-17", "date_to": null, "gross_price": "0.1690", "user_facing_price": "0.20", "grace_period_minutes": null, "tax": 19, "blocking_cap": null } ], "TUESDAY": [ { "time_from": "00:00", "time_to": "01:00", "date_from": "2025-12-17", "date_to": null, "gross_price": "0.1690", "user_facing_price": "0.20", "grace_period_minutes": null, "tax": 19, "blocking_cap": null }, { "time_from": "01:00", "time_to": "02:00", "date_from": "2025-12-17", "date_to": null, "gross_price": "0.1690", "user_facing_price": "0.20", "grace_period_minutes": null, "tax": 19, "blocking_cap": null }, { "time_from": "02:00", "time_to": "03:00", "date_from": "2025-12-17", "date_to": null, "gross_price": "0.1690", "user_facing_price": "0.20", "grace_period_minutes": null, "tax": 19, "blocking_cap": null }, { "time_from": "03:00", "time_to": "04:00", "date_from": "2025-12-17", "date_to": null, "gross_price": "0.1690", "user_facing_price": "0.20", "grace_period_minutes": null, "tax": 19, "blocking_cap": null }, { "time_from": "04:00", "time_to": "05:00", "date_from": "2025-12-17", "date_to": null, "gross_price": "0.1690", "user_facing_price": "0.20", "grace_period_minutes": null, "tax": 19, "blocking_cap": null }, { "time_from": "05:00", "time_to": "06:00", "date_from": "2025-12-17", "date_to": null, "gross_price": "0.1690", "user_facing_price": "0.20", "grace_period_minutes": null, "tax": 19, "blocking_cap": null }, { "time_from": "06:00", "time_to": "07:00", "date_from": "2025-12-17", "date_to": null, "gross_price": "0.1690", "user_facing_price": "0.20", "grace_period_minutes": null, "tax": 19, "blocking_cap": null }, { "time_from": "07:00", "time_to": "08:00", "date_from": "2025-12-17", "date_to": null, "gross_price": "0.1690", "user_facing_price": "0.20", "grace_period_minutes": null, "tax": 19, "blocking_cap": null }, { "time_from": "08:00", "time_to": "09:00", "date_from": "2025-12-17", "date_to": null, "gross_price": "0.1690", "user_facing_price": "0.20", "grace_period_minutes": null, "tax": 19, "blocking_cap": null }, { "time_from": "09:00", "time_to": "10:00", "date_from": "2025-12-17", "date_to": null, "gross_price": "0.1690", "user_facing_price": "0.20", "grace_period_minutes": null, "tax": 19, "blocking_cap": null }, { "time_from": "10:00", "time_to": "11:00", "date_from": "2025-12-17", "date_to": null, "gross_price": "0.1690", "user_facing_price": "0.20", "grace_period_minutes": null, "tax": 19, "blocking_cap": null }, { "time_from": "11:00", "time_to": "12:00", "date_from": "2025-12-17", "date_to": null, "gross_price": "0.1690", "user_facing_price": "0.20", "grace_period_minutes": null, "tax": 19, "blocking_cap": null }, { "time_from": "12:00", "time_to": "13:00", "date_from": "2025-12-17", "date_to": null, "gross_price": "0.1690", "user_facing_price": "0.20", "grace_period_minutes": null, "tax": 19, "blocking_cap": null }, { "time_from": "13:00", "time_to": "14:00", "date_from": "2025-12-17", "date_to": null, "gross_price": "0.1690", "user_facing_price": "0.20", "grace_period_minutes": null, "tax": 19, "blocking_cap": null }, { "time_from": "14:00", "time_to": "15:00", "date_from": "2025-12-17", "date_to": null, "gross_price": "0.1690", "user_facing_price": "0.20", "grace_period_minutes": null, "tax": 19, "blocking_cap": null }, { "time_from": "15:00", "time_to": "16:00", "date_from": "2025-12-17", "date_to": null, "gross_price": "0.1690", "user_facing_price": "0.20", "grace_period_minutes": null, "tax": 19, "blocking_cap": null }, { "time_from": "16:00", "time_to": "17:00", "date_from": "2025-12-17", "date_to": null, "gross_price": "0.1690", "user_facing_price": "0.20", "grace_period_minutes": null, "tax": 19, "blocking_cap": null }, { "time_from": "17:00", "time_to": "18:00", "date_from": "2025-12-17", "date_to": null, "gross_price": "0.1690", "user_facing_price": "0.20", "grace_period_minutes": null, "tax": 19, "blocking_cap": null }, { "time_from": "18:00", "time_to": "19:00", "date_from": "2025-12-17", "date_to": null, "gross_price": "0.1690", "user_facing_price": "0.20", "grace_period_minutes": null, "tax": 19, "blocking_cap": null }, { "time_from": "19:00", "time_to": "20:00", "date_from": "2025-12-17", "date_to": null, "gross_price": "0.1950", "user_facing_price": "0.23", "grace_period_minutes": null, "tax": 19, "blocking_cap": null }, { "time_from": "20:00", "time_to": "21:00", "date_from": "2025-12-17", "date_to": null, "gross_price": "0.1690", "user_facing_price": "0.20", "grace_period_minutes": null, "tax": 19, "blocking_cap": null }, { "time_from": "21:00", "time_to": "22:00", "date_from": "2025-12-17", "date_to": null, "gross_price": "0.1690", "user_facing_price": "0.20", "grace_period_minutes": null, "tax": 19, "blocking_cap": null }, { "time_from": "22:00", "time_to": "23:00", "date_from": "2025-12-17", "date_to": null, "gross_price": "0.1690", "user_facing_price": "0.20", "grace_period_minutes": null, "tax": 19, "blocking_cap": null }, { "time_from": "23:00", "time_to": "00:00", "date_from": "2025-12-17", "date_to": null, "gross_price": "0.1690", "user_facing_price": "0.20", "grace_period_minutes": null, "tax": 19, "blocking_cap": null } ], "WEDNESDAY": [ { "time_from": "00:00", "time_to": "01:00", "date_from": "2025-12-17", "date_to": null, "gross_price": "0.1690", "user_facing_price": "0.20", "grace_period_minutes": null, "tax": 19, "blocking_cap": null }, { "time_from": "01:00", "time_to": "02:00", "date_from": "2025-12-17", "date_to": null, "gross_price": "0.1690", "user_facing_price": "0.20", "grace_period_minutes": null, "tax": 19, "blocking_cap": null }, { "time_from": "02:00", "time_to": "03:00", "date_from": "2025-12-17", "date_to": null, "gross_price": "0.1690", "user_facing_price": "0.20", "grace_period_minutes": null, "tax": 19, "blocking_cap": null }, { "time_from": "03:00", "time_to": "04:00", "date_from": "2025-12-17", "date_to": null, "gross_price": "0.1690", "user_facing_price": "0.20", "grace_period_minutes": null, "tax": 19, "blocking_cap": null }, { "time_from": "04:00", "time_to": "05:00", "date_from": "2025-12-17", "date_to": null, "gross_price": "0.1690", "user_facing_price": "0.20", "grace_period_minutes": null, "tax": 19, "blocking_cap": null }, { "time_from": "05:00", "time_to": "06:00", "date_from": "2025-12-17", "date_to": null, "gross_price": "0.1690", "user_facing_price": "0.20", "grace_period_minutes": null, "tax": 19, "blocking_cap": null }, { "time_from": "06:00", "time_to": "07:00", "date_from": "2025-12-17", "date_to": null, "gross_price": "0.1690", "user_facing_price": "0.20", "grace_period_minutes": null, "tax": 19, "blocking_cap": null }, { "time_from": "07:00", "time_to": "08:00", "date_from": "2025-12-17", "date_to": null, "gross_price": "0.1690", "user_facing_price": "0.20", "grace_period_minutes": null, "tax": 19, "blocking_cap": null }, { "time_from": "08:00", "time_to": "09:00", "date_from": "2025-12-17", "date_to": null, "gross_price": "0.1690", "user_facing_price": "0.20", "grace_period_minutes": null, "tax": 19, "blocking_cap": null }, { "time_from": "09:00", "time_to": "10:00", "date_from": "2025-12-17", "date_to": null, "gross_price": "0.1690", "user_facing_price": "0.20", "grace_period_minutes": null, "tax": 19, "blocking_cap": null }, { "time_from": "10:00", "time_to": "11:00", "date_from": "2025-12-17", "date_to": null, "gross_price": "0.1690", "user_facing_price": "0.20", "grace_period_minutes": null, "tax": 19, "blocking_cap": null }, { "time_from": "11:00", "time_to": "12:00", "date_from": "2025-12-17", "date_to": null, "gross_price": "0.1690", "user_facing_price": "0.20", "grace_period_minutes": null, "tax": 19, "blocking_cap": null }, { "time_from": "12:00", "time_to": "13:00", "date_from": "2025-12-17", "date_to": null, "gross_price": "0.1690", "user_facing_price": "0.20", "grace_period_minutes": null, "tax": 19, "blocking_cap": null }, { "time_from": "13:00", "time_to": "14:00", "date_from": "2025-12-17", "date_to": null, "gross_price": "0.1690", "user_facing_price": "0.20", "grace_period_minutes": null, "tax": 19, "blocking_cap": null }, { "time_from": "14:00", "time_to": "15:00", "date_from": "2025-12-17", "date_to": null, "gross_price": "0.1690", "user_facing_price": "0.20", "grace_period_minutes": null, "tax": 19, "blocking_cap": null }, { "time_from": "15:00", "time_to": "16:00", "date_from": "2025-12-17", "date_to": null, "gross_price": "0.1690", "user_facing_price": "0.20", "grace_period_minutes": null, "tax": 19, "blocking_cap": null }, { "time_from": "16:00", "time_to": "17:00", "date_from": "2025-12-17", "date_to": null, "gross_price": "0.1690", "user_facing_price": "0.20", "grace_period_minutes": null, "tax": 19, "blocking_cap": null }, { "time_from": "17:00", "time_to": "18:00", "date_from": "2025-12-17", "date_to": null, "gross_price": "0.1690", "user_facing_price": "0.20", "grace_period_minutes": null, "tax": 19, "blocking_cap": null }, { "time_from": "18:00", "time_to": "19:00", "date_from": "2025-12-17", "date_to": null, "gross_price": "0.1690", "user_facing_price": "0.20", "grace_period_minutes": null, "tax": 19, "blocking_cap": null }, { "time_from": "19:00", "time_to": "20:00", "date_from": "2025-12-17", "date_to": null, "gross_price": "0.1690", "user_facing_price": "0.20", "grace_period_minutes": null, "tax": 19, "blocking_cap": null }, { "time_from": "20:00", "time_to": "21:00", "date_from": "2025-12-17", "date_to": null, "gross_price": "0.1690", "user_facing_price": "0.20", "grace_period_minutes": null, "tax": 19, "blocking_cap": null }, { "time_from": "21:00", "time_to": "22:00", "date_from": "2025-12-17", "date_to": null, "gross_price": "0.1690", "user_facing_price": "0.20", "grace_period_minutes": null, "tax": 19, "blocking_cap": null }, { "time_from": "22:00", "time_to": "23:00", "date_from": "2025-12-17", "date_to": null, "gross_price": "0.1690", "user_facing_price": "0.20", "grace_period_minutes": null, "tax": 19, "blocking_cap": null }, { "time_from": "23:00", "time_to": "00:00", "date_from": "2025-12-17", "date_to": null, "gross_price": "0.1690", "user_facing_price": "0.20", "grace_period_minutes": null, "tax": 19, "blocking_cap": null } ], "THURSDAY": [ { "time_from": "00:00", "time_to": "01:00", "date_from": "2025-12-17", "date_to": null, "gross_price": "0.1690", "user_facing_price": "0.20", "grace_period_minutes": null, "tax": 19, "blocking_cap": null }, { "time_from": "01:00", "time_to": "02:00", "date_from": "2025-12-17", "date_to": null, "gross_price": "0.1690", "user_facing_price": "0.20", "grace_period_minutes": null, "tax": 19, "blocking_cap": null }, { "time_from": "02:00", "time_to": "03:00", "date_from": "2025-12-17", "date_to": null, "gross_price": "0.1690", "user_facing_price": "0.20", "grace_period_minutes": null, "tax": 19, "blocking_cap": null }, { "time_from": "03:00", "time_to": "04:00", "date_from": "2025-12-17", "date_to": null, "gross_price": "0.1690", "user_facing_price": "0.20", "grace_period_minutes": null, "tax": 19, "blocking_cap": null }, { "time_from": "04:00", "time_to": "05:00", "date_from": "2025-12-17", "date_to": null, "gross_price": "0.1690", "user_facing_price": "0.20", "grace_period_minutes": null, "tax": 19, "blocking_cap": null }, { "time_from": "05:00", "time_to": "06:00", "date_from": "2025-12-17", "date_to": null, "gross_price": "0.1690", "user_facing_price": "0.20", "grace_period_minutes": null, "tax": 19, "blocking_cap": null }, { "time_from": "06:00", "time_to": "07:00", "date_from": "2025-12-17", "date_to": null, "gross_price": "0.1690", "user_facing_price": "0.20", "grace_period_minutes": null, "tax": 19, "blocking_cap": null }, { "time_from": "07:00", "time_to": "08:00", "date_from": "2025-12-17", "date_to": null, "gross_price": "0.1950", "user_facing_price": "0.23", "grace_period_minutes": null, "tax": 19, "blocking_cap": null }, { "time_from": "08:00", "time_to": "09:00", "date_from": "2025-12-17", "date_to": null, "gross_price": "0.1950", "user_facing_price": "0.23", "grace_period_minutes": null, "tax": 19, "blocking_cap": null }, { "time_from": "09:00", "time_to": "10:00", "date_from": "2025-12-17", "date_to": null, "gross_price": "0.1950", "user_facing_price": "0.23", "grace_period_minutes": null, "tax": 19, "blocking_cap": null }, { "time_from": "10:00", "time_to": "11:00", "date_from": "2025-12-17", "date_to": null, "gross_price": "0.1950", "user_facing_price": "0.23", "grace_period_minutes": null, "tax": 19, "blocking_cap": null }, { "time_from": "11:00", "time_to": "12:00", "date_from": "2025-12-17", "date_to": null, "gross_price": "0.1950", "user_facing_price": "0.23", "grace_period_minutes": null, "tax": 19, "blocking_cap": null }, { "time_from": "12:00", "time_to": "13:00", "date_from": "2025-12-17", "date_to": null, "gross_price": "0.1690", "user_facing_price": "0.20", "grace_period_minutes": null, "tax": 19, "blocking_cap": null }, { "time_from": "13:00", "time_to": "14:00", "date_from": "2025-12-17", "date_to": null, "gross_price": "0.1690", "user_facing_price": "0.20", "grace_period_minutes": null, "tax": 19, "blocking_cap": null }, { "time_from": "14:00", "time_to": "15:00", "date_from": "2025-12-17", "date_to": null, "gross_price": "0.1690", "user_facing_price": "0.20", "grace_period_minutes": null, "tax": 19, "blocking_cap": null }, { "time_from": "15:00", "time_to": "16:00", "date_from": "2025-12-17", "date_to": null, "gross_price": "0.1690", "user_facing_price": "0.20", "grace_period_minutes": null, "tax": 19, "blocking_cap": null }, { "time_from": "16:00", "time_to": "17:00", "date_from": "2025-12-17", "date_to": null, "gross_price": "0.1690", "user_facing_price": "0.20", "grace_period_minutes": null, "tax": 19, "blocking_cap": null }, { "time_from": "17:00", "time_to": "18:00", "date_from": "2025-12-17", "date_to": null, "gross_price": "0.1690", "user_facing_price": "0.20", "grace_period_minutes": null, "tax": 19, "blocking_cap": null }, { "time_from": "18:00", "time_to": "19:00", "date_from": "2025-12-17", "date_to": null, "gross_price": "0.1690", "user_facing_price": "0.20", "grace_period_minutes": null, "tax": 19, "blocking_cap": null }, { "time_from": "19:00", "time_to": "20:00", "date_from": "2025-12-17", "date_to": null, "gross_price": "0.1690", "user_facing_price": "0.20", "grace_period_minutes": null, "tax": 19, "blocking_cap": null }, { "time_from": "20:00", "time_to": "21:00", "date_from": "2025-12-17", "date_to": null, "gross_price": "0.1690", "user_facing_price": "0.20", "grace_period_minutes": null, "tax": 19, "blocking_cap": null }, { "time_from": "21:00", "time_to": "22:00", "date_from": "2025-12-17", "date_to": null, "gross_price": "0.1690", "user_facing_price": "0.20", "grace_period_minutes": null, "tax": 19, "blocking_cap": null }, { "time_from": "22:00", "time_to": "23:00", "date_from": "2025-12-17", "date_to": null, "gross_price": "0.1690", "user_facing_price": "0.20", "grace_period_minutes": null, "tax": 19, "blocking_cap": null }, { "time_from": "23:00", "time_to": "00:00", "date_from": "2025-12-17", "date_to": null, "gross_price": "0.1690", "user_facing_price": "0.20", "grace_period_minutes": null, "tax": 19, "blocking_cap": null } ], "FRIDAY": [ { "time_from": "00:00", "time_to": "01:00", "date_from": "2025-12-17", "date_to": null, "gross_price": "0.1690", "user_facing_price": "0.20", "grace_period_minutes": null, "tax": 19, "blocking_cap": null }, { "time_from": "01:00", "time_to": "02:00", "date_from": "2025-12-17", "date_to": null, "gross_price": "0.1950", "user_facing_price": "0.23", "grace_period_minutes": null, "tax": 19, "blocking_cap": null }, { "time_from": "02:00", "time_to": "03:00", "date_from": "2025-12-17", "date_to": null, "gross_price": "0.1950", "user_facing_price": "0.23", "grace_period_minutes": null, "tax": 19, "blocking_cap": null }, { "time_from": "03:00", "time_to": "04:00", "date_from": "2025-12-17", "date_to": null, "gross_price": "0.1950", "user_facing_price": "0.23", "grace_period_minutes": null, "tax": 19, "blocking_cap": null }, { "time_from": "04:00", "time_to": "05:00", "date_from": "2025-12-17", "date_to": null, "gross_price": "0.1950", "user_facing_price": "0.23", "grace_period_minutes": null, "tax": 19, "blocking_cap": null }, { "time_from": "05:00", "time_to": "06:00", "date_from": "2025-12-17", "date_to": null, "gross_price": "0.1950", "user_facing_price": "0.23", "grace_period_minutes": null, "tax": 19, "blocking_cap": null }, { "time_from": "06:00", "time_to": "07:00", "date_from": "2025-12-17", "date_to": null, "gross_price": "0.1950", "user_facing_price": "0.23", "grace_period_minutes": null, "tax": 19, "blocking_cap": null }, { "time_from": "07:00", "time_to": "08:00", "date_from": "2025-12-17", "date_to": null, "gross_price": "0.1950", "user_facing_price": "0.23", "grace_period_minutes": null, "tax": 19, "blocking_cap": null }, { "time_from": "08:00", "time_to": "09:00", "date_from": "2025-12-17", "date_to": null, "gross_price": "0.1950", "user_facing_price": "0.23", "grace_period_minutes": null, "tax": 19, "blocking_cap": null }, { "time_from": "09:00", "time_to": "10:00", "date_from": "2025-12-17", "date_to": null, "gross_price": "0.1950", "user_facing_price": "0.23", "grace_period_minutes": null, "tax": 19, "blocking_cap": null }, { "time_from": "10:00", "time_to": "11:00", "date_from": "2025-12-17", "date_to": null, "gross_price": "0.1950", "user_facing_price": "0.23", "grace_period_minutes": null, "tax": 19, "blocking_cap": null }, { "time_from": "11:00", "time_to": "12:00", "date_from": "2025-12-17", "date_to": null, "gross_price": "0.1950", "user_facing_price": "0.23", "grace_period_minutes": null, "tax": 19, "blocking_cap": null }, { "time_from": "12:00", "time_to": "13:00", "date_from": "2025-12-17", "date_to": null, "gross_price": "0.1950", "user_facing_price": "0.23", "grace_period_minutes": null, "tax": 19, "blocking_cap": null }, { "time_from": "13:00", "time_to": "14:00", "date_from": "2025-12-17", "date_to": null, "gross_price": "0.1690", "user_facing_price": "0.20", "grace_period_minutes": null, "tax": 19, "blocking_cap": null }, { "time_from": "14:00", "time_to": "15:00", "date_from": "2025-12-17", "date_to": null, "gross_price": "0.1690", "user_facing_price": "0.20", "grace_period_minutes": null, "tax": 19, "blocking_cap": null }, { "time_from": "15:00", "time_to": "16:00", "date_from": "2025-12-17", "date_to": null, "gross_price": "0.1690", "user_facing_price": "0.20", "grace_period_minutes": null, "tax": 19, "blocking_cap": null }, { "time_from": "16:00", "time_to": "17:00", "date_from": "2025-12-17", "date_to": null, "gross_price": "0.1690", "user_facing_price": "0.20", "grace_period_minutes": null, "tax": 19, "blocking_cap": null }, { "time_from": "17:00", "time_to": "18:00", "date_from": "2025-12-17", "date_to": null, "gross_price": "0.1690", "user_facing_price": "0.20", "grace_period_minutes": null, "tax": 19, "blocking_cap": null }, { "time_from": "18:00", "time_to": "19:00", "date_from": "2025-12-17", "date_to": null, "gross_price": "0.1690", "user_facing_price": "0.20", "grace_period_minutes": null, "tax": 19, "blocking_cap": null }, { "time_from": "19:00", "time_to": "20:00", "date_from": "2025-12-17", "date_to": null, "gross_price": "0.1690", "user_facing_price": "0.20", "grace_period_minutes": null, "tax": 19, "blocking_cap": null }, { "time_from": "20:00", "time_to": "21:00", "date_from": "2025-12-17", "date_to": null, "gross_price": "0.1690", "user_facing_price": "0.20", "grace_period_minutes": null, "tax": 19, "blocking_cap": null }, { "time_from": "21:00", "time_to": "22:00", "date_from": "2025-12-17", "date_to": null, "gross_price": "0.1690", "user_facing_price": "0.20", "grace_period_minutes": null, "tax": 19, "blocking_cap": null }, { "time_from": "22:00", "time_to": "23:00", "date_from": "2025-12-17", "date_to": null, "gross_price": "0.1690", "user_facing_price": "0.20", "grace_period_minutes": null, "tax": 19, "blocking_cap": null }, { "time_from": "23:00", "time_to": "00:00", "date_from": "2025-12-17", "date_to": null, "gross_price": "0.1690", "user_facing_price": "0.20", "grace_period_minutes": null, "tax": 19, "blocking_cap": null } ], "SATURDAY": [ { "time_from": "00:00", "time_to": "01:00", "date_from": "2025-12-17", "date_to": null, "gross_price": "0.1950", "user_facing_price": "0.23", "grace_period_minutes": null, "tax": 19, "blocking_cap": null }, { "time_from": "01:00", "time_to": "02:00", "date_from": "2025-12-17", "date_to": null, "gross_price": "0.1950", "user_facing_price": "0.23", "grace_period_minutes": null, "tax": 19, "blocking_cap": null }, { "time_from": "02:00", "time_to": "03:00", "date_from": "2025-12-17", "date_to": null, "gross_price": "0.1950", "user_facing_price": "0.23", "grace_period_minutes": null, "tax": 19, "blocking_cap": null }, { "time_from": "03:00", "time_to": "04:00", "date_from": "2025-12-17", "date_to": null, "gross_price": "0.1950", "user_facing_price": "0.23", "grace_period_minutes": null, "tax": 19, "blocking_cap": null }, { "time_from": "04:00", "time_to": "05:00", "date_from": "2025-12-17", "date_to": null, "gross_price": "0.1950", "user_facing_price": "0.23", "grace_period_minutes": null, "tax": 19, "blocking_cap": null }, { "time_from": "05:00", "time_to": "06:00", "date_from": "2025-12-17", "date_to": null, "gross_price": "0.1950", "user_facing_price": "0.23", "grace_period_minutes": null, "tax": 19, "blocking_cap": null }, { "time_from": "06:00", "time_to": "07:00", "date_from": "2025-12-17", "date_to": null, "gross_price": "0.1950", "user_facing_price": "0.23", "grace_period_minutes": null, "tax": 19, "blocking_cap": null }, { "time_from": "07:00", "time_to": "08:00", "date_from": "2025-12-17", "date_to": null, "gross_price": "0.1950", "user_facing_price": "0.23", "grace_period_minutes": null, "tax": 19, "blocking_cap": null }, { "time_from": "08:00", "time_to": "09:00", "date_from": "2025-12-17", "date_to": null, "gross_price": "0.1950", "user_facing_price": "0.23", "grace_period_minutes": null, "tax": 19, "blocking_cap": null }, { "time_from": "09:00", "time_to": "10:00", "date_from": "2025-12-17", "date_to": null, "gross_price": "0.1950", "user_facing_price": "0.23", "grace_period_minutes": null, "tax": 19, "blocking_cap": null }, { "time_from": "10:00", "time_to": "11:00", "date_from": "2025-12-17", "date_to": null, "gross_price": "0.1690", "user_facing_price": "0.20", "grace_period_minutes": null, "tax": 19, "blocking_cap": null }, { "time_from": "11:00", "time_to": "12:00", "date_from": "2025-12-17", "date_to": null, "gross_price": "0.1690", "user_facing_price": "0.20", "grace_period_minutes": null, "tax": 19, "blocking_cap": null }, { "time_from": "12:00", "time_to": "13:00", "date_from": "2025-12-17", "date_to": null, "gross_price": "0.1690", "user_facing_price": "0.20", "grace_period_minutes": null, "tax": 19, "blocking_cap": null }, { "time_from": "13:00", "time_to": "14:00", "date_from": "2025-12-17", "date_to": null, "gross_price": "0.1690", "user_facing_price": "0.20", "grace_period_minutes": null, "tax": 19, "blocking_cap": null }, { "time_from": "14:00", "time_to": "15:00", "date_from": "2025-12-17", "date_to": null, "gross_price": "0.1690", "user_facing_price": "0.20", "grace_period_minutes": null, "tax": 19, "blocking_cap": null }, { "time_from": "15:00", "time_to": "16:00", "date_from": "2025-12-17", "date_to": null, "gross_price": "0.1690", "user_facing_price": "0.20", "grace_period_minutes": null, "tax": 19, "blocking_cap": null }, { "time_from": "16:00", "time_to": "17:00", "date_from": "2025-12-17", "date_to": null, "gross_price": "0.1690", "user_facing_price": "0.20", "grace_period_minutes": null, "tax": 19, "blocking_cap": null }, { "time_from": "17:00", "time_to": "18:00", "date_from": "2025-12-17", "date_to": null, "gross_price": "0.1690", "user_facing_price": "0.20", "grace_period_minutes": null, "tax": 19, "blocking_cap": null }, { "time_from": "18:00", "time_to": "19:00", "date_from": "2025-12-17", "date_to": null, "gross_price": "0.1690", "user_facing_price": "0.20", "grace_period_minutes": null, "tax": 19, "blocking_cap": null }, { "time_from": "19:00", "time_to": "20:00", "date_from": "2025-12-17", "date_to": null, "gross_price": "0.1690", "user_facing_price": "0.20", "grace_period_minutes": null, "tax": 19, "blocking_cap": null }, { "time_from": "20:00", "time_to": "21:00", "date_from": "2025-12-17", "date_to": null, "gross_price": "0.1690", "user_facing_price": "0.20", "grace_period_minutes": null, "tax": 19, "blocking_cap": null }, { "time_from": "21:00", "time_to": "22:00", "date_from": "2025-12-17", "date_to": null, "gross_price": "0.1690", "user_facing_price": "0.20", "grace_period_minutes": null, "tax": 19, "blocking_cap": null }, { "time_from": "22:00", "time_to": "23:00", "date_from": "2025-12-17", "date_to": null, "gross_price": "0.1690", "user_facing_price": "0.20", "grace_period_minutes": null, "tax": 19, "blocking_cap": null }, { "time_from": "23:00", "time_to": "00:00", "date_from": "2025-12-17", "date_to": null, "gross_price": "0.1690", "user_facing_price": "0.20", "grace_period_minutes": null, "tax": 19, "blocking_cap": null } ], "SUNDAY": [ { "time_from": "00:00", "time_to": "01:00", "date_from": "2025-12-17", "date_to": null, "gross_price": "0.1950", "user_facing_price": "0.23", "grace_period_minutes": null, "tax": 19, "blocking_cap": null }, { "time_from": "01:00", "time_to": "02:00", "date_from": "2025-12-17", "date_to": null, "gross_price": "0.1950", "user_facing_price": "0.23", "grace_period_minutes": null, "tax": 19, "blocking_cap": null }, { "time_from": "02:00", "time_to": "03:00", "date_from": "2025-12-17", "date_to": null, "gross_price": "0.1950", "user_facing_price": "0.23", "grace_period_minutes": null, "tax": 19, "blocking_cap": null }, { "time_from": "03:00", "time_to": "04:00", "date_from": "2025-12-17", "date_to": null, "gross_price": "0.1950", "user_facing_price": "0.23", "grace_period_minutes": null, "tax": 19, "blocking_cap": null }, { "time_from": "04:00", "time_to": "05:00", "date_from": "2025-12-17", "date_to": null, "gross_price": "0.1950", "user_facing_price": "0.23", "grace_period_minutes": null, "tax": 19, "blocking_cap": null }, { "time_from": "05:00", "time_to": "06:00", "date_from": "2025-12-17", "date_to": null, "gross_price": "0.1950", "user_facing_price": "0.23", "grace_period_minutes": null, "tax": 19, "blocking_cap": null }, { "time_from": "06:00", "time_to": "07:00", "date_from": "2025-12-17", "date_to": null, "gross_price": "0.1950", "user_facing_price": "0.23", "grace_period_minutes": null, "tax": 19, "blocking_cap": null }, { "time_from": "07:00", "time_to": "08:00", "date_from": "2025-12-17", "date_to": null, "gross_price": "0.1950", "user_facing_price": "0.23", "grace_period_minutes": null, "tax": 19, "blocking_cap": null }, { "time_from": "08:00", "time_to": "09:00", "date_from": "2025-12-17", "date_to": null, "gross_price": "0.1950", "user_facing_price": "0.23", "grace_period_minutes": null, "tax": 19, "blocking_cap": null }, { "time_from": "09:00", "time_to": "10:00", "date_from": "2025-12-17", "date_to": null, "gross_price": "0.1950", "user_facing_price": "0.23", "grace_period_minutes": null, "tax": 19, "blocking_cap": null }, { "time_from": "10:00", "time_to": "11:00", "date_from": "2025-12-17", "date_to": null, "gross_price": "0.1950", "user_facing_price": "0.23", "grace_period_minutes": null, "tax": 19, "blocking_cap": null }, { "time_from": "11:00", "time_to": "12:00", "date_from": "2025-12-17", "date_to": null, "gross_price": "0.1950", "user_facing_price": "0.23", "grace_period_minutes": null, "tax": 19, "blocking_cap": null }, { "time_from": "12:00", "time_to": "13:00", "date_from": "2025-12-17", "date_to": null, "gross_price": "0.1950", "user_facing_price": "0.23", "grace_period_minutes": null, "tax": 19, "blocking_cap": null }, { "time_from": "13:00", "time_to": "14:00", "date_from": "2025-12-17", "date_to": null, "gross_price": "0.1950", "user_facing_price": "0.23", "grace_period_minutes": null, "tax": 19, "blocking_cap": null }, { "time_from": "14:00", "time_to": "15:00", "date_from": "2025-12-17", "date_to": null, "gross_price": "0.1950", "user_facing_price": "0.23", "grace_period_minutes": null, "tax": 19, "blocking_cap": null }, { "time_from": "15:00", "time_to": "16:00", "date_from": "2025-12-17", "date_to": null, "gross_price": "0.1950", "user_facing_price": "0.23", "grace_period_minutes": null, "tax": 19, "blocking_cap": null }, { "time_from": "16:00", "time_to": "17:00", "date_from": "2025-12-17", "date_to": null, "gross_price": "0.1950", "user_facing_price": "0.23", "grace_period_minutes": null, "tax": 19, "blocking_cap": null }, { "time_from": "17:00", "time_to": "18:00", "date_from": "2025-12-17", "date_to": null, "gross_price": "0.1690", "user_facing_price": "0.20", "grace_period_minutes": null, "tax": 19, "blocking_cap": null }, { "time_from": "18:00", "time_to": "19:00", "date_from": "2025-12-17", "date_to": null, "gross_price": "0.1690", "user_facing_price": "0.20", "grace_period_minutes": null, "tax": 19, "blocking_cap": null }, { "time_from": "19:00", "time_to": "20:00", "date_from": "2025-12-17", "date_to": null, "gross_price": "0.1690", "user_facing_price": "0.20", "grace_period_minutes": null, "tax": 19, "blocking_cap": null }, { "time_from": "20:00", "time_to": "21:00", "date_from": "2025-12-17", "date_to": null, "gross_price": "0.1690", "user_facing_price": "0.20", "grace_period_minutes": null, "tax": 19, "blocking_cap": null }, { "time_from": "21:00", "time_to": "22:00", "date_from": "2025-12-17", "date_to": null, "gross_price": "0.1690", "user_facing_price": "0.20", "grace_period_minutes": null, "tax": 19, "blocking_cap": null }, { "time_from": "22:00", "time_to": "23:00", "date_from": "2025-12-17", "date_to": null, "gross_price": "0.1950", "user_facing_price": "0.23", "grace_period_minutes": null, "tax": 19, "blocking_cap": null }, { "time_from": "23:00", "time_to": "00:00", "date_from": "2025-12-17", "date_to": null, "gross_price": "0.1950", "user_facing_price": "0.23", "grace_period_minutes": null, "tax": 19, "blocking_cap": null } ] }, "blocking_fee": { "ALL": [ { "time_from": null, "time_to": null, "date_from": "2025-12-17", "date_to": null, "gross_price": "4.02", "user_facing_price": "0.08", "grace_period_minutes": 0, "tax": 19, "blocking_cap": null } ] }, "session_fee": null, "starting_fee": null }, "local_datetime": "2026-04-02T12:42:22.671636+02:00", "currency": "eur", "pre_authorization_amount": "30.00", "is_fallback": false } ], "logo_url": "https://storage.googleapis.com/cariqa-cpo-logos/custom_evacharge_dev_station_logo.png?generation=1766404007574021&md5_hash=e1e6197d26b8de242509afbbdd66a71a&size=4150" } ``` ## Nearby Search Flow Find stations around a specific location for location-based discovery. ```bash cURL theme={null} curl -X GET "https://connect.cariqa.com/api/v1/stations/around/?latitude=49.630383&longitude=8.368902&distance=10" \ -H "Authorization: Bearer YOUR_API_TOKEN" \ -H "Content-Type: application/json" ``` ```python Python theme={null} import requests headers = { "Authorization": "Bearer YOUR_API_TOKEN", "Content-Type": "application/json" } response = requests.get( "https://connect.cariqa.com/api/v1/stations/around/", headers=headers, params={ "latitude": 49.630383, "longitude": 8.368902, "distance": 10 } ) ``` ```javascript JavaScript theme={null} const response = await fetch('https://connect.cariqa.com/api/v1/stations/around/?latitude=49.630383&longitude=8.368902&distance=10', { headers: { 'Authorization': 'Bearer YOUR_API_TOKEN', 'Content-Type': 'application/json' } }); ``` Response provides detailed station information with pricing and availability: ```json theme={null} { "count": 1, "next": null, "previous": null, "results": [ { "id": "8125a4fb3197c72f9db92c8c2253e9dd", "name": "EVA Charge", "speed": "slow", "address": "Ludwigstraße, 9, 67547, Worms", ... } ] } ``` ## Key Station Data * **Station Information**: Complete location details, operator info, and contact information * **EVSE Status**: Real-time availability status for each charging point * **Pricing Details**: Comprehensive pricing structure including parking fees and session fees * **Technical Specifications**: Connector types, power levels, and charging speeds * **Partner Status**: Whether the station is a direct partner for revenue sharing # User Management Source: https://docs.cariqa.com/patterns-users Usage patterns for user management endpoints ## User Creation and Management Flow All user-related operations require users to be created first in the system. ### Create User ```bash cURL theme={null} curl -X POST "https://connect.cariqa.com/api/v1/users/" \ -H "Authorization: Bearer YOUR_API_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "email": "user@example.com", "locale": "de", "custom_properties": { "external_id": "abcdefg123456" } }' ``` ```python Python theme={null} import requests headers = { "Authorization": "Bearer YOUR_API_TOKEN", "Content-Type": "application/json" } data = { "email": "user@example.com", "locale": "de", "custom_properties": { "external_id": "abcdefg123456" } } response = requests.post( "https://connect.cariqa.com/api/v1/users/", headers=headers, json=data ) ``` ```javascript JavaScript theme={null} const response = await fetch('https://connect.cariqa.com/api/v1/users/', { method: 'POST', headers: { 'Authorization': 'Bearer YOUR_API_TOKEN', 'Content-Type': 'application/json' }, body: JSON.stringify({ email: 'user@example.com', locale: 'de', custom_properties: { 'external_id': 'abcdefg123456' } }) }); ``` Response: ```json theme={null} { "id": "72794486-bf87-44fb-9b74-5b8fed6c994d", "email": "user@example.com", "locale": "de", "external_id": { "external_id": "abcdefg123456" } } ``` ### List Users Before Selection ```bash cURL theme={null} curl -X GET "https://connect.cariqa.com/api/v1/users/" \ -H "Authorization: Bearer YOUR_API_TOKEN" \ -H "Content-Type: application/json" ``` ```python Python theme={null} import requests headers = { "Authorization": "Bearer YOUR_API_TOKEN", "Content-Type": "application/json" } response = requests.get( "https://connect.cariqa.com/api/v1/users/", headers=headers ) ``` ```javascript JavaScript theme={null} const response = await fetch('https://connect.cariqa.com/api/v1/users/', { headers: { 'Authorization': 'Bearer YOUR_API_TOKEN', 'Content-Type': 'application/json' } }); ``` Response: ```json theme={null} { "count": 3, "next": null, "previous": null, "results": [ { "id": "29b8c323-eaf8-487a-a43d-0d37dd7328f1", "email": "user1@example.com", "locale": "en", "custom_properties": null }, { "id": "72794486-bf87-44fb-9b74-5b8fed6c994d", "email": "user@example.com", "locale": "de", "custom_properties": { "external_id": "abcdefg123456" } }, { "id": "db48d284-d67b-4e71-9065-1ef0e1b062d0", "email": "user@example.com", "locale": "de", "custom_properties": { "external_id": null } } ] } ``` ### Retrieve User Details ```bash cURL theme={null} curl -X GET "https://connect.cariqa.com/api/v1/users/72794486-bf87-44fb-9b74-5b8fed6c994d/" \ -H "Authorization: Bearer YOUR_API_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "locale": "en" }' ``` ```python Python theme={null} import requests headers = { "Authorization": "Bearer YOUR_API_TOKEN", "Content-Type": "application/json" } response = requests.get( "https://connect.cariqa.com/api/v1/users/72794486-bf87-44fb-9b74-5b8fed6c994d/", headers=headers ) ``` ```javascript JavaScript theme={null} const response = await fetch('https://connect.cariqa.com/api/v1/users/72794486-bf87-44fb-9b74-5b8fed6c994d/', { method: 'GET', headers: { 'Authorization': 'Bearer YOUR_API_TOKEN', 'Content-Type': 'application/json' } }); ``` Response: ```json theme={null} { "id": "72794486-bf87-44fb-9b74-5b8fed6c994d", "email": "user@example.com", "locale": "de", "custom_properties": { "external_id": "abcdefg123456" } } ``` ### Update User Details ```bash cURL theme={null} curl -X PATCH "https://connect.cariqa.com/api/v1/users/72794486-bf87-44fb-9b74-5b8fed6c994d/" \ -H "Authorization: Bearer YOUR_API_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "locale": "en" }' ``` ```python Python theme={null} import requests headers = { "Authorization": "Bearer YOUR_API_TOKEN", "Content-Type": "application/json" } data = {"locale": "en"} response = requests.patch( "https://connect.cariqa.com/api/v1/users/72794486-bf87-44fb-9b74-5b8fed6c994d/", headers=headers, json=data ) ``` ```javascript JavaScript theme={null} const response = await fetch('https://connect.cariqa.com/api/v1/users/72794486-bf87-44fb-9b74-5b8fed6c994d/', { method: 'PATCH', headers: { 'Authorization': 'Bearer YOUR_API_TOKEN', 'Content-Type': 'application/json' }, body: JSON.stringify({ locale: 'en' }) }); ``` Response: ```json theme={null} { "id": "72794486-bf87-44fb-9b74-5b8fed6c994d", "email": "user@example.com", "locale": "en", "custom_properties": { "external_id": "abcdefg123456" } } ``` ### Soft Delete User ```bash cURL theme={null} curl -X DELETE "https://connect.cariqa.com/api/v1/users/72794486-bf87-44fb-9b74-5b8fed6c994d/" \ -H "Authorization: Bearer YOUR_API_TOKEN" \ -H "Content-Type: application/json" ``` ```python Python theme={null} import requests headers = { "Authorization": "Bearer YOUR_API_TOKEN", "Content-Type": "application/json" } response = requests.delete( "https://connect.cariqa.com/api/v1/users/72794486-bf87-44fb-9b74-5b8fed6c994d/", headers=headers ) ``` ```javascript JavaScript theme={null} const response = await fetch('https://connect.cariqa.com/api/v1/users/72794486-bf87-44fb-9b74-5b8fed6c994d/', { method: 'DELETE', headers: { 'Authorization': 'Bearer YOUR_API_TOKEN', 'Content-Type': 'application/json' } }); ``` ## Key Implementation Notes * **Client Scoping**: API automatically validates ownership - users are scoped to the authenticated client * **Email Uniqueness**: Email addresses are not unique across the system and are optional * **External id**: Set external ids of the users and use them to search users * **Soft Delete**: Users are marked as deleted but data is preserved for compliance * **Automatic Validation**: No need to manually verify user ownership before calling detail endpoints # Payments Frontend Setup Source: https://docs.cariqa.com/payments-frontend-setup The **Cariqa Connect API** eliminates the need to implement Stripe server-side logic. Consequently, you only need to configure Stripe for the frontend. This guide provides the high-level configuration required to handle the use cases supported by the platform, including the [**Playground Reference Client**](https://docs.cariqa.com/demo-playground). *** ## 1. Preamble: The Payment Lifecycle The Cariqa Platform operates on a **post-payment flow**. Although we utilize payment pre-authorization, the final charge may exceed this amount. Therefore, a user **must** have a valid payment method attached at: * The moment the session begins. * The moment the platform receives the Charge Detail Record (CDR) to bill the user for the actual usage. This ensures the platform can either return the unused pre-authorization amount or bill the user for any additional charges. *** ## 2. Intent Entities: Setup vs. Payment Stripe utilizes two primary entities to manage transaction flows: | Entity | Role | Description | | :----------------- | :------------ | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Setup Intent** | **Primary** | A user-specific token used to attach a payment method to Stripe. The Connect API generates this via the Stripe Admin API. Every user is required to add a payment method via this intent. | | **Payment Intent** | **Secondary** | A user-specific token for frontend-initiated payments. While Cariqa primarily uses backend billing (via Setup Intents), a Payment Intent is generated if a charge fails due to specific payment method restrictions (insufficient funds, 3DS confirmation, etc.). | *** ## 3. Production Implementation (setup intent) Stripe publishableKey (dev/prod modes) required for the front-end are provided during the onboarding process. The Stripe publishable key is public by design, so it's safe to expose in client apps. Even so, our strong recommendation is to fetch it from your backend at runtime rather than bundling it into the app. This keeps it ready for a hot-swap if it ever needs to be rotated — without having to re-release your mobile app. ### 🍏 Mobile iOS (Cards + Apple Pay) Refer to the [official Stripe Payment Sheet iOS guide](https://docs.stripe.com/payments/accept-a-payment?payment-ui=mobile\&platform=ios). The "Server-side" chapters are not required for this integration. * **[Set up Stripe (client-side)](https://docs.stripe.com/payments/accept-a-payment?payment-ui=mobile\&platform=ios#setup-client-side):** Install the SDK. * [**Collect payment details**](https://docs.stripe.com/payments/accept-a-payment?payment-ui=mobile\&platform=ios#ios-collect-payment-details) * **Payment Details:** You do **not** need to provide `customer` or `customerSessionClientSecret`. * **Intent Usage:** Use `setupIntent` instead of `paymentIntent` to add a payment method. * Skip `allowsDelayedPaymentMethods`. * Disable billing details collection in Stripe's UI. Instead, collect and display billing details in your own UI if needed. ```swift theme={null} configuration.billingDetailsCollectionConfiguration.name = .never configuration.billingDetailsCollectionConfiguration.email = .never configuration.billingDetailsCollectionConfiguration.phone = .never configuration.billingDetailsCollectionConfiguration.address = .never ``` * **[Set up a return URL](https://docs.stripe.com/payments/accept-a-payment?payment-ui=mobile\&platform=ios#ios-set-up-return-url):** Ensure a return URL is configured. * **[Enable Apple Pay](https://docs.stripe.com/payments/accept-a-payment?payment-ui=mobile\&platform=ios#ios-apple-pay):** * Certificate creation requires interaction with the Cariqa team. * We will provide the `stripe.certSigningRequest` for you to upload to the Apple Developer Portal. * Upload the resulting `apple_pay.cer` back to us to register it with Stripe. * Use the following item, adding your app name to the label: ```swift theme={null} paymentSummaryItems: [ PKPaymentSummaryItem( label: "Authorisation for Your App Name", amount: 0.00, type: .pending ) ] ``` * Skip "Recurring payments" tab. * Skip "Order tracking" chapter. * [**Enable card scanning:**](https://docs.stripe.com/payments/accept-a-payment?payment-ui=mobile\&platform=ios#ios-card-scanning) Optional, but without a permission description it may cause an error during App Store distribution. * **[Customize the sheet](https://docs.stripe.com/payments/accept-a-payment?payment-ui=mobile\&platform=ios#ios-customization):** Optional: apply the desired styling. * **[Handle user logout](https://docs.stripe.com/payments/accept-a-payment?payment-ui=mobile\&platform=ios#ios-logout):** Ensure you handle user logout correctly. ### 🤖 Mobile Android (Cards + Google Pay) Refer to the [official Stripe Payment Sheet Android guide](https://docs.stripe.com/payments/accept-a-payment?payment-ui=mobile\&platform=android). The "Server-side" chapters are not required. * **[Set up Stripe (client side)](https://docs.stripe.com/payments/accept-a-payment?payment-ui=mobile\&platform=android#setup-client-side):** Skip the `financial-connections` import. * [**Collect payment details**](https://docs.stripe.com/payments/accept-a-payment?payment-ui=mobile\&platform=android#android-collect-payment-details): * **Payment Details:** You do **not** need to provide `customer` or `customerSessionClientSecret`. * **Intent Usage:** Use `setupIntent` instead of `paymentIntent` to add a payment method. * Skip `allowsDelayedPaymentMethods`. * Disable billing details collection in Stripe's UI. Instead, collect and display billing details in your own UI if needed. ```kotlin theme={null} val billingDetailsConfig = PaymentSheet.BillingDetailsCollectionConfiguration( name = PaymentSheet.BillingDetailsCollectionConfiguration.CollectionMode.Never, email = PaymentSheet.BillingDetailsCollectionConfiguration.CollectionMode.Never, phone = PaymentSheet.BillingDetailsCollectionConfiguration.CollectionMode.Never, address = PaymentSheet.BillingDetailsCollectionConfiguration.AddressCollectionMode.Never ) ``` * **[Enable card scanner](https://docs.stripe.com/payments/accept-a-payment?payment-ui=mobile\&platform=android#android-card-scanning):** Skip this — it's marked as Public Preview. * **[Enable Google Pay](https://docs.stripe.com/payments/accept-a-payment?payment-ui=mobile\&platform=android#android-google-pay):** * Registration in the [Google Pay & Wallet Console](https://pay.google.com/business/console/) is required for production. * Review the [Google frontend integration guide](https://developers.google.com/pay/api/android/guides/setup). Passing Google Pay review is required to access production payments. * Use the following config, adding your app name to the label: ```kotlin theme={null} val googlePayConfiguration = PaymentSheet.GooglePayConfiguration( // ... countryCode = "DE", currencyCode = "EUR", amount = 0, label = "Authorisation for Your App Name" ) ``` * **Note:** Your app must be uploaded to at least the **Internal Track** in the Google Play Console to appear in the Google Pay Console. * **[Customize the sheet](https://docs.stripe.com/payments/accept-a-payment?payment-ui=mobile\&platform=android#android-customization):** Optional: apply the desired styling. * **[Handle user logout](https://docs.stripe.com/payments/accept-a-payment?payment-ui=mobile\&platform=android#android-logout):** Ensure you handle user logout correctly. ### 💻 Web (Cards + Google Pay) Stripe provides a dedicated guide for [Stripe Elements Guide](https://docs.stripe.com/payments/accept-a-payment?payment-ui=elements\&api-integration=paymentintents). As with other platforms, the server-side implementation chapters should be ignored.

**Credit Cards:** No specialized configuration is required.
**Apple/Google Pay:** You must share your production domain with the Cariqa team. * **[Collect payment details](https://docs.stripe.com/payments/accept-a-payment?payment-ui=elements\&api-integration=paymentintents#web-collect-payment-details):** * Skip `Collect addresses` * Skip `Request Apple Pay merchant token` * **[Apple Pay and Google Pay](https://docs.stripe.com/payments/accept-a-payment?payment-ui=elements\&api-integration=paymentintents#apple-pay-and-google-pay):** these payment methods are already enabled in the Stripe account — ensure they are added (or not disabled) in the PaymentElement initialization config. ### ⚛️ React Native Stripe provides a dedicated guide for [React Native](https://docs.stripe.com/payments/accept-a-payment?payment-ui=mobile\&platform=react-native). As with other platforms, the server-side implementation chapters should be ignored. *** ## 4. Testing the Integration Use the following test cards in the **DEV environment**. For Apple Pay and Google Pay, you can use a simulator or real device; no real charges will be made, and the card will be replaced with the `*4242` test card. | Card Number | Behavior | | :-------------------- | :--------------------------------------------------------------------------------------- | | `4242 4242 4242 4242` | Frictionless addition and payment. | | `4000 0027 6000 3184` | Requires manual **3DS confirmation** for both setup and payment (useful for edge cases). | [More Stripe testing cards here](https://docs.stripe.com/testing). *** ## 5. Manual Payment Confirmation (payment intent) If the backend fails to process a payment (e.g., due to insufficient funds or a requirement for user authentication), the frontend will receive a Payment Intent. This intent must then be passed to the Stripe SDK. For implementation details, refer to the [**Outstanding payments**](/patterns-payments-outstanding) documentation. # Quick Start Source: https://docs.cariqa.com/quickstart ## Obtain a Token The Cariqa Connect API uses **JWT-based Bearer tokens** for authentication. How to obtain it: 1. [Contact](mailto:sales@cariqa.com) our team for manual onboarding and provide the required information 2. We will send you: 1. API tokens for development and production environments 2. Stripe publishable key required for client-side payment method collection 3. We will also verify your domains for Apple Pay and Google Pay 4. Go ahead and make your first API request **You'll need to provide:** * Company details and use case * Technical contact information * Domain(s) for Apple Pay/Google Pay verification ### First API Request Once you get your API Token, store it securely and try your first API call ```bash cURL theme={null} curl -X GET "https://connect.cariqa.com/api/v1/stations/around/?latitude=49.630383&longitude=8.368902&distance=10" \ -H "Authorization: Bearer YOUR_API_TOKEN" \ -H "Content-Type: application/json" ``` ```python Python theme={null} import requests headers = { "Authorization": "Bearer YOUR_API_TOKEN", "Content-Type": "application/json" } response = requests.get( "https://connect.cariqa.com/api/v1/stations/around/", headers=headers, params={ "latitude": 49.630383, "longitude": 8.368902, "distance": 10 } ) ``` ```javascript JavaScript theme={null} const response = await fetch('https://connect.cariqa.com/api/v1/stations/around/?latitude=49.630383&longitude=8.368902&distance=10', { headers: { 'Authorization': 'Bearer YOUR_API_TOKEN', 'Content-Type': 'application/json' } }); ``` ### Stripe Integration The Stripe SDK must be integrated into your frontend application to allow users to securely add their favourite payment methods. This ensures compliance with PSD2/SCA requirements: payment details are handled and stored by Stripe, not Cariqa. **You must integrate [Stripe SDK on your frontend](/payments-frontend-setup): this is a hard requirement** for PSD2 compliance. ## Ready You are set! Explore the [API Reference ](/getting-started)or follow our [Guides](/complete-examples) and start integrating with Cariqa Connect API. Our support is always at your disposal in case of troubles (we recommend to check the [Toubleshooting](/troubleshooting) section first). # Start Charging Error Handling Source: https://docs.cariqa.com/start-charging-errors-handling Error handling reference for the Connect API start charging flow. # Start Charging Error Handling Starting a charging session is a multi-step process. Before the session can be created, the platform validates the customer state, checks the requested station and connector, verifies billing and payment readiness, performs payment pre-authorization, and sends the start command to the charging provider. Because this flow depends on both internal platform state and external charging infrastructure, a start request can fail for several reasons. This document describes the expected error responses that external customers should handle when calling the **Start Charging** endpoint. ## Error Response Format Most start charging errors are returned using the following structure: ``` json { "detail": "Charging Error", "error": { "type": "already_charging", "details": "User already has active charging session OR is starting charging" } } ``` Some errors may include additional fields inside `error`, for example a payment intent client secret when additional card authentication is required. ``` json { "detail": "Charging Error", "error": { "type": "pre_authorization_failed", "details": "We didn't manage to pre-authorize payment before starting charging. User should try again.", "payment_intent_client_secret": "pi_..." } } ``` *** # Status Codes ## `409 Conflict` The request is valid, but the charging session cannot be started because of the current customer, insufficient billing data, or connector state. ### Error type: `already_charging` The customer already has an active charging session, or another start charging request is already being processed. This can happen when: * The customer already has an active charging session. * The customer recently sent another start charging request and it is still being processed. Example response: ``` json { "detail": "Charging Error", "error": { "type": "already_charging", "details": "User already has active charging session OR is starting charging" } } ``` Recommended handling: * Do not retry immediately in a loop. * Refresh the customer’s active charging session state. * If no active session is visible yet, wait briefly and retry once. * Show the customer a message that a charging session is already active or starting. *** ### Error type: `billing_data_required` The customer’s billing data is missing, incomplete, or incorrectly configured. This can happen when: * Required billing profile data is missing. * Billing data exists but is incomplete. * Billing data cannot be used to issue invoices or process payments. Example response: ``` json { "detail": "Charging Error", "error": { "type": "billing_data_required", "details": "Billing data is partially/fully missing. or improperly configured" } } ``` Recommended handling: * Ask the customer to complete or update their billing information. * Do not retry start charging until the billing data has been corrected. *** ### Error type: `station_availability_issue` The selected connector is out of order. This can happen when: * The connector is marked as unavailable by the station operator. * The connector is temporarily out of service. * The connector cannot accept a new charging session. Example response: ``` json { "detail": "Charging Error", "error": { "type": "station_availability_issue", "details": "Connector you were trying to start charging is out of order" } } ``` Recommended handling: * Ask the customer to choose another connector at the same station. * If available, refresh station details before showing connector availability. * Do not retry the same connector immediately unless its status changes. *** ## `404 Not Found` The requested station or EVSE could not be found. This can happen when the provided `evse_id` does not exist or no longer available. Example response: ``` json { "detail": "Station with this evse id was not found" } ``` Recommended handling: * Verify that the `evse_id` is correct. * Refresh station data before allowing the customer to start charging. *** ## `402 Payment Required` The customer cannot start a new charging session because a payment-related action is required. ### Error type: `payment_error` The customer has an outstanding unpaid charging session or payment that must be completed before a new session can start. This can happen when: * A previous charging session has been unpaid. * A previous payment failed. * The customer must complete payment settlement before starting another session. Example response: ``` json { "detail": "Payment error", "error": { "type": "payment_error", "details": "There is an outstanding payment which user need to finish before starting new charging session" } } ``` Recommended handling: * Redirect the customer to the outstanding payments flow. * Require the outstanding payment to be completed before retrying start charging. * Do not keep retrying the start charging request until the debt is resolved. *** ### Error type: `pre_authorization_failed` The platform could not pre-authorize the customer’s payment method before starting the charging session. This can happen when: * The selected payment method was declined. * The payment provider returned a general pre-authorization failure. * The payment method is no longer valid. Example response without additional authentication data: ``` json { "detail": "Payment error", "error": { "type": "pre_authorization_failed", "details": "We didn't manage to pre-authorize payment before starting charging. User should try again." } } ``` Example response with additional authentication data: ``` json { "detail": "Payment error", "error": { "type": "pre_authorization_failed", "details": "We didn't manage to pre-authorize payment before starting charging. User should try again.", "payment_intent_client_secret": "pi_..." } } ``` Recommended handling: * If `payment_intent_client_secret` is present, use it to complete the required customer authentication. * If no client secret is present, ask the customer to retry or choose another payment method. * After successful authentication or payment method update, retry the start charging request. *** ## `424 Failed Dependency` The platform could not complete the start charging flow because an external dependency was unavailable or rejected the operation. ### Error type: `station_availability_issue` The platform could not fetch or validate station data. This can happen when: * Station data could not be fetched from an external system. * The station provider is temporarily unavailable. * The platform cannot reliably confirm station availability. Example response: ``` json { "detail": "Charging Error", "error": { "type": "station_availability_issue", "details": "We were not able to fetch station details for some reason. Try to change the input or try again a bit later" } } ``` Recommended handling: * Ask the customer to retry later. * Refresh station details before retrying. * If the issue persists, suggest choosing another station or connector. *** ### Error type: `charging_provider_error` The charging provider did not successfully start the charging session. This can happen when: * The external charging provider rejected the start request. * The provider could not process the start command. * Communication with the provider failed. Example response: ``` json { "detail": "Charging Error", "error": { "type": "charging_provider_error", "details": "Charging provider didn't manage to start charging" } } ``` Recommended handling: * Do not assume that charging has started. * Refresh the customer’s active session state. * If no session exists, allow the customer to retry after a short delay. * If the issue repeats, suggest using another connector or contacting support. *** ## `500 Internal Server Error` An unexpected internal error occurred while processing the start charging request. ### Error type: `unexpected_error` This can happen when: * An internal state transition failed. * An unexpected platform error occurred. * Required internal data could not be generated. * An unknown unhandled condition was reached. Example response: ``` json { "detail": "Charging Error", "error": { "type": "unexpected_error", "details": "We faced unexpected error. In case it wasn't resolved let us know. Code: 123e4567-e89b-12d3-a456-426614174000" } } ``` Or: ``` json { "detail": "Charging Error", "error": { "type": "unexpected_error", "details": "Internal error occurred. Please try again a bit later." } } ``` Recommended handling: * Do not assume that charging has started. * Refresh the active session state before allowing another start attempt. * If an error code is included, store it and provide it to support. * Show a generic error message to the customer and suggest trying again later. *** # Recommended Client-Side Handling When a start charging request fails: 1. Check the HTTP status code. 2. Check `error.type` when available. 3. Refresh the customer’s active charging session state before retrying. 4. Avoid aggressive automatic retries. 5. For payment-related errors, resolve the payment issue first. 6. For station/provider errors, refresh station data or ask the customer to choose another connector. 7. For unexpected errors, capture the returned support code if present and if the issue persists let us know. ## Summary | HTTP status | Error type | Meaning | Recommended action | | ----------- | ---------------------------- | ---------------------------------------------------- | --------------------------------------------- | | `409` | `already_charging` | Customer already has a session or one is starting | Refresh session state | | `409` | `billing_data_required` | Billing data is missing or invalid | Ask customer to update billing data | | `409` | `station_availability_issue` | Connector is out of order | Choose another connector | | `404` | Not applicable | EVSE or station was not found | Verify or refresh station data | | `402` | `payment_error` | Outstanding debt exists | Complete outstanding payment | | `402` | `pre_authorization_failed` | Payment pre-authorization failed | Authenticate, retry, or change payment method | | `424` | `station_availability_issue` | Station data cannot be fetched or station is blocked | Retry later or choose another station | | `424` | `charging_provider_error` | Provider failed to start charging | Refresh state, retry later | | `500` | `unexpected_error` | Unexpected internal error | Retry later, contact support with error code | # Stop Charging Error Handling Source: https://docs.cariqa.com/stop-charging-errors-handling Error handling reference for the Connect API stop charging flow. # Stop Charging Error Handling Stopping a charging session is the process of ending an existing active charging session for a Connect API user. Before the session can be stopped, the platform validates that the requested session exists, belongs to the requested user, is still active, and can be stopped through the charging provider. Because this flow depends on both internal charging session state and external charging infrastructure, a stop request can fail for several reasons. This document describes the expected error responses that external customers should handle when calling the **Stop Charging** endpoint. ## Error Response Format Most stop charging errors are returned using the following structure: ``` json { "detail": "Human-readable error message", "error": { "type": "error_type", "details": "Additional error details" } } ``` Clients should rely on `error.type` for programmatic handling when it is present and `error.details` is for human-readable error details. Some errors may not include the `error` object and may only return a `detail` field. Example: ``` json { "detail": "User session with this id was not found" } ``` *** # Status Codes ## `404 Not Found` The requested charging session could not be found or is not accessible for the current user/client scope. This can happen when: * The provided `session_id` does not exist. * The session does not belong to the requested user. Example response: ``` json { "detail": "User session with this id was not found" } ``` Recommended handling: * Verify that the `session_id` is correct. * Refresh the customer’s charging sessions list. *** ## `409 Conflict` The request is valid, but the charging session cannot be stopped because of the current session state. ### Error type: `already_stopped` The requested charging session is already inactive or has already been stopped. This can happen when: * The customer already stopped the session. * The session was stopped automatically by the charging provider or station. * The local session state was updated before the client sent the stop request. * The client is using stale session data. Example response: ``` json { "detail": "User session is already stopped", "error": { "type": "already_stopped", "details": "User session is already stopped" } } ``` Recommended handling: * Treat the session as stopped on the client side. * Refresh the session details. * Avoid retrying the stop request unless refreshed session data still shows the session as active. *** ### Error type: `charging_provider_error` The charging provider did not successfully stop the charging session. This can happen when: * The external charging provider rejected the stop request. * The provider could not process the stop command. * Communication with the provider failed. Example response: ``` json { "detail": "Charging Error", "error": { "type": "charging_provider_error", "details": "Charging provider didn't manage to stop charging" } } ``` Recommended handling: * Do not assume that charging has stopped. * Refresh the customer’s active session state. * If no session exists, allow the customer to retry after a short delay. * If the issue repeats, suggest using another connector or contacting support. *** ## `500 Internal Server Error` An unexpected internal error occurred while processing the stop charging request. ### Error type: `unexpected_error` This can happen when: * An internal state transition failed. * An unexpected platform error occurred. * Required internal data could not be generated. * An unknown unhandled condition was reached. Example response: ``` json { "detail": "Charging Error", "error": { "type": "unexpected_error", "details": "We faced unexpected error. In case it wasn't resolved let us know. Code: 123e4567-e89b-12d3-a456-426614174000" } } ``` Or: ``` json { "detail": "Charging Error", "error": { "type": "unexpected_error", "details": "Internal error occurred. Please try again a bit later." } } ``` Recommended handling: * Do not assume that charging has stopped. * Refresh the active session state before allowing another stopped attempt. * If an error code is included, store it and provide it to support. * Show a generic error message to the customer and suggest trying again later. *** # Recommended Client-Side Handling When a stop charging request fails: 1. Check the HTTP status code. 2. Check `error.type` when available. 3. Refresh the charging session state after any stop failure. 4. Treat `already_stopped` as a non-critical state conflict. 5. Do not assume the session is still active after a provider error without refetching session details. 6. Avoid aggressive automatic retries. 7. For provider errors, allow the customer to retry after refreshing session state. 8. For unexpected errors, capture the returned support code if present and if the issue persists let us know. ## Summary | HTTP status | Error type | Meaning | Recommended action | | ----------- | ------------------------- | ------------------------------------------ | -------------------------------------------- | | `404` | Not applicable | Session was not found or is not accessible | Verify session ID or refresh session data | | `424` | `already_stopped` | Session is already inactive or stopped | Treat session as stopped | | `424` | `charging_provider_error` | Provider failed to stop charging | Refresh state, show retry option | | `500` | `unexpected_error` | Unexpected internal error | Retry later, contact support with error code | # Development mode Source: https://docs.cariqa.com/test-payments In development mode, you can add a payment method and perform charging sessions without initiating real financial transactions. This configuration also applies to the [**Playground Reference Client**](https://docs.cariqa.com/demo-playground). ### Mobile Platforms | Payment Method | Configuration Requirement | | :-------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Credit Card** | No additional setup is required for dev mode beyond the standard client-side SDK initialization. | | **Apple Pay** | You must specify your **Apple Merchant ID** within the application code to enable the payment sheet; real cards are automatically replaced with a test card (e.g., `*4242`). | | **Google Pay** | No specialized setup is required for dev mode; real cards are automatically replaced with a test card (e.g., `*4242`). | ### Web Platform * **Credit Card**: No specialized setup is required for basic testing. * **Apple Pay**: You must share your website domain with the **Cariqa team** for registration. * **Google Pay**: You must share your website domain with the **Cariqa team** for registration. For mobile and web testing, you can use either a simulator or a physical device. Stripe will ensure no real charges are made during these test sessions. # Troubleshooting Source: https://docs.cariqa.com/troubleshooting ## 403 - Forbidden This error means that the provided token is invalid or expired. Check what value is sent and, if you believe it's right, contact our support team to get help. ## 401 - Unauthorized This error means that the authorization header has not been correctly added to the request. Check again the [Authentication](/authentication) section to make sure everything is done correctly.