Integrating Teleskope Platform with Rewards Vendor

19 min

Introduction

This document outlines the technical design for integrating the Teleskope platform with a third-party Rewards vendor. The primary goal of this integration is to enable Teleskope users to redeem points, earned and stored within the Teleskope platform, for rewards offered by the integrated vendor. The integration will facilitate a seamless user experience, secure user identification, and a robust point deduction mechanism with transactional integrity.

Solution Overview

The integration will leverage a Single Sign-On (SSO) mechanism using Java Web Tokens (JWT) for secure user authentication and authorization when transitioning from Teleskope to the Rewards platform. Point deduction will be managed through a REST-based Enterprise Application Integration (EAI) API provided by Teleskope, utilizing a two-phase commit with rollback to ensure data consistency.

Key Components and Technologies

Teleskope Platform: The system of record for user points and the initiator of the reward redemption process.
Rewards Platform: The external vendor system that displays and allows redemption of rewards.
Java Web Tokens (JWT): Used for secure, stateless transmission of user identity and point information from Teleskope to the Rewards platform.
Teleskope EAI API: A RESTful API provided by Teleskope for programmatic interaction, specifically for point deduction with two-phase commit.
HTTPS: All communication between platforms will be secured using HTTPS.

Integration Flows

User Journey: From Teleskope to Rewards Platform

User Initiates Redemption: A user logged into the Teleskope platform navigates to a "Redeem Rewards" section and clicks on a "Redeem" button.
Teleskope Generates JWT: Upon clicking "Redeem," the Teleskope backend generates a signed JWT containing the following claims:
1. firstName: User's first name
2. lastName: User's last name
3. points: User's current number of points
4. email: User's email address
5. userId: Unique identifier for the user on Teleskope
6. iat: Issued At
7. exp: Expiration Time for JWT validity.
Redirection to Rewards Platform: Teleskope redirects the user's browser to a pre-configured URL on the Rewards platform. The JWT is passed as a URL parameter (e.g., https://rewards.vendor.com/redeem?token=<JWT>) or as part of a POST request, depending on the agreed-upon method with the Rewards vendor for security and URL length considerations.
Rewards Platform Validates JWT: Upon receiving the request, the Rewards platform:
1. Validates the JWT's signature using a pre-shared secret or public key provided by Teleskope.
2. Verifies the exp claim to ensure the token has not expired.
3. Extracts the user claims (first name, last name, points, email, userId).
Rewards Platform Displays User Points: The Rewards platform uses the points claim from the JWT to display the user's available points prominently on their interface, allowing the user to browse and select rewards. The user's identity (first name, last name, email) can also be used for personalization.

Point Deduction: Two-Phase Commit with Rollback

This flow describes how points are deducted from Teleskope when a user checks out rewards on the Rewards platform.

Phase 1: Prepare (Commit Request)

User Checks Out Rewards: On the Rewards platform, the user selects desired rewards and proceeds to checkout. The Rewards platform determines the total points required for the selected rewards.
Rewards Platform Initiates Commit Request (Teleskope EAI API): The Rewards platform makes a POST request to Teleskope's EAI API commit endpoint (e.g., /eai/v1/points?commit). This request will include:
1. user_id: The unique ID of the user (obtained from the initial JWT).
2. points_to_deduct: The total number of points to be deducted for the chosen rewards.
3. transaction_id: A unique identifier generated by the Rewards platform for this specific redemption transaction.
4. description: A brief description of the reward redemption (e.g., "Redemption for [Reward Name]").
Teleskope Processes Commit Request: Upon receiving the commit request, Teleskope:
1. Validates the user_id and points_to_deduct.
2. Checks if the user has sufficient points available.
3. If successful: Temporarily "holds" or earmarks the points_to_deduct for the given transaction_id, ensuring they cannot be spent elsewhere. Responds with a 200 OK status and a success message, acknowledging the commit request.
4. If insufficient points or other error: Responds with a 4xx status code (e.g., 400 Bad Request) and an error message, indicating the failure.

Phase 2: Complete (Confirm or Rollback)

Scenario A: Successful Redemption (Confirm)

Rewards Platform Confirms Redemption: After successfully processing the reward order (e.g., confirming inventory, preparing for shipment), the Rewards platform makes a POST request to Teleskope's EAI API confirm endpoint (e.g., /eai/v1/points?confirm). This request will include:
1. user_id: The unique ID of the user.
2. transaction_id: The same transaction_id used in the commit request.
Teleskope Processes Confirm Request: Upon receiving the confirm request, Teleskope:
1. Permanently deducts the points previously held for the specified transaction_id and user_id.
2. Responds with a 200 OK status and a success message.

Scenario B: Failed Redemption (Rollback)

Rewards Platform Rolls Back: If the reward order cannot be fulfilled for any reason (e.g., out of stock, payment failure on Rewards platform side), the Rewards platform makes a POST request to Teleskope's EAI API rollback endpoint (e.g., /eai/v1/points?rollback). This request will include:
1. user_id: The unique ID of the user.
2. transaction_id: The same transaction_id used in the commit request.
Teleskope Processes Rollback Request: Upon receiving the rollback request, Teleskope:
1. Releases the temporarily held points for the specified transaction_id and user_id, making them available again to the user.
2. Responds with a 200 OK status and a success message.

API Endpoints (Teleskope EAI API)

Teleskope will expose the following RESTful API endpoints:

POST /eai/v1/points?commit
- Description: Initiates the first phase of the point deduction.
- Request Body (JSON):JSON

{
    "userId": "string",
    "pointsToDeduct": "integer",
    "transactionId": "string",
    "description": "string"
}

Response (200 OK - JSON):JSON

 {
    "status": "SUCCESS",
    "message": "Points committed for transaction"
}

Error Responses (4xx - JSON):JSON

 {
    "status": "FAILED",
    "message": "Error description"
}

(e.g., insufficient points, invalid user)

POST /eai/v1/points?confirm
- Description: Confirms the point deduction after successful reward fulfillment.
- Request Body (JSON):JSON

{
    "userId": "string",
    "transactionId": "string"
}

Response (200 OK - JSON):JSON

 {
    "status": "SUCCESS",
    "message": "Points successfully deducted"
}

Error Responses (4xx - JSON): (e.g., transaction not found, points already deducted)

POST /eai/v1/points?rollback
- Description: Rolls back the point deduction in case of failed reward fulfillment.
- Request Body (JSON):JSON

{
    "userId": "string",
    "transactionId": "string"
}

Response (200 OK - JSON):JSON

{
    "status": "SUCCESS",
    "message": "Points successfully rolled back"
}

Error Responses (4xx - JSON): (e.g., transaction not found, no points to roll back)

Security Considerations

JWT Signature: JWTs will be signed using a strong algorithm (e.g., HS256 or RS256) and a secret key or key pair shared only between Teleskope and the Rewards platform.
JWT Expiration: JWTs will have a short expiration time to minimize the window of opportunity for replay attacks.
HTTPS Everywhere: All communication between Teleskope and the Rewards platform must occur over HTTPS to ensure data encryption in transit.
API Authentication/Authorization: The Teleskope EAI API should be protected with appropriate authentication and authorization mechanisms (e.g., HTTPS Basic Authentication, IP Whitelisting) to ensure only the authorized Rewards platform can access it.
Input Validation: Both platforms must rigorously validate all incoming data to prevent injection attacks and other vulnerabilities.

Error Handling and Retries

Network Issues: Rewards platforms should implement robust retry mechanisms with exponential backoff for transient network failures when making API calls.
API Errors: The Rewards platform should gracefully handle error responses from the Teleskope EAI API. For instance, if a commit request fails due to insufficient points, the Rewards platform should inform the user accordingly.