Top-up

Overview

This endpoint is used to add funds (reload/top-up) to an existing prepaid card. You can also optionally activate the card or update the associated customer information within the same request.

Environments

Environment	Protocol	HTTP Method	URL
Sandbox	HTTPS	POST	https://uat.paywizard.biz/ovstrade/openLoyaltyPay/giftIssuance
Production	HTTPS	POST	https://portal.paywizard.biz/ovstrade/openLoyaltyPay/giftIssuance

---

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	The unique order ID for this reload transaction, generated by your system.
loyaltyChannel	String	Yes	The prepaid channel provider. See Prepaid Channels for valid values.
accountId	String	Yes	The unique identifier for the prepaid card.
entryType	String	Yes	The method used to input the accountId. See Entry Type Codes below.
activating	String	No	Set to "Y" to activate the card or "N" to not activate.
customerInfo	Object	No	A JSON object containing the customer's details. See CustomerInfo Object structure below.

CustomerInfo Object (Optional)

Parameter	Type	Required	Description
customerType	String	No	1: Primary account holder, 2: Alternate, 3: Giver of card.
firstName	String	No	Customer's first name.
middleName	String	No	Customer's middle name.
lastName	String	No	Customer's last name.
address1	String	No	Primary address line.
address2	String	No	Secondary address line.
city	String	No	City name.
state	String	No	State or province.
postal	String	No	Postal code (must be a valid format for the country).
country	String	No	2-character ISO 3166-1 country code.
mailPref	String	No	Mail preference. O: Opt-out, I: Opt-in.
phone	String	No	Phone number in the format +CCC AAA LLL LLL xEEEE.
isMobile	String	No	Y: Yes, N: No.
phonePref	String	No	Phone contact preference. O: Opt-out, I: Opt-in.
email	String	No	Customer's email address.
emailPref	String	No	Email contact preference. O: Opt-out, I: Opt-in.
birthday	String	No	Customer's birthday in YYYYMMDD format.
anniversary	String	No	Customer's anniversary in YYYYMMDD format.
gender	String	No	M: Male, F: Female.

Entry Type Codes

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

Request Example

{
    "clientId": "825429536610058240",
    "tranOrderNo": "20250401123534801",
    "loyaltyChannel": "FACTOR4",
    "accountId": "914639258868515",
    "entryType": "K",
    "activating": "Y",
    "customerInfo": {
        "customerType": "1",
        "firstName": "Jon1",
        "middleName": "Mid2",
        "lastName": "Doe3",
        "address1": "295R+VM Settat, Morocco",
        "address2": "Settat,Morocco",
        "city": "Morocco",
        "state": "Settat",
        "postal": "",
        "country": "US",
        "mailPref": "O",
        "phone": "[phone]",
        "isMobile": "N",
        "phonePref": "O",
        "email": "[e-mail]",
        "emailPref": "O",
        "birthday": "20000101",
        "anniversary": "",
        "gender": ""
    }
}

---

Response Body

The response object contains the status of the reload transaction request.

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 unique transaction ID generated by the payment platform.
data.transIndexCode	String	A unique transaction reference code.
data.amount	String	The transaction amount that was reloaded.
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 reload request.

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

Success Response Example

{
    "code": 200,
    "msg": "success",
    "timestamp": "2025-07-24 15:52:21",
    "data": {
        "mid": "202507081058",
        "paywizardId": "10020000080",
        "checkoutId": "933434611567034368",
        "transIndexCode": "100200000809631006007",
        "amount": "10000",
        "result": 0
    }
}