Skip to main content

​
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: 
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"
  }'
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: 
{
  "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: 
{
  "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"
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"
  }'
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"
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: 
204

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