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, as follows:

• Redeeming Wallet Points in Transactions: Enable users to redeem wallet points during transactions, providing a seamless way to use their loyalty rewards.
• Crediting Points to User Wallets: Add points to user wallets as 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 to ensure the loyalty balance remains accurate.

Example Use Case

Consider an example in which a user makes a $200 purchase 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: Set the wallet balance to 150 points to ensure the user's wallet accurately reflects the redeemed points.

Base URL

The following is a sample base URL:

https://<region>.api.clevertap.com/1/promo/creditDebit

For region-specific endpoints, refer to Region.

HTTP Method

POST

Headers

For more information about API headers, refer to Headers.

Query Parameters

The following table lists the required query parameters.

Body Parameters

The following table lists the body parameters.

Example Request

The following is a sample request to the Debit/Credit Wallet API, showing the headers needed to authenticate the request. The full set of request body options for debit and credit transactions is shown in the payload examples below.

curl -X POST "https://<region>.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" \
-d '{
  "description": "Reward points for purchase",
  "points": 100,
  "transactionType": "DEBIT",
  "orderId": "order123",
  "saleChannel": "POS",
  "saleAmount": 1000,
  "locationId": "BAN123",
  "metadata": {
    "RuleId": "123",
    "vouchercode": "oomco123",
    "brand": "amazon"
  }
}'

Find CleverTap Account ID and Passcode

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

The following are the request payload examples for debit and 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",
  "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": "PENDING",
  "activationDuration": "3d",
  "expiryDuration": "1d 10m",
  "orderId": "order123",
  "saleChannel": "POS",
  "saleAmount": 1000,
  "locationId": "BAN123",
  "metadata": {
    "RuleId": "123",
    "vouchercode": "oomco123",
    "brand": "amazon"
  }
}

Example Response

The following is a sample response. On a successful API call, the system debits or credits the specified points from the user's wallet and returns the updated wallet balance and transaction details.

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

Errors

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