# Add Tip

#### Overview

This endpoint is used to add a tip to a previously completed prepaid card transaction. This is often used in restaurant or service environments where the tip amount is determined after the initial payment is made.

#### Environments

| Environment | Protocol | HTTP Method | URL                                                            |
| ----------- | -------- | ----------- | -------------------------------------------------------------- |
| Sandbox     | HTTPS    | `POST`      | `https://uat.paywizard.biz/ovstrade/openLoyaltyPay/giftTip`    |
| Production  | HTTPS    | `POST`      | `https://portal.paywizard.biz/ovstrade/openLoyaltyPay/giftTip` |

#### Authentication

Authentication is handled through a JSON Web Token (JWT) included in the request header. A signature must also be provided in the headers for request verification.

For detailed instructions on generating the required signature, please refer to our [Signature Generation Guide](https://oversea.hs1c.cn/showdoc/web/#/671575440/155776446).

***

#### Endpoint: Add Tip to Prepaid Transaction

`POST /ovstrade/openLoyaltyPay/giftTip`

**Headers**

| Key            | Type   | Required | Description                                                                                                         |
| -------------- | ------ | -------- | ------------------------------------------------------------------------------------------------------------------- |
| `Content-Type` | String | Yes      | Must be `application/json`.                                                                                         |
| `jwt-token`    | String | Yes      | The transaction token obtained using your developer credentials.                                                    |
| `sign`         | String | Yes      | The request signature. See [Signature Generation Guide](https://oversea.hs1c.cn/showdoc/web/#/671575440/155776446). |

**Request Body Parameters**

| Parameter      | Type   | Required | Description                                                                                                                  |
| -------------- | ------ | -------- | ---------------------------------------------------------------------------------------------------------------------------- |
| `clientId`     | String | Yes      | Your unique developer ID.                                                                                                    |
| `tranOrderNo`  | String | Yes      | A new, unique order ID for this specific tip transaction, generated by your system.                                          |
| `oriOrderNo`   | String | Yes      | The `checkoutId` of the original payment transaction to which the tip is being added.                                        |
| `tranCurrency` | String | Yes      | The 3-letter ISO currency code for the tip amount. Example: `"USD"`.                                                         |
| `amount`       | String | Yes      | The tip amount to be added.                                                                                                  |
| `accountId`    | String | Yes      | The unique identifier for the prepaid card used in the original transaction.                                                 |
| `entryType`    | String | Yes      | The method used to input the `accountId`. See [Entry Type Codes](https://www.google.com/search?q=%23entry-type-codes) below. |

**Entry Type Codes**

| Code | Description                 |
| ---- | --------------------------- |
| `B`  | Barcode                     |
| `K`  | Keyed (manually entered)    |
| `M`  | Magnetic Stripe             |
| `P`  | Proximity (NFC/Contactless) |

**Request Example**

JSON

```
{
    "clientId": "825429536610058240",
    "tranOrderNo": "20250401123534801",
    "accountId": "914639258868515",
    "entryType": "K",
    "amount": "2.00",
    "tranCurrency": "USD",
    "oriOrderNo": "927994263952818176"
}
```

***

**Response Body**

The response object contains the status of the tip adjustment transaction.

| Parameter             | Type    | Description                                                                                                                                                    |
| --------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `code`                | Integer | The HTTP status code. `200` indicates a successful request.                                                                                                    |
| `msg`                 | String  | A human-readable message. `success` on successful requests.                                                                                                    |
| `timestamp`           | String  | The UTC timestamp of the response. Format: `YYYY-MM-DD HH:mm:ss`.                                                                                              |
| `data`                | Object  | A container for the successful response data. Null on error.                                                                                                   |
| `data.mid`            | String  | The merchant ID.                                                                                                                                               |
| `data.paywizardId`    | String  | The unique platform ID for the transaction.                                                                                                                    |
| `data.checkoutId`     | String  | The new, unique transaction ID for this tip adjustment, generated by the payment platform.                                                                     |
| `data.transIndexCode` | String  | A unique transaction reference code.                                                                                                                           |
| `data.amount`         | String  | The tip amount that was processed.                                                                                                                             |
| `data.result`         | Integer | An integer code representing the status of the transaction. See [Transaction Status Codes](https://www.google.com/search?q=%23transaction-status-codes) below. |

**Transaction Status Codes**

The `result` field indicates the immediate outcome of the tip adjustment request.

| Result Code | Description           |
| ----------- | --------------------- |
| `0`         | Success               |
| `1`         | Failure               |
| `2`         | Pending / In Progress |

**Success Response Example**

JSON

```
{
    "code": 200,
    "msg": "success",
    "timestamp": "2025-07-24 17:09:24",
    "data": {
        "mid": "202507081058",
        "paywizardId": "10020000080",
        "checkoutId": "933454027025416192",
        "transIndexCode": "100200000800256343351",
        "amount": "20000",
        "result": 0
    }
}
```
