Overview

The Debit/Credit Wallet API allows you to update the points in the user's 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's 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 update loyalty balances based on user actions or rewards instantly. 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 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

📘

Metadata Validation

• You may include any number of key–value pairs.
• Do not send an empty object ({}) for metadata. If metadata is present but empty, the request fails with error code 777 and message metadata key value can not be empty.
• All key–value pairs in metadata are saved with each credit/debit transaction in the wallet transaction store.

📘

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 request to the Debit/Credit Wallet API, including the headers needed to authenticate the request:

curl -X POST "https://in1.api.clevertap.com/1/promo/creditDebit?identity=krishna123&walletId=1963" \
-H "X-CleverTap-Account-Id: ACCOUNT_ID" \
-H "X-CleverTap-Passcode: PASSCODE \
-H "Content-Type: application/json" 

Find CleverTap Account ID and Passcode

You can find the CleverTap Account ID and Passcode from the CleverTap dashboard by navigating to the Settings > Project page on the CleverTap dashboard.

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

{
   "description": "Reward points for purchase",
   "points": 100,
   "transactionType": "DEBIT",
   "orderId": "order123",
   "saleChannel": "POS",
   "saleAmount": 1000,
   "locationId": "BAN123",
   "metadata":
    {
     "RuleId": "123",
     "vouchercode": "oomco123",
     "brand": "amazon"
   }
}

 {
   "description": "Reward points for purchase",
   "points": 100,
   "transactionType": "CREDIT",
   "bucketType": "ACTIVE",
   "expiryDuration": "1d 10m",
   "activationDuration": "3d",
   "orderId": "order123",
   "saleChannel": "POS",
   "saleAmount": 1000,
   "locationId": "BAN123",
   "metadata":
    {
     "RuleId": "123",
     "vouchercode": "oomco123",
     "brand": "amazon"
   }
}

Sample Response

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

{
    "status": "success",
    "record": {
        "saleAmount": 1000,
        "walletId": 1963,
        "metadata": {
            "RuleId": "123",
            "brand": "amazon",
            "vouchercode": "oomco123"
        },
        "activePoints": 120.46,
        "orderId": "order123",
        "saleChannel": "POS",
        "locationId": "BAN123",
        "description": "Reward points for purchase",
        "tnxId": "wl_EjKlltmdYqrJYDiRaRcGv",
        "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.

📘

Note

Response fields are illustrative. The saleChannel, locationId, saleAmount, metadata response fields affect what is stored, not necessarily what is returned. If your implementation returns any of these fields, document them in your environment’s response schema.

Errors

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