End-to-end example

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

User Registration - Create user account
Payment Setup - Add and configure payment method via Stripe
Station Discovery - Find nearby charging stations
Start Charging - Initiate a charging session
Monitor Session - Track charging progress
Stop Charging - End session and get receipt

1. User Registration

First, create a user account in the system:

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"
  }'

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

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:

{
  "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:

curl -X GET "https://connect.cariqa.com/api/v1/users/123/setup-intents/?pm_type=card" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

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"]

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:

{
  "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 guide to confirm the Setup Intent on the client side (iOS, Android, Web).

2.3 Verify Payment Method Added

curl -X GET "https://connect.cariqa.com/api/v1/users/123/payment-methods/" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

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"]

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:

{
  "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:

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"

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

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):

{
    "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:

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"
  }'

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"]

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:

{
  "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:

curl -X GET "https://connect.cariqa.com/api/v1/users/123/charging-sessions/ab7ae756-b663-43b9-a025-40c51dd503d9/" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

# 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)

// 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):

{
  "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:

curl -X POST "https://connect.cariqa.com/api/v1/users/123/charging/stop/ab7ae756-b663-43b9-a025-40c51dd503d9/" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

response = requests.post(
    f"https://connect.cariqa.com/api/v1/users/{user_id}/charging/stop/{session_id}/",
    headers=headers
)
stop_result = response.json()

const stopResponse = await fetch(`https://connect.cariqa.com/api/v1/users/${userId}/charging/stop/${sessionId}/`, {
  method: 'POST',
  headers
});

const stopResult = await stopResponse.json();

Response:

7. Get completed charging session

Retrieve the complete session details with final costs:

curl -X GET "https://connect.cariqa.com/api/v1/users/123/charging-sessions/ab7ae756-b663-43b9-a025-40c51dd503d9/" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

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']}")

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:

{
  "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/?<params>",
    "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:

Example Error Handling

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:

✅ Create user accounts with proper authentication
✅ Securely collect payment methods via Stripe integration
✅ Discover charging stations with location-based search
✅ Initiate charging sessions with payment authorization
✅ Monitor session progress with real-time status updates
✅ 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.

Introduction

Use Cases

Guides

API Reference

User Journey

Flow Overview

1. User Registration

2. Payment Method Setup

2.1 Create Setup Intent

2.2 Frontend Stripe Integration

2.3 Verify Payment Method Added

3. Station Discovery

4. Start Charging Session

5. Monitor Charging Session

6. Stop Charging Session

7. Get completed charging session

Error Handling Best Practices

Summary

​User Journey

​Flow Overview

​1. User Registration

​2. Payment Method Setup

​2.1 Create Setup Intent

​2.2 Frontend Stripe Integration

​2.3 Verify Payment Method Added

​3. Station Discovery

​4. Start Charging Session

​5. Monitor Charging Session

​6. Stop Charging Session

​7. Get completed charging session

​Error Handling Best Practices

​Summary

User Journey

Flow Overview

1. User Registration

2. Payment Method Setup

2.1 Create Setup Intent

2.2 Frontend Stripe Integration

2.3 Verify Payment Method Added

3. Station Discovery

4. Start Charging Session

5. Monitor Charging Session

6. Stop Charging Session

7. Get completed charging session

Error Handling Best Practices

Summary