Point API Integration Guide

In this guide, we'll show you all the information you need to get started, from obtaining access tokens to making API calls and handling callbacks.

Begin development in the staging environment to test and debug the integration. Once testing is successful, promote the integration to the production environment for live usage.

Getting Started

Here's a simplified overview of how the integration works:

Obtain Credentials

First, obtain the necessary credentials from the organization owner. You'll need the the following information to authenticate your requests.

Client ID
Client secret
Point-earning rule ID, or point redemption rule ID

Request Token

Next, make an API call to request a token for authentication.

Obtain Credentials

curl --location '{abc-auth-url}/realms/partner/protocol/openid-connect/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'client_id={your-client-id}' \
--data-urlencode 'client_secret={you-client-secret}' \
--data-urlencode 'grant_type=client_credentials'

Call the API to Earn or Redeem Points

Once you have the token, you can use it to make API calls to earn or redeem points asynchronously. We provide two options for making the API call, with or without signing.

Call the API to Earn or Redeem Points without Signing

If your system does not support signing, you can make the API call without the signature. Here's an example of it:

Call Point API

curl --location '{point-url-endpoint}' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {you-access-token}' \
--data '{
    "userId": "{your-user-id}",
    "ruleId": "{point-rule-id}",
    "amount": {point-amount},
    "requestId": "{your-request-id}",
    "callbackUrl": "{your-callback-url}"
}'

Call the API to Earn or Redeem Points with Signature

If you would like to make the call more secure, you can make the API call with the signature by using this example:

Note: To implement API call with Signature, Please send your Public Key and contact us to enable it for you.

Call Point API

curl --location '{point-url-endpoint}' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {you-access-token}' \
--header 'Digest: SHA-512={base64Hash}' \
--header 'Signature: keyId="${key}",algorithm="RSA-SHA256",created=${timestampInSec},headers="(created) digest (request-target)",signature="${sign}"' \
--data '{
    "userId": "{your-user-id}",
    "ruleId": "{point-rule-id}",
    "amount": {point-amount},
    "requestId": "{your-request-id}",
    "callbackUrl": "{your-callback-url}"
}'

Upon making the API call with any option, you will receive one of the following HTTP responses:

HTTP	Message	Description
202	Accepted	The API request has been successfully verified, and the points transaction is in progress.
400	Invalid Request	Your request contains invalid parameters, the specified rule is not found, inactive, or outside its active period, the user is invalid, or the request lacks sufficient balance. Ensure all parameters are correct and try again.
401	Access Denied	Your request lacks sufficient scope permissions. Make sure your authentication credentials have the necessary access rights.
403	Access Forbidden	Your client is not authorized to access this resource. Check your client credentials and ensure they are properly authenticated.
500	Internal Server Error	An internal server error occurred. Please try your request again later. If the issue persists, contact support for assistance.

Handling Callback Results

After making the API call to earn or redeem points, you'll receive a callback with the processing result.

Success

{
  "action": "point_earn",
  "clientId": "{your-client-id}",
  "userId": "{user-id}",
  "requestId": "{your-request-id}",
  "ruleId": "{point-rule-id}",
  "point": {point-amount},
  "transactionId": "{abc-transaction-id}",
  "timestamp": "2024-04-12T07:41:26.633135053Z",
  "status": "success"
}

action: The action performed (point_earn or point_burn).
point: The amount of points earned or redeemed.
requestId: Your request ID.
transactionId: Transaction ID from our system.
status: Status of the transaction (success or failed).

Note: If the earned or redeemed point amount is not equal to the requested amount, it indicates that the maximum cap amount has been reached. The amount received is the maximum amount that can be processed.

Failed

{
  "action": "point_earn",
  "clientId": "{your-client-id}",
  "userId": "{user-id}",
  "requestId": "{your-request-id}",
  "ruleId": "{point-rule-id}",
  "timestamp": "2024-04-12T07:41:26.633135053Z",
  "status": "failed",
  "errorMessage": "Reaching Earning Limit"
}

errorMessage: Reason for failure (e.g., reaching earning limit, redemption limit, insufficient balance, unexpected error).

Get the Customer Point balance

Get Point Balance API

curl --location '{baseURL}/latitude-points/orgs/{orgId}/point-programs/default/balances/{userId}' \
--header 'accept: application/json, text/plain, /' \
--header 'authorization: Bearer {you-access-token}'

Additional Resources

To access URLs for staging or production environments, please refer to the API Overview.

API-Triggered Rules API Guide