API Endpoints

Cashback API

Earn and use cashback for member transactions on cashback cards.

Product API: These endpoints are part of the Cashback API. All endpoints begin with: /api/v1/cashback/

Earn Cashback

POST Earn Cashback
cashback_write
/api/v1/cashback/cashback/earn

Calculate and credit cashback to a member based on purchase amount.

How It Works

1

Configure Card

The cashback card has a configured cashback percentage (e.g., 5% back).

2

Send Transaction

Send card_id, member_id and purchase_amount to calculate cashback.

3

Credit Balance

Cashback is automatically credited to member's wallet balance.

Request Body

{
  "card_id": 10,
  "member_id": 123,
  "purchase_amount": 50.00,
  "reference": "ORDER-12345",
  "metadata": {
    "store_location": "Downtown",
    "cashier_id": "EMP-001"
  }
}

card_id (integer, required) - The cashback card ID
member_id (integer, conditional) - Member ID
email (string, conditional) - Member email (alternative to member_id)
phone (string, conditional) - Member phone (alternative to member_id)
member_name (string, optional) - Name for member auto-creation
purchase_amount (number, required) - Purchase amount
reference (string, optional) - Transaction reference
metadata (object, optional) - Additional metadata

Response

{
  "success": true,
  "data": {
    "transaction_id": 456,
    "purchase_amount": 50.00,
    "cashback_percentage": 5,
    "cashback_earned": 2.50,
    "new_balance": 12.50,
    "member_id": 123,
    "card_id": 10,
    "earned_at": "2025-01-15T10:30:00Z"
  }
}

Redeem Cashback

POST Redeem Cashback
cashback_write Member Auth Required
/api/v1/cashback/cashback/redeem

Redeem cashback from member balance for a discount or refund.

Authentication Required: This endpoint requires X-Member-Token header to protect member funds.

Step by Step

1

Authenticate Member

Member must be authenticated via OTP with X-Member-Token.

2

Verify Balance

System checks member has sufficient cashback available.

3

Process Redemption

Amount is debited from member's cashback balance.

Headers

X-App-Id: app_abc123...
X-Api-Key: test_xyz789...
X-Member-Token: eyJ0eXAiOiJKV1QiLCJhbGc...
Content-Type: application/json

Request Body

{
  "card_id": 10,
  "amount": 5.00,
  "pin": "1234",
  "reference": "REFUND-ORDER-12345"
}

card_id (integer, required) - Cashback card ID
amount (number, required) - Amount to redeem
pin (string, optional) - PIN for additional verification
reference (string, optional) - Custom transaction reference

Response

{
  "success": true,
  "data": {
    "transaction_id": 457,
    "amount_redeemed": 5.00,
    "new_balance": 7.50,
    "member_id": 123,
    "card_id": 10,
    "redeemed_at": "2025-01-15T11:00:00Z"
  }
}

Get Cashback Balance

GET Get Balance
cashback_read
/api/v1/cashback/cashback/balance

Retrieve member's current cashback balance on a specific card.

Query Parameters

GET /api/v1/cashback/cashback/balance?card_id=10&member_id=123

card_id (integer, required) - Cashback card ID
member_id (integer, required) - Member ID

Response

{
  "success": true,
  "data": {
    "card_id": 10,
    "member_id": 123,
    "cashback_balance": 12.50,
    "cashback_percentage": 5,
    "reward_system": "cashback",
    "queried_at": "2025-01-15T10:30:00Z"
  }
}

Transaction History

GET History
cashback_read
/api/v1/cashback/cashback/history

Retrieve member's cashback transaction history with pagination.

Query Parameters

GET /api/v1/cashback/cashback/history?card_id=10&member_id=123&limit=20&offset=0

Response

{
  "success": true,
  "data": {
    "card_id": 10,
    "member_id": 123,
    "transactions": [
      {
        "id": 456,
        "type": "earning",
        "amount": 2.50,
        "points": 0,
        "event": "cashback_earned",
        "created_at": "2025-01-15T10:30:00Z"
      },
      {
        "id": 457,
        "type": "redemption",
        "amount": -5.00,
        "points": 0,
        "event": "cashback_redeemed",
        "created_at": "2025-01-15T11:00:00Z"
      }
    ],
    "pagination": {
      "limit": 20,
      "offset": 0,
      "total": 45,
      "has_more": true
    }
  }
}

Refund Cashback

POST Refund Cashback
cashback_write
/api/v1/cashback/cashback/refund

Reverse/deduct cashback previously earned on a purchase. Use when an order is refunded.

Note: The system will automatically calculate cashback to deduct based on the refund amount, or you can specify an explicit amount.

Request Body

{
  "card_id": 10,
  "member_id": 123,
  "refund_amount": 25.00,
  "reference": "REFUND-ORDER-12345"
}

card_id (integer, required) - Cashback card ID
member_id (integer, conditional) - Member ID
email (string, conditional) - Member email (alternative to member_id)
phone (string, conditional) - Member phone (alternative to member_id)
refund_amount (number, required) - Refund amount
cashback_to_deduct (number, optional) - Explicit cashback to deduct
reference (string, optional) - Transaction reference

Response

{
  "success": true,
  "data": {
    "transaction_id": 459,
    "cashback_deducted": 1.25,
    "refund_amount": 25.00,
    "previous_balance": 12.50,
    "new_balance": 11.25,
    "currency": "TND",
    "member_id": 123,
    "card_id": 10,
    "reference": "REFUND-ORDER-12345",
    "balance_warning": null,
    "refunded_at": "2025-01-15T12:00:00Z"
  }
}

Cashback Cards

The cards endpoints allow you to list and retrieve details about available cashback cards.

GET List Cards
card_read
/api/v1/cashback/cards

List all cashback cards available to your application.

Response

{
  "success": true,
  "data": {
    "cards": [
      {
        "id": 10,
        "unique_identifier": "CASH-001",
        "name": "Premium Cashback Card",
        "description": "5% cashback on all purchases",
        "reward_system": "cashback",
        "cashback_config": {
          "cashback_percentage": 5.0,
          "cashback_min_amount": 10.0,
          "cashback_max_amount": 1000.0,
          "allows_pin_redemption": true
        }
      }
    ],
    "total": 1
  }
}
ESC
↵ to select
esc to close