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.

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}"
}'

Upon making the API call, you may receive 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).

Additional Resources

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

API-Triggered Rules Overview