Starting Session

Get Session Token (Authentication)

POST /v2/session/startSession

To authenticate and begin your session, you will need to provide the following credentials in a secure POST request:

Request Headers:

• Content-Type: application/json
• x-source-customer-id: string
  
  

Note: Refer to the Security Requirements section on suggestions to secure the x-source-customer-id. Also for customers who have not linked a card to the Cardlytics Rewards platform, you can use no-user-available as the x-source-customer-id to receive a valid token.

Request Payload:

• clientId: Your unique clientId provided by Cardlytics.
• secret: A secure secret key shared with you by Cardlytics.

Request Payload Sample:

{
  "clientId": "String",
  "secret": "String"
}

Response

Upon successful authentication, the API will provide a bearer token that you can use to access our services.

Token Details:

• Bearer Token Validity: The token is valid for 15 minutes from the time of issue.

• This Bear Token should be cached for subsequent API calls.

• Only request a new token if the previous one has expired.

Errors and Handling Expired Tokens:

• Providing an invalid clientId or clientSecret the API will return a 500 Internal Server Error

• If your token expires, all subsequent API requests will return a 401 Unauthorized response indicating that the session is no longer valid.

• To continue accessing the API, you must request a new token using the same token generation endpoint (POST /v2/session/startSession).

Link SDK

Overview

The Link SDK provides several methods to manage customers’ account linking between your application and financial institutions through our platform. Below you'll find detailed explanations of how to use each method.

Methods

1. getAccountLinkStatus

   • Description: Retrieves the account linking status. {#exceptions:}

   • Parameters:

     • cdlxSessionToken (string): A valid CDLX session token. {#exceptions:}

     • x-source-customer-id (string): A valid source customer Id. Should be the same hashed id used during /startSession

   • Returns: CardlyticsCustomerProfile

2. startAccountLink

   • Description:

     Initiates the account linking process. The process varies depending on the selected link provider but aims to store an access token in the CDLX backend.

   • Parameters:

     • cdlxSessionToken (string): A valid CDLX session token.

     • linkProvider (string): Must be one of the supported linking providers. Currently supports "PLAID_HOSTED". {#exceptions:}

     • redirect_uri (string): The URL to redirect to after a successful link.

     • x-source-customer-id (string): A valid source customer Id. Should be the same hashed id used during /startSession

   • Returns: void

   • Exceptions:

     • Invalid linkProvider value.

     • Invalid session token value (401).

     • Other errors from CDLX APIs.

3. deleteAccountLink

   • Description: Deletes an existing account link.

   • Parameters:

     • cdlxSessionToken (string): A valid CDLX session token.

     • accountLinkId (string): The ID of the account link.

     • x-source-customer-id (string): A valid source customer Id.

   • Returns: A Promise that resolves to a boolean indicating success or failure.

   • Exceptions: Rejects under error cases.

Script Tag

To include the Cardlytics Link SDK in your project, use the following script tag:

<script src="/linking-sdk/v1/cardlytics-linking-sdk.js"></script>

Security Requirements

Use HMAC-SHA-256 to obfuscate x-source-customer-id:

Example (Node.js):

const crypto = require('crypto');
function hashCustomerId(customerId, secret) {
  return crypto.createHmac('sha256', secret).update(customerId).digest('hex');
}