# 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

<table><thead><tr><th width="124.5999755859375">Environment</th><th width="83.800048828125">Protocol</th><th width="61.79998779296875">HTTP Method</th><th>URL</th></tr></thead><tbody><tr><td>Sandbox</td><td>HTTPS</td><td><code>POST</code></td><td><code>https://uat.paywizard.biz/ovstrade/openLoyaltyPay/giftIssuance</code></td></tr><tr><td>Production</td><td>HTTPS</td><td><code>POST</code></td><td><code>https://portal.paywizard.biz/ovstrade/openLoyaltyPay/giftIssuance</code></td></tr></tbody></table>

***

## **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](../cloud-api/paywizard-open-platform-api-signature-guide-v3). |

## **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](https://oversea.hs1c.cn/showdoc/web/#/671575440/155776425) 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](https://www.google.com/search?q=%23entry-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](https://www.google.com/search?q=%23customerinfo-object-optional) 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**

<table><thead><tr><th width="115.5999755859375">Code</th><th>Description</th></tr></thead><tbody><tr><td><code>B</code></td><td>Barcode</td></tr><tr><td><code>K</code></td><td>Keyed (manually entered)</td></tr><tr><td><code>M</code></td><td>Magnetic Stripe</td></tr><tr><td><code>P</code></td><td>Proximity (NFC/Contactless)</td></tr></tbody></table>

### **Request Example**

```json
{
    "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": "+8612154154",
        "isMobile": "N",
        "phonePref": "O",
        "email": "Jon@gmail.com",
        "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](https://www.google.com/search?q=%23transaction-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**

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

