# Allocating Rewards Using EnKash APIs

This section guides you through the sequence of actions required to allocate or manage reward points for a user via EnKash’s reward system.


<Tabs>
  <Tab title="Create Single User">
      <Container>
  ### <span style="color:#0a58ca">1. Obtain Onboarding Identifiers</span>

Before initiating any API requests, ensure you have the following identifiers from EnKash after onboarding:

| **Field**       | **Description**                                 |
| --------------- | ----------------------------------------------- |
| `companyId`     | Unique ID assigned to your company by EnKash.   |
| `cardAccountId` | Reward account ID associated with your company. |
| `partnerId`     | Partner ID assigned during onboarding.          |

</Container>

    
<Container>
    ### <span style="color:#0a58ca">2. Create Reward Account and Allocate Points</span>

Use this functionality to **create a new user** and allocate initial reward points to their account.
 
**Set the following parameters:**

- `transactionType`: `CR` *(Credit)*
- `type`: `ALLOCATE_POINT`

**Required Details:**

| Field         | Description                        |
|---------------|------------------------------------|
| `firstName`   | Employee's first name              |
| `email`       | Employee's email address           |
| `mobile`      | Employee's mobile number           |
| `gender`      | Employee's gender (M/F)            |
| `title`       | Employee's title (Mr/Mrs/Ms)       |
| `loadAmount`  | Initial points to be credited      |

**Sample Request:**

```json
{
  "companyId": "CEK1PU9AOO",
  "cardAccountId": "CAQL8YCV3",
  "transactionCode": "ALLOCATION",
  "transactionType": "CR",
  "type": "ALLOCATE_POINT",
  "email": "xyz2@gmail.com",
  "mobile": "9600098867",
  "title": "Mr",
  "firstName": "hedfdfg",
  "gender": "M",
  "loadAmount": 11,
  "uniqueReferenceNum": "TEST234236"
}
```

</Container>


<Container>
     ### <span style="color:#0a58ca">3. Topup Existing Reward Account</span>

Use this to top-up an existing reward account with additional points.

**Set the following parameters:**

- `transactionType`: `CR` *(Credit)*
- `type`: `ALLOCATE_POINT`

**Required Details:**

| Field              | Description                                      |
|--------------------|--------------------------------------------------|
| `enkashCardId`     | Unique card ID *(required if `cardAccountId` not used)* |
| `cardAccountId`    | Unique reward account ID *(required if `enkashCardId` not used)* |
| `loadAmount`       | Points to be credited                           |
| `email` / `mobile` | *(Optional)* User identifiers for validation     |

</Container>


<Container>
    ### <span style="color:#0a58ca">4. Unallocate / Debit Points</span>

Use this to reverse/remove (debit) points from a reward account  (e.g., refunds or corrections).

**Set the following parameters:**

- `transactionType`: `DR` *(Debit)*
- `type`: `UNALLOCATE_POINT`

**Required Details:**

| Field              | Description                                      |
|--------------------|--------------------------------------------------|
| `enkashCardId`     | Unique card ID *(required if `cardAccountId` not used)* |
| `cardAccountId`    | Unique reward account ID *(required if `enkashCardId` not used)* |
| `loadAmount`       | Points to be debited                             |

</Container>


<Container>
     ### <span style="color:#0a58ca">5. Validate the Response</span>

You will receive a response with transaction and `cardAccount` details. Verify that the `pgReferenceNumber` in the response matches your `uniqueReferenceNumber`.

**Sample Response Snippet:**

```json
{
  "code": 0,
  "message": "Success",
  "payload": {
    "enKashCardId": "EKC04AZHXP",
    "enkashCardTxnId": "ECTRSZJ8CRJ2E",
    "pgReferenceNumber": "TEST234236",
    "otbBalance": 11,
    "maskedNumber": "XXXX XXXX XXXX 8867",
    ...
  }
}
```
</Container>

  </Tab>
  <Tab title="Create Multiple Users">

This functionality allows you to **create reward accounts and allocate points in bulk** for multiple users in a single request. 

      **Ideal for**

* Reward campaigns
* Employee incentive programs
* Loyalty point distributions

 <Container>
  ### <span style="color:#0a58ca">1. Obtain Onboarding Identifiers</span>

Before initiating any API requests, ensure you have the following identifiers from EnKash after onboarding:

| **Field**       | **Description**                                 |
| --------------- | ----------------------------------------------- |
| `companyId`     | Unique ID assigned to your company by EnKash.   |
| `cardAccountId` | Reward account ID associated with your company. |
| `partnerId`     | Partner ID assigned during onboarding.          |

</Container>
      
### <span style="color:#0a58ca">Endpoint</span>

```
POST /api/v0/partner/enKashCard/points/allocate/bulk
```
### <span style="color:#0a58ca">Request Format</span>

Send a JSON array where each object represents one user and their allocation data.

**Example Request**

```json
[
  {
    "userId": "USER123",
    "companyId": "COMP456",
    "cardAccountId": "CA789",
    "points": 100,
    "reason": "Performance bonus"
  },
  {
    "userId": "USER124",
    "companyId": "COMP456",
    "cardAccountId": "CA789",
    "points": 150,
    "reason": "Sales target achievement"
  }
]
``` 
### <span style="color:#0a58ca">Error Handling</span>

**422 UNPROCESSABLE_ENTITY**

> The request is syntactically valid but semantically incorrect

**Possible Messages:**

:::danger[]
Company Id is required if it is an Enkash User
:::
:::danger[]
Primary Enkash card is not present. So bulk upload cannot be done
:::
:::danger[]
KYC is not uploaded or under review for the primary card. So bulk upload cannot be done
:::
:::danger[]
Bin Type is not mapped on PlanMaster
:::
:::danger[]
Card Account does not exist for this partner
:::

**404 NOT_FOUND**

> The requested resource was not found

**Example Message:**
      
:::danger[]
Card account not found for **companyId** and **cardAccountId**
:::

  </Tab>
</Tabs>

### <span style="color:#0a58ca">Reference Number Mapping</span>

| **Parameter**           | **Where It’s Used** | **Purpose**                                       |
| ----------------------- | ------------------- | ------------------------------------------------- |
| `uniqueReferenceNumber` | Request payload     | Identifies the transaction uniquely (client side) |
| `pgReferenceNumber`     | Response payload    | EnKash's confirmation reference for traceability  |

<TipGood>These must match to confirm the transaction has been successfully tracked</TipGood>

### <span style="color:#0a58ca">Data Schema</span>

| **Field**               | **Type** | **Description**                                             |
| ----------------------- | -------- | ----------------------------------------------------------- |
| `companyId`             | `string` | Unique EnKash company ID (provided on onboarding)          |
| `cardAccountId`         | `string` | EnKash reward account ID                                   |
| `transactionCode`       | `enum`   | Type of transaction (e.g., `ALLOCATION`)                   |
| `transactionType`       | `enum`   | Direction of transaction (`CR` or `DR`)                    |
| `type`                  | `enum`   | Transaction purpose (`ALLOCATE_POINT`, `UNALLOCATE_POINT`) |
| `email`                 | `string` | Email ID of the cardholder                                 |
| `mobile`                | `string` | Mobile number of the cardholder                            |
| `title`                 | `string` | Title of the cardholder (Mr/Mrs/Ms)                        |
| `firstName`             | `string` | First name of the cardholder                               |
| `gender`                | `string` | Gender (M/F).                                               |
| `loadAmount`            | `number` | Amount of points to credit or debit                        |
| `uniqueReferenceNumber` | `string` | Unique identifier from the partner for traceability        |