Partner Integration Checklist

Welcome to the Partner Integration Guide

This guide provides a step-by-step checklist to help you quickly and securely integrate our APIs. With AWS Cognito handling authentication, you can confidently get started while ensuring compliance with our security requirements There are two integration methods available for connecting with our system:

1. API-Based Flow: This method is used when you have your own UI (via app or web) and want to integrate with our system using our APIs. This approach is referred to as the API-Based Flow. Follow

2. Single-Use Activation Link Flow: This method is used when you do not have your own UI and prefer to use our UI for purchases and cancellations. This approach is referred to as the Single-Use Activation Link Flow.

⚠️ Note: You cannot switch between the two flows interchangeably. You must choose one of the flows and follow the corresponding steps, as these configurations are pre-mapped in our system.

API-Based Flow

Follow the steps below to proceed with API Based Flow

Step 1: Pre-Integration Requirements for API Based Flow

You Provide:

1. Product IDs (productId): Required for creating a purchase. These IDs identify the products your users can buy and must be mapped in our system.
2. Redirect URL: Needed for user pairing. This is the URL where users are redirected after activation.

You Receives:

1. Partner ID (partnerId): A unique identifier for your organization within our system.
2. Client ID and Client Secret: Used for API authentication, provided securely by our team.

Note: Store credentials securely and ensure they remain accessible within your application.

---

Step 2: Generating Access Tokens

Once you receive your client credentials, follow these steps to obtain an access token for making API calls.

Encoding Your Credentials

Use Base64 URL encoding to encode clientId:clientSecret.

echo -n 'clientId:clientSecret' | base64 > encoded_credentials

Requesting an Access Token

Make a POST request to the Amazon Cognito token endpoint with your encoded credentials.

curl -v -X POST \
-H 'Content-Type: application/x-www-form-urlencoded' \
-H 'Authorization: Basic {encoded_credentials}' \
"https://ps.auth.eu-central-1.amazoncognito.com/oauth2/token?grant_type=client_credentials"

Notes:

• For tokens obtained via the client_credentials grant, Amazon Cognito does not issue refresh tokens. This is because the client credentials flow is designed for server-to-server communication without user interaction. To obtain a new access token after the current one expires, you must repeat Step 2.
• Store the access token securely; it expires after 1 hour. Re-run this step to obtain a new token before expiration.

---

Step 3: User Pairing

The pairing process links your users to our system.

Process Flow

1. Users click on a pairing link in your app/web.
2. They are redirected to our login/registration page.
3. Upon successful login/registration, they are redirected to your provided Redirect URL with a unique (csuId) as a query parameter which serves as our reference ID for your user
4. The csuId should be stored and linked to your user ID in your system, as it serves as our reference ID for your user.

API Endpoints

You Provide this URL to your users:

https://dealer.prod.ps.axelspringer.de/api/v1/partners/{partnerId}/activation

After successful login/registration, users are redirected to your provided Redirect URL with the following query parameter:

https://your-redirect-url.com/?csuId=XYZ123

Note: Store the csuId securely for future API calls.

---

Step 4: Creating a Purchase or Subscription

Once the csuId is mapped, you can initiate purchases or subscriptions.

Purchase Creation API

curl --location \
'https://dealer.prod.ps.axelspringer.de/api/v1/partners/{partnerId}/purchase' \
--header 
'Content-Type: application/json' --header 'Authorization: Bearer ${STEP2_ACCESS_TOKEN}' \
 --data '{
    "csuId": "CSUID-FROM_STEP3",
    "productId": "PRODUCT_ID_FROM_STEP1",
    "purchaseRef": "globally_unique_purchase_reference_to_identify_the_purchase"
}'

Note: The purchaseRef refers to a unique reference that you generate to link this subscription to the user. It could be the user's unique ID, or a combination of the user ID and purchase reference—anything that ensures it’s unique to both the user and the purchase. This reference will be used later to cancel the subscription, so it’s important to ensure it can uniquely identify this transaction.

More details: API Documentation

---

Step 5: Subscription Cancellation

Once a user subscribes, their subscription auto-renews monthly unless canceled or terminated by the user or partner.

Canceling a Subscription

curl --location --request DELETE 'https://dealer.prod.ps.axelspringer.de/api/v1/partners/{partnerId}/purchase?purchaseRef=${purchaseRef_step4_passed_should}' --header 'Content-Type: application/json' --header 'Authorization: Bearer ${STEP2_ACCESS_TOKEN}'

More details: Subscription Management

---

API Based Flow Integration Checklist ✅

Step	Task Description	Partner Action	Status
Setup	Provide product IDs and redirect URL	Submit product IDs and redirect URL to our team	[ ]
Setup	Receive authentication credentials	Store Partner ID, Client ID, and Client Secret securely	[ ]
1	Encode client credentials	Generate Base64-encoded credentials	[ ]
2	Obtain access token	Make API request to retrieve token	[ ]
3	Store and manage token	Use the token for all subsequent api calls, once expired then make new token	[ ]
4	Implement user pairing	Redirect users and store CSU-ID securely	[ ]
5	Create purchase/subscription	Call API to initiate a purchase	[ ]
6	Cancel subscriptions	Implement cancellation endpoint whenever required	[ ]

✅ Once all steps are checked, your integration is complete! 🚀

Support & Contact

For any integration issues, reach out to our SPRINGPremiumServices-og team at SPRINGPremiumServices-og@moveoffice.com.

Happy Integrating! 🚀

---