# VOID

## Overview

This endpoint is used to reverse (or void) a transaction. A reversal is typically used to cancel a transaction on the same day it was made, before the funds have settled.

{% hint style="warning" %}
Note: Partial reversals are not supported by all payment channels.
{% endhint %}

## Environments

<table><thead><tr><th width="127.79998779296875">Environment</th><th width="103.60003662109375">Protocol</th><th width="82">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/openPay/reversalOrder</code></td></tr><tr><td>Production</td><td>HTTPS</td><td><code>POST</code></td><td><code>https://portal.paywizard.biz/ovstrade/openPay/reversalOrder</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](https://oversea.hs1c.cn/showdoc/web/#/671575440/155776446). |

## **Request Body Parameters**

To identify the transaction to be reversed, you must provide either the `oriCheckoutId` or the `oriTransIndexCode`.

| Parameter           | Type   | Required               | Description                                                                          |
| ------------------- | ------ | ---------------------- | ------------------------------------------------------------------------------------ |
| `clientId`          | String | Yes                    | Your unique developer ID.                                                            |
| `transIndexCode`    | String | Yes                    | A new, unique order ID for this specific reversal request, generated by your system. |
| `oriCheckoutId`     | String | Conditionally Required | The original `checkoutId` of the transaction you want to reverse.                    |
| `oriTransIndexCode` | String | Conditionally Required | The original `transIndexCode` of the transaction you want to reverse.                |
| `amount`            | String | Yes                    | The amount to be reversed. Example: `"1.50"`.                                        |
| `notifyUrl`         | String | No                     | The callback URL where you will receive the final reversal result notification.      |

{% hint style="warning" %}
*Note: You must provide at least one of the original identifiers (`oriCheckoutId` or `oriTransIndexCode`). If both are sent, `oriCheckoutId` will take precedence.*
{% endhint %}

## **Request Example**

```json
{
    "clientId": "825429536610058240",
    "transIndexCode": "202506091432000000013",
    "oriCheckoutId": "917121926164512768",
    "amount": "0.01"
}
```

***

## **Response Body**

The response object contains the immediate status of the reversal request.

| Parameter                | Type    | Description                                                                                                                                           |
| ------------------------ | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| `code`                   | Integer | The HTTP status code. `200` indicates a successful request. Any other value indicates an error.                                                       |
| `msg`                    | String  | A human-readable message describing the result. "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 reversal, generated by the payment platform.                                                                  |
| `data.transIndexCode`    | String  | The unique reversal order ID that you provided in the request.                                                                                        |
| `data.result`            | Integer | An integer code representing the status of the reversal. See [Reversal Status Codes](https://www.google.com/search?q=%23reversal-status-codes) below. |
| `data.amount`            | String  | The reversed amount.                                                                                                                                  |
| `data.oriCheckoutId`     | String  | The `checkoutId` of the original transaction that was reversed.                                                                                       |
| `data.oriTransIndexCode` | String  | The `transIndexCode` of the original transaction that was reversed.                                                                                   |

## **Reversal Status Codes**

The `result` field indicates the immediate outcome of the reversal request. The final status may be delivered via the `notifyUrl`.

<table><thead><tr><th width="142">Result Code</th><th>Description</th></tr></thead><tbody><tr><td><code>0</code></td><td>Success</td></tr><tr><td><code>1</code></td><td>Failure</td></tr><tr><td><code>2</code></td><td>Pending / In Progress</td></tr></tbody></table>

## **Success Response Example**

```json
{
    "code": 200,
    "msg": "success",
    "timestamp": "2025-06-09 15:32:00",
    "data": {
        "mid": "007889-3-006",
        "paywizardId": "10280000002",
        "checkoutId": "917122074735149056",
        "transIndexCode": "202506091432000000014",
        "amount": "0.01",
        "result": 0,
        "oriCheckoutId": "917121926164512768",
        "oriTransIndexCode": "202506091432000000012"
    }
}
```
