# Incentive Account Creation & Points Allocation

This API enables you to create a **incentive account for your partners** and **allocate or reallocate points** (either credit or debit). It is suitable for use cases like partner onboarding, incentive programs, or points management.

  ### How It Works

<Container>
    ### <span style="color:#0a58ca">Create a new user and allocate initial incentive points</span>
    


* `transactionType`: `CR` *(Credit)*
* `type`: `ALLOCATE_POINT`
</Container>


<Container>
  ### <span style="color:#0a58ca">Credit points to an existing incentive account</span>

* `transactionType`: `CR`
* `type`: `ALLOCATE_POINT`
</Container>


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

* `transactionType`: `DR` *(Debit)*
* `type`: `UNALLOCATE_POINT`
</Container>


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

| **Field**               | **Where It's Used** | **Description**                                                |
| ----------------------- | ------------------- | -------------------------------------------------------------- |
| `uniqueReferenceNumber` | Request             | Sent by the client to uniquely identify the transaction        |
| `pgReferenceNumber`     | Response            | Returned by EnKash for transaction confirmation & traceability |

:::tip[]
These **must match** to ensure transaction traceability
:::
</Container>

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

```
POST /api/v0/partner/enKashCard/points/allocate
```

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

**Header Parameters**

| Name            | Type   | Required | Example                   |
| --------------- | ------ | -------- | ------------------------- |
| `partnerId`     | string | <Icon icon="solar-bold-check-circle"/>       | `CRMXWB3ZM`               |
| `Content-Type`  | string | <Icon icon="solar-bold-check-circle"/>       | `application/json`        |
| `Authorization` | string | <Icon icon="solar-bold-check-circle"/>        | `Bearer {{access_token}}` |

**Body Parameters**

| Field                   | Type   | Required | Description                              |
| ----------------------- | ------ | -------- | ---------------------------------------- |
| `companyId`             | string | <Icon icon="solar-bold-check-circle"/>         | Unique EnKash Company ID                 |
| `cardAccountId`         | string | <Icon icon="solar-bold-check-circle"/>         | Reward account ID                        |
| `transactionCode`       | string | <Icon icon="solar-bold-check-circle"/>         | Type of transaction (e.g., `ALLOCATION`) |
| `transactionType`       | string | <Icon icon="solar-bold-check-circle"/>         | `CR` for credit, `DR` for debit          |
| `type`                  | string | <Icon icon="solar-bold-check-circle"/>         | `ALLOCATE_POINT` or `UNALLOCATE_POINT`   |
| `email`                 | string | <Icon icon="solar-bold-check-circle"/>         | Employee’s email                         |
| `mobile`                | string | <Icon icon="solar-bold-check-circle"/>         | Employee’s mobile                        |
| `title`                 | string | <Icon icon="solar-bold-check-circle"/>         | Mr/Mrs/Ms                                |
| `firstName`             | string | <Icon icon="solar-bold-check-circle"/>         | Employee’s first name                    |
| `gender`                | string | <Icon icon="solar-bold-check-circle"/>         | M/F                                      |
| `loadAmount`            | number | <Icon icon="solar-bold-check-circle"/>         | Amount of points                         |
| `uniqueReferenceNumber` | string | <Icon icon="solar-bold-check-circle"/>         | Unique transaction reference ID          |

**Example 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,
  "uniqueReferenceNumber": "TEST234236"
}
```
### <span style="color:#0a58ca">Response</span>

**HTTP Status Code `200 OK`**

**Response Body**

| Field                 | Type    | Description                          |
| --------------------- | ------- | ------------------------------------ |
| `code`                | integer | `0` = success                        |
| `message`             | string  | API status message                   |
| `payload`             | object  | Contains card and user details       |
| `enKashCardId`      | string  | Unique card ID                       |
| `enkashCardTxnId`   | string  | Transaction ID                       |
| `otbBalance`        | number  | Available balance on the reward card |
| `pgReferenceNumber` | string  | Matches your `uniqueReferenceNumber` |

**Example Response**

```json
{
  "code": 0,
  "message": "Success",
  "payload": {
    "enKashCardId": "EKC04AZHXP",
    "enkashCardTxnId": "ECTRSZJ8CRJ2E",
    "cardAccountId": "CAQL8YCV3",
    "email": "xyz2@gmail.com",
    "mobile": "9600098867",
    "title": "Mr",
    "firstName": "hedfdfg",
    "gender": "M",
    "otbBalance": 11,
    "companyId": "CEK1PU9AOO",
    "cardStatus": {
      "name": "UL",
      "label": "UnLocked"
    },
    "kycStatus": {
      "name": "VERIFIED",
      "label": "Verified"
    },
    "binType": {
      "name": "REWARD",
      "label": "Reward Card"
    },
    "cardActivated": true,
    "virtualAccountNumber": "ENKASHEDENKEKC04AZHXP",
    "rewardPointsReceived": 11
  }
}
```

<TipGood>Ensure employee’s card is **active** and **KYC verified**</TipGood>
<TipGood>For debit operations (`UNALLOCATE_POINT`), ensure sufficient balance exists</TipGood>
<TipGood>Use **matching reference numbers** for consistent reconciliation</TipGood>