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.

---

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.

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