Overview

The Debit/Credit Wallet API allows you to update the points in the user wallet by either debiting (subtracting) or crediting (adding) them. The wallet ledger balance is updated immediately after the transaction is processed.

This API provides flexibility for a range of scenarios where point adjustments are required for the user wallet as follows:

• Redeeming Wallet Points in Transactions: Enable users to redeem wallet points during transactions, providing them with a seamless way to utilize their loyalty rewards.
• Crediting Points to User Wallets: Add points to the user wallet as and when needed.

This API is essential for businesses managing customer loyalty programs. It allows you to instantly update loyalty balances based on user actions or rewards. For example, if a user earns 100 loyalty points after a purchase, the API instantly credits the points to their wallet. Later, if the user returns the item, the API can debit the corresponding points, ensuring the loyalty balance remains accurate. By leveraging this API, businesses can enhance user experience and build trust through accurate and immediate loyalty point transactions.

Example Use Case

Consider an example user case where a user makes a purchase worth $200 and has a balance of 200 points in their wallet. You can use the Debit/Credit Wallet API to seamlessly redeem wallet points during this transaction as follows:

1. Determine Redemption Details: With a conversion rate of 1 point = $1, this redemption translates into a $50 discount.

2. Calculate Final Payable Amount: Apply the $50 discount to the purchase amount of $200. The user’s final payable amount is $150.

3. Invoke the Debit API: Invoke the Debit API to deduct the redeemed points from the user's wallet after completing the transaction successfully. Pass the transaction details, such as walletId, identity, and points to be debited (in this case, 50) in the API request.

4. Update Wallet Ledger: Update the wallet balance to 150 points, ensuring the user wallet accurately reflects the redeemed points.

📘

Example Credit Use Case

This above example illustrates a scenario specific to the Debit API. Consider an example where the current user balance is 200 points and earns 50 points after a transaction. In this case, the Credit API is invoked to add points to the user wallet, updating the wallet balance to 250 points.

Base URL

Here is an example base URL from the account in the India region

https://in1.api.clevertap.com/1/promo/creditDebit

Region

To identify the API endpoint for the region of your account, refer to Region.

Headers

For more information about API headers used while processing API requests, refer to Headers.

HTTP Method

POST

Query Parameters

Body Parameters

📘

Debit Transactions Validation

If debit transactions exceed available active points, they are not processed to prevent overdrafts in the wallet.

Sample Request

Here is an example HTTP request to the Debit/Credit Wallet API, including the headers needed to authenticate the request:

POST /https://in1.api.clevertap.com/1/promo/creditDebit?walletId=1000&identity=User2 HTTP/1.1
Authorization: Basic {API Key: Secret Key}
Content-Type: application/json

The following are the request payloads for debit/credit transactions:

{
    "description": "Reward points for purchase",
    "points": 100,
    "transactionType": "DEBIT",
    "bucketType": "",
    "expiryDuration": "",
    "activationDuration": "",
    "orderId": "order123"
}

 {
    "description": "Reward points for purchase",
    "points": 100,
    "transactionType": "CREDIT",
    "bucketType": "PENDING",
    "expiryDuration": "1d 10m",
    "activationDuration": "3d",
    "orderId": "order123"
}

Sample Response

The sample response returns the updated wallet balance and transaction details in the following format:

{
    "status": "success",
    "record": {
        "walletId": 1000,
        "activePoints":200,
        "orderId": "order123",
        "description": "points redeemed for a purchase",
        "tnxId": "wl_YLKUlWbHU4MKySZhoGqLV",
        "points": 100
    }
}

On a successful API call, the system debits or credits the specified points from the user's wallet based on the transactionType in the request body and returns a response indicating the updated wallet balance and transaction details.

Errors

To know the errors applicable to the Debit/Credit Wallet API, refer to API Error Cases.