Skip to main content

Consumer Services API

Welcome to the documentation for the Consumer Services API.

Structure​

The Consumer Services project exposes a number of different APIs depending on the use-case. Some parts of how the APIs work are shared though, such as authentication.

Getting started​

In order to get started with the API and make your first requests, you can follow the guide below.

Authentication​

Every request must include an access token in the Authorization header with the Bearer prefix. There are two kinds of callers, and each uses a different authentication mechanism and token issuer. Which one you need depends on what you are building:

End-userUser Management (UM)
WhoA consumer using an app or web shop, e.g. someone buying a data package for their vehicle.A backend service or administrator acting on behalf of a tenant (domain), e.g. a user of IoT Connect Portal or a system integration.
Token issuerConsumer Services user pool (Amazon Cognito)User Management (iam.iot.telenor.com)
Typical useBrowsing products, buying, managing own subscriptions and payment methods. Sees only their own data.Reading data across the tenant's domain, issuing refunds. Access is controlled by permissions.
CredentialsThe user's email and password (or a federated sign-in) together with a public Client ID. No secret.A client_id and client_secret (client credentials), or a signed-in UM user.

The two token types are not interchangeable. Routes only admit the callers listed for them: an end-user token is rejected (403) on routes reserved for UM callers, such as the receipt list, and a UM token is rejected on routes that act on behalf of a shopper, such as creating a purchase or a payment. Each section of the API documentation states which caller applies. A missing or unknown caller results in 401.

End-user authentication​

End-users authenticate against the Consumer Services user pool. Please contact support for the Client ID of the public app client and the Cognito region/domain that applies to your environment. The client is public, so it has no client secret and can safely be used from a browser or mobile app.

Use an SDK such as AWS Amplify in your app (this is what the Consumer Services customer portal does), or call the Cognito API directly:

curl -X POST https://cognito-idp.eu-north-1.amazonaws.com/ \
-H "Content-Type: application/x-amz-json-1.1" \
-H "X-Amz-Target: AWSCognitoIdentityProviderService.InitiateAuth" \
-d '{
"AuthFlow": "USER_PASSWORD_AUTH",
"ClientId": "your-public-client-id",
"AuthParameters": {
"USERNAME": "shopper@example.com",
"PASSWORD": "the-users-password"
}
}'

The response contains an AuthenticationResult:

{
"AuthenticationResult": {
"AccessToken": "eyJraWQiOi...",
"IdToken": "eyJraWQiOi...",
"RefreshToken": "eyJjdHkiOi...",
"ExpiresIn": 3600,
"TokenType": "Bearer"
}
}

Send the AccessToken in the Authorization header. The IdToken is not accepted by the API. When the access token expires, use the RefreshToken to get a new one instead of asking the user to sign in again:

curl -X POST https://cognito-idp.eu-north-1.amazonaws.com/ \
-H "Content-Type: application/x-amz-json-1.1" \
-H "X-Amz-Target: AWSCognitoIdentityProviderService.InitiateAuth" \
-d '{
"AuthFlow": "REFRESH_TOKEN_AUTH",
"ClientId": "your-public-client-id",
"AuthParameters": { "REFRESH_TOKEN": "your-refresh-token" }
}'

Note: Users sign up and confirm their account through the same user pool. If the user's account requires further steps (for example a confirmation code or a new password), InitiateAuth returns a ChallengeName instead of tokens. Users that sign in through an OEM use the identity federation flow instead of a password.

User Management authentication​

UM callers authenticate using OAuth 2.0. For more information on how to implement OAuth authentication, see https://www.oauth.com/oauth2-servers/access-tokens/client-credentials/.

Please contact support for the URL for fetching an OAuth-token, a Client ID, and a Client Secret. Once a request towards the token-endpoint has been made successfully, you will have an access token. This access-token is then to be included in subsequent requests to the API as a Authorization-header with the Bearer-prefix.

Once you have a client_id and a client_secret, follow these steps:

  1. Send Authentication Request: Make a POST request to the token endpoint with your credentials.

    • Example:
      curl -X POST \
      https://iam.iot.telenor.com/auth/realms/telenor-iot/protocol/openid-connect/token \
      -d "client_id=your-client-id" \
      -d "client_secret=your-client-secret" \
      -d "scope=openid" \
      -d "grant_type=client_credentials"
  2. Receive Token: Upon successful authentication request, the response will contain an access token.

  3. Use Token: Include the obtained token in the Authorization header of subsequent requests to access protected resources.

What a UM token may do is decided by the permissions granted to your client or user, for example permission-ecom-product-read. A call to a route you lack permission for returns 403. Never use a client_secret in a browser or mobile app.

E-commerce​

The E-commerce API lets you sell data products (top-ups and subscriptions) to your users. A purchase is the central entity: it owns the cart, and every payment, subscription and receipt is attached to it.

All E-commerce endpoints are served under:

https://api.iotdrive.telenor.com/consumer-services/ecom/v1

Who can call what​

The purchase flow described below is performed by an end-user (see End-user authentication), since a purchase, its cart and its payments belong to the shopper. UM callers read data across their domain. In short:

AreaEnd-userUser Management
List products for sale (GET /products/for-sale/{oemMarketId})YesNeeds permission-ecom-product-read
Create a purchase, add and remove cart itemsYes (own purchases)No
Payment methods, create a payment, payment detailsYes (own purchases)No
Read purchases, carts, payments, subscriptionsYes (own data)Needs the matching permission-ecom-*-read
Create refundsYes (own purchases)Needs permission-ecom-refund-create
Receipt lists (GET /receipts)NoNeeds permission-ecom-receipt-read

An end-user always sees only their own data. A UM caller sees the data belonging to their domain and its child domains.

The examples below use an end-user access token (see Authentication) and these shell variables:

export BASE_URL="https://api.iotdrive.telenor.com/consumer-services/ecom/v1"
export TOKEN="end-user-access-token"

Example of fetching a token with the shopper's credentials:

export TOKEN=$(curl -s -X POST https://cognito-idp.eu-north-1.amazonaws.com/ \
-H "Content-Type: application/x-amz-json-1.1" \
-H "X-Amz-Target: AWSCognitoIdentityProviderService.InitiateAuth" \
-d '{
"AuthFlow": "USER_PASSWORD_AUTH",
"ClientId": "your-public-client-id",
"AuthParameters": { "USERNAME": "shopper@example.com", "PASSWORD": "the-users-password" }
}' | jq -r '.AuthenticationResult.AccessToken')

Request and response bodies are JSON, so send Content-Type: application/json on requests with a body. Errors are returned with an HTTP status code and a machine-readable reasonCode in the body (for example VALIDATION, NOT_FOUND, PAYMENT_ALREADY_PENDING).

Overview of the purchase flow​

  1. List products that are for sale in a market.
  2. Create a purchase for that market.
  3. Add a product to the cart.
  4. Fetch the payment methods available for the purchase.
  5. Render the Adyen client side components in your frontend.
  6. Create the payment with the encrypted card data from Adyen.
  7. Handle additional actions (3-D Secure, redirects).
  8. Verify the purchase.

Card details never pass through your backend or ours in clear text: Adyen's components encrypt them in the browser, and you only forward the encrypted values.

1. List products​

Products are listed per OEM market (oemMarketId). Only products that are currently for sale are returned. The result is paginated; use limit (1-100) and continuationToken (from meta.continuationToken of the previous page) to page through it. Pass locale to get translated display names.

curl -X GET \
"$BASE_URL/products/for-sale/{oemMarketId}?locale=en&limit=20" \
-H "Authorization: Bearer $TOKEN"

Example response:

{
"items": [
{
"productId": "01JABCDEF0123456789XYZ",
"productType": "SUBSCRIPTION",
"displayName": "Premium data",
"priceIncVat": 99,
"vatPercentage": 0.25,
"productTypeDefinition": {
"recurrenceInMonths": 1,
"subscriptionType": "CONTINUOUS"
},
"dataInBytes": 10737418240,
"deviceType": "VEHICLE",
"createdAt": "2025-01-01T00:00:00.000Z",
"lastModifiedAt": "2025-01-01T00:00:00.000Z"
}
],
"meta": { "continuationToken": null, "limit": 20 }
}

productType is either TOPUP (one-time) or SUBSCRIPTION (FIXED_TERM or CONTINUOUS). vatPercentage is a fraction between 0 and 1. You can narrow the list with the optional deviceType query parameter (VEHICLE, FLEET_VEHICLE or IP_CAMERA).

2. Create a purchase​

A purchase starts out empty and is tied to an OEM market, which decides the currency and payment configuration.

curl -X POST \
"$BASE_URL/purchases" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{ "oemMarketId": "your-oem-market-id" }'

Example response:

{
"item": {
"userId": "01JUSER0123456789XYZ",
"purchaseId": "01JPURCHASE0123456789",
"status": "CREATED",
"oemMarketId": "your-oem-market-id",
"domainId": "your-domain-id",
"currency": "EUR",
"createdAt": "2025-01-01T12:00:00.000Z",
"lastModifiedAt": "2025-01-01T12:00:00.000Z"
}
}

Keep the purchaseId; it is used in every following step. You can read the purchase, and follow its status, at any time:

curl -X GET \
"$BASE_URL/purchases/{purchaseId}" \
-H "Authorization: Bearer $TOKEN"

A purchase moves through these statuses: CREATED → PAYMENT_PENDING (waiting for 3-D Secure or similar) → PAYMENT_COMPLETED → COMPLETED. If a payment is refused the status becomes PAYMENT_FAILED, and you may retry by creating a new payment for the same purchase. COMPLETED means post-payment processing (for example delivering top-ups) has finished.

3. Add products to the cart​

The cart belongs to the purchase. Add a product by sending its productId, the affectedEntityId it applies to (for example the identifier of the vehicle receiving the data) and the market.

curl -X POST \
"$BASE_URL/carts/{purchaseId}/cart-items" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"productId": "01JABCDEF0123456789XYZ",
"affectedEntityId": "your-affected-entity-id",
"oemMarketId": "your-oem-market-id",
"locale": "en"
}'

Example response:

{
"purchaseId": "01JPURCHASE0123456789",
"cartItemId": "01JCARTITEM0123456789",
"productId": "01JABCDEF0123456789XYZ",
"affectedEntityId": "your-affected-entity-id",
"displayName": "Premium data",
"priceIncVat": 99,
"vatPercentage": 0.25,
"dataInBytes": 10737418240
}

Inspect the cart, including its summary, with:

curl -X GET \
"$BASE_URL/carts/{purchaseId}" \
-H "Authorization: Bearer $TOKEN"

Remove an item with:

curl -X DELETE \
"$BASE_URL/carts/{purchaseId}/cart-items/{cartItemId}" \
-H "Authorization: Bearer $TOKEN"

Note: A payment can be created for a cart holding exactly one item. Adding a product that does not exist in the market returns 404.

4. Fetch payment methods​

Before rendering the payment form, ask the API which payment methods are available for the purchase. The result is handed to the Adyen components in the next step. browserInfo describes the shopper's browser; in a web frontend all values can be read from window and navigator.

curl -X POST \
"$BASE_URL/payment-methods" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"purchaseId": "01JPURCHASE0123456789",
"shopperEmail": "shopper@example.com",
"shopperLocale": "en-GB",
"browserInfo": {
"acceptHeader": "text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8",
"colorDepth": 24,
"language": "en-GB",
"screenHeight": 1080,
"screenWidth": 1920,
"timeZoneOffset": -60,
"userAgent": "Mozilla/5.0 ..."
}
}'

To offer saved cards (see tokenize in step 6), send the same body to POST $BASE_URL/stored-payment-methods. Pass the two results to Adyen as paymentMethods and storedPaymentMethods.

5. Collect card details with Adyen client side components​

Payments are processed by Adyen. Use Adyen's @adyen/adyen-web library (v6) in your frontend to render the card form. It encrypts the card data in the browser, so you never handle raw card numbers.

You need:

  • An Adyen client key for the target environment. Contact support to get one.
  • The Adyen environment (test or the matching live region), plus the purchase's currency and country.
  • The payment methods from step 4.
npm install @adyen/adyen-web
import { AdyenCheckout, Card } from '@adyen/adyen-web/auto';
import '@adyen/adyen-web/styles/adyen.css';

let paymentId: string;
let paymentData: string;

const checkout = await AdyenCheckout({
environment: 'test',
clientKey: 'your-adyen-client-key',
locale: 'en-GB',
countryCode: 'SE',
amount: { value: 9900, currency: 'EUR' }, // minor units: priceIncVat * 100
paymentMethodsResponse: { paymentMethods, storedPaymentMethods },

// Called when the shopper submits the form
onSubmit: async (state, _component, actions) => {
const { paymentMethod } = state.data;
const res = await fetch(`${BASE_URL}/payments`, {
method: 'POST',
headers: {
Authorization: `Bearer ${token}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
purchaseId,
shopperEmail,
returnUrl: `${window.location.origin}/payment/return`,
browserInfo,
paymentMethod: {
card: {
type: paymentMethod.type,
encryptedCardNumber: paymentMethod.encryptedCardNumber,
encryptedExpiryMonth: paymentMethod.encryptedExpiryMonth,
encryptedExpiryYear: paymentMethod.encryptedExpiryYear,
encryptedSecurityCode: paymentMethod.encryptedSecurityCode,
},
},
}),
});
if (!res.ok) return actions.reject();

const { item } = await res.json();
paymentId = item.paymentId;
paymentData = item.paymentData;
actions.resolve({
resultCode: item.resultCode,
action: item.paymentAction ? JSON.parse(item.paymentAction) : undefined,
});
},

// Called after a 3-D Secure / redirect challenge
onAdditionalDetails: async (state, _component, actions) => {
const res = await fetch(`${BASE_URL}/payment-details`, {
method: 'POST',
headers: {
Authorization: `Bearer ${token}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
purchaseId,
paymentId,
paymentData,
details: state.data.details, // { threeDSResult } or { redirectResult }
}),
});
if (!res.ok) return actions.reject();

const { item } = await res.json();
actions.resolve({ resultCode: item.resultCode });
},

onPaymentCompleted: () => { /* continue to step 8 */ },
onPaymentFailed: (result) => { /* show error */ },
onError: (error) => { /* show error */ },
});

new Card(checkout).mount('#card-container');

Things to note:

  • amount.value is in minor units (cents), whereas the API's priceIncVat is in major units.
  • The API returns Adyen's paymentAction as a JSON string; parse it before handing it to Adyen.
  • Keep paymentId and paymentData from the create-payment response, they are required when submitting additional details.
  • The browser calls the API directly with the shopper's end-user access token, so no secret is involved. Never use User Management credentials (client_secret) in a browser; those tokens are also not accepted on these routes.

To let a returning shopper pay with a saved card, mount Adyen's Dropin instead of Card, and send paymentMethod.stored instead of paymentMethod.card in the next step.

6. Create a payment​

This is the request made by the onSubmit handler above. The amount is taken from the cart; you don't send it. Set tokenize to true to save the card for future use.

curl -X POST \
"$BASE_URL/payments" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"purchaseId": "01JPURCHASE0123456789",
"shopperEmail": "shopper@example.com",
"shopperLocale": "en-GB",
"returnUrl": "https://your-app.example.com/payment/return",
"tokenize": false,
"browserInfo": {
"acceptHeader": "text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8",
"colorDepth": 24,
"language": "en-GB",
"screenHeight": 1080,
"screenWidth": 1920,
"timeZoneOffset": -60,
"userAgent": "Mozilla/5.0 ..."
},
"paymentMethod": {
"card": {
"type": "scheme",
"encryptedCardNumber": "adyenjs_0_1_25$...",
"encryptedExpiryMonth": "adyenjs_0_1_25$...",
"encryptedExpiryYear": "adyenjs_0_1_25$...",
"encryptedSecurityCode": "adyenjs_0_1_25$..."
}
}
}'

For a saved card, replace card with:

"stored": {
"type": "scheme",
"storedPaymentMethodId": "stored-payment-method-id",
"encryptedSecurityCode": "adyenjs_0_1_25$..."
}

Example response:

{
"item": {
"purchaseId": "01JPURCHASE0123456789",
"paymentId": "01JPAYMENT0123456789",
"paymentStatus": "PENDING",
"resultCode": "IdentifyShopper",
"paymentAction": "{\"type\":\"threeDS2\", ...}",
"paymentData": "Ab02b4c0...",
"amountIncVat": 99,
"vatAmount": 19.8,
"currency": "EUR",
"createdAt": "2025-01-01T12:01:00.000Z",
"lastModifiedAt": "2025-01-01T12:01:00.000Z",
"documents": []
}
}

How to read the result:

resultCodeMeaning
AuthorisedThe payment was accepted.
IdentifyShopper, ChallengeShopper, RedirectShopperThe shopper must complete a 3-D Secure challenge or redirect. paymentAction describes it and Adyen's component handles it.
Refused, Cancelled, ErrorThe payment failed (paymentStatus is FAILED). Check refusalReason. The shopper can try again.

Errors worth handling:

StatusreasonCodeMeaning
400PRODUCT_NOT_FOR_SALEA product in the cart is no longer for sale.
400VALIDATIONInvalid body, an empty cart (unless tokenize is true), or more than one cart item.
409PAYMENT_ALREADY_PENDINGThe purchase already has a payment in progress.
409PAYMENT_ALREADY_COMPLETEDThe purchase has already been paid.

7. Handle additional actions (3-D Secure / redirects)​

When paymentAction is present, Adyen's component runs the challenge and then calls onAdditionalDetails. Forward the details to POST /payment-details:

curl -X POST \
"$BASE_URL/payment-details" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"purchaseId": "01JPURCHASE0123456789",
"paymentId": "01JPAYMENT0123456789",
"paymentData": "Ab02b4c0...",
"details": { "threeDSResult": "eyJ0cmFuc1N0YXR1cyI6..." }
}'

For flows where the shopper leaves your page (redirects), Adyen sends them back to your returnUrl with a redirectResult query parameter. On that page, submit it as "details": { "redirectResult": "..." }. Since the page is reloaded, persist purchaseId, paymentId and paymentData (for example in sessionStorage) before the redirect.

The response has the same shape as in step 6 and contains the final resultCode (Authorised on success).

8. Verify the purchase​

The final state of a purchase is set asynchronously: Adyen confirms the payment to us through a webhook, after which the purchase is processed in the background. A positive resultCode in the browser means the payment was accepted, but treat the purchase as paid once its status is PAYMENT_COMPLETED or COMPLETED. Poll the purchase until then:

curl -X GET \
"$BASE_URL/purchases/{purchaseId}" \
-H "Authorization: Bearer $TOKEN"

You can also list the purchase's payments and fetch its receipts:

curl -X GET \
"$BASE_URL/payments?purchaseId={purchaseId}" \
-H "Authorization: Bearer $TOKEN"
curl -X GET \
"$BASE_URL/receipts?purchaseId={purchaseId}" \
-H "Authorization: Bearer $TOKEN"