---
title: Integrating Teleskope Platform with Rewards Vendor
slug: integrating-teleskope-platform-with-rewards-vendor
docTags: 
createdAt: 2025-06-23T13:55:16.812Z
---

# 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

1. **User Initiates Redemption:** A user logged into the Teleskope platform navigates to a "Redeem Rewards" section and clicks on a "Redeem" button.
2. **Teleskope Generates JWT:** Upon clicking "Redeem," the Teleskope backend generates a signed JWT containing the following claims:
   1. <font color="#22C55E">firstName\:</font> User's first name
   2. <font color="#22C55E">lastName\:</font> User's last name
   3. <font color="#22C55E">points\:</font> User's current number of points
   4. <font color="#22C55E">email\: </font>User's email address
   5. <font color="#22C55E">userId\:</font> Unique identifier for the user on Teleskope
   6. <font color="#22C55E">iat\:</font> Issued At
   7. <font color="#22C55E">exp\:</font> Expiration Time for JWT validity.
3. 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., <font color="#22C55E">https\://rewards.vendor.com/redeem?token=&lt;JWT&gt;</font>) or as part of a POST request, depending on the agreed-upon method with the Rewards vendor for security and URL length considerations.
4. 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 <font color="#22C55E">exp</font> claim to ensure the token has not expired.
   3. Extracts the user claims (first name, last name, points, email, userId).
5. **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.

## &#x20;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)

1. **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.
2. **Rewards Platform Initiates Commit Request (Teleskope EAI API):&#x20;**&#x54;he Rewards platform makes a POST request to Teleskope's EAI API <font color="#22C55E"> </font>endpoint (e.g., <font color="#22C55E">/eai/v1/points?commit</font>). This request will include:
   1. <font color="#22C55E">user\_id</font>: The unique ID of the user (obtained from the initial JWT).
   2. <font color="#22C55E">points\_to\_deduct</font>: The total number of points to be deducted for the chosen rewards.
   3. <font color="#22C55E">transaction\_id</font>: A unique identifier generated by the Rewards platform for this specific redemption transaction.
   4. <font color="#22C55E">description</font>: A brief description of the reward redemption (e.g., "Redemption for \[Reward Name]").
3. Teleskope Processes Commit Request: Upon receiving the <font color="#22C55E">commit</font> request, Teleskope:
   1. Validates the <font color="#22C55E">user\_id</font> and <font color="#22C55E">points\_to\_deduct</font>.
   2. Checks if the user has sufficient points available.
   3. If successful: Temporarily "holds" or earmarks the <font color="#22C55E">points\_to\_deduct</font> for the given <font color="#22C55E">transaction\_id</font>, ensuring they cannot be spent elsewhere. Responds with a <font color="#22C55E">200 OK </font>status and a success message, acknowledging the commit request.
   4. If insufficient points or other error: Responds with a <font color="#22C55E">4xx</font> status code (e.g., <font color="#22C55E">400 Bad Request</font>) and an error message, indicating the failure.

### Phase 2: Complete (Confirm or Rollback)

- **Scenario A: Successful Redemption (Confirm)**

1. **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 <font color="#22C55E">confirm</font> endpoint (e.g., <font color="#22C55E">/eai/v1/points?confirm</font>). This request will include:
   1. <font color="#22C55E">user\_id</font>: The unique ID of the user.
   2. <font color="#22C55E">transaction\_id</font>: The same <font color="#22C55E">transaction\_id </font>used in the <font color="#22C55E">commit</font> request.
2. **Teleskope Processes Confirm Request:** Upon receiving the <font color="#22C55E">confirm</font> request, Teleskope:
   1. Permanently deducts the points previously held for the specified <font color="#22C55E">transaction\_id</font> and <font color="#22C55E">user\_id</font>.
   2. Responds with a <font color="#22C55E">200 OK</font> status and a success message.

- **Scenario B: Failed Redemption (Rollback)**

1. **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 <font color="#22C55E">rollback</font> endpoint (e.g., <font color="#22C55E">/eai/v1/points?rollback</font>). This request will include:
   1. <font color="#22C55E">user\_id</font>: The unique ID of the user.
   2. <font color="#22C55E">transaction\_id</font>: The same <font color="#22C55E">transaction\_id </font>used in the <font color="#22C55E">commit</font> request.
2. **Teleskope Processes Rollback Request:** Upon receiving the <font color="#22C55E">rollback</font> request, Teleskope:
   1. Releases the temporarily held points for the specified <font color="#22C55E">transaction\_id</font> and <font color="#22C55E">user\_id</font>, making them available again to the user.
   2. Responds with a <font color="#22C55E">200 OK </font>status and a success message.

## API Endpoints (Teleskope EAI API)

Teleskope will expose the following RESTful API endpoints:

- <font color="#22C55E">**POST /eai/v1/points?commit**</font>
  - **Description:** Initiates the first phase of the point deduction.
  - **Request Body (JSON):**&#x4A;SON

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

- **Response (200 OK - JSON):**&#x4A;SON

```json

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

- **Error Responses (4xx - JSON):**&#x4A;SON

```json

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

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



- <font color="#22C55E">**POST /eai/v1/points?confirm**</font>
  - **Description:** Confirms the point deduction after successful reward fulfillment.
  - **Request Body (JSON):**&#x4A;SON

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

- **Response (200 OK - JSON)\:JSON**

```json

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

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



- <font color="#22C55E">**POST /eai/v1/points?rollback**</font>
  - **Description:** Rolls back the point deduction in case of failed reward fulfillment.
  - **Request Body (JSON):**&#x4A;SON

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

- **Response (200 OK - JSON):**&#x4A;SON

```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 <font color="#22C55E">commit </font>request fails due to insufficient points, the Rewards platform should inform the user accordingly.