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

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.

Frontend Only - Required for Compliance

// Initialize Stripe with your publishable key (provided during onboarding)
const stripe = Stripe('pk_live_your_publishable_key');

// Create Elements instance  
const elements = stripe.elements();

// Create card element
const cardElement = elements.create('card');
cardElement.mount('#card-element');

// When user submits payment form
const {error, paymentMethod} = await stripe.createPaymentMethod({
  type: 'card',
  card: cardElement,
});

if (error) {
  // Handle error
  console.error(error);
} else {
  // Confirm the setup intent
  const {error: confirmError} = await stripe.confirmCardSetup(
    clientSecret,  // From step 2.1
    {
      payment_method: paymentMethod.id
    }
  );
  
  if (!confirmError) {
    // Payment method successfully added
    console.log('Payment method added successfully');
  }
}

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:

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_view": "https://invoice.stripe.com/i/acct_1LKJg9HtgZxQ1KXx/test_YWNjdF8xTEtKZzlIdGdaeFExS1h4LF9VR0lGVXZ1ckhJRFlMaTJPZVoyTzR3R1dsbE81NXJaLDE2NTY3ODcyNA02000P98cfsJ?s=ap",
    "invoice_download": "https://pay.stripe.com/invoice/acct_1LKJg9HtgZxQ1KXx/test_YWNjdF8xTEtKZzlIdGdaeFExS1h4LF9VR0lGVXZ1ckhJRFlMaTJPZVoyTzR3R1dsbE81NXJaLDE2NTY3ODcyNA02000P98cfsJ/pdf?s=ap",
    "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

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

Introduction

Use Cases

API Reference

Documentation Index

​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