# TSYS Transit Parameter Push

## Overview

This endpoint is used to upload and push TSYS Trasit payment configuration parameters to a specific terminal.

## Environments

| Environment | Protocol | HTTP Method | URL                                                                                |
| ----------- | -------- | ----------- | ---------------------------------------------------------------------------------- |
| Sandbox     | HTTPS    | `POST`      | `https://uat.paywizard.biz/ovstrade/openVarSheet/tsystrasit/configuration/push`    |
| Production  | HTTPS    | `POST`      | `https://portal.paywizard.biz/ovstrade/openVarSheet/tsystrasit/configuration/push` |

#### 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: Push TSYS Trasit Configuration

`POST /ovstrade/openVarSheet/tsystrasit/configuration/push`

## **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.                                                                                                                        |
| `pushData` | Object | Yes      | An object containing the configuration parameters to be pushed. See [PushData Object](https://www.google.com/search?q=%23pushdata-object) below. |

***

### **PushData Object**

| Parameter                  | Type   | Required | Description                                                                                                                                       |
| -------------------------- | ------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| `terminalSn`               | String | Yes      | The serial number of the target terminal.                                                                                                         |
| `terminalNumber`           | String | Yes      | The assigned terminal number.                                                                                                                     |
| `dbaName`                  | String | Yes      | The "Doing Business As" name for the merchant.                                                                                                    |
| `merchantAddress`          | Object | No       | The merchant's physical address. See [MerchantAddress Object](https://www.google.com/search?q=%23merchantaddress-object).                         |
| `legalPhone`               | String | No       | The legally registered phone number for the business.                                                                                             |
| `dbaPhone`                 | String | No       | The public-facing phone number for the business.                                                                                                  |
| `cardTypesAccepted`        | Object | No       | Object specifying accepted card types. See [CardTypesAccepted Object](https://www.google.com/search?q=%23cardtypesaccepted-object).               |
| `ebtFcsAndService`         | String | No       | EBT (Electronic Benefit Transfer) settings.                                                                                                       |
| `vitalMerchantId`          | String | No       | The Vital/TSYS merchant ID.                                                                                                                       |
| `location`                 | String | No       | The location identifier.                                                                                                                          |
| `application`              | String | No       | The application name.                                                                                                                             |
| `closeMethod`              | String | No       | The method for closing batches.                                                                                                                   |
| `authPrimaryPhone`         | String | No       | The primary phone number for authorization calls.                                                                                                 |
| `authSecondPhone`          | String | No       | The secondary phone number for authorization calls.                                                                                               |
| `settlePrimaryPhone`       | String | No       | The primary phone number for settlement calls.                                                                                                    |
| `settleSecondPhone`        | String | No       | The secondary phone number for settlement calls.                                                                                                  |
| `sicCode`                  | String | No       | The Standard Industrial Classification code.                                                                                                      |
| `agencyNumber`             | String | No       | The agency number.                                                                                                                                |
| `storeNumber`              | String | No       | The store number.                                                                                                                                 |
| `acquirerId`               | String | No       | The acquirer ID.                                                                                                                                  |
| `chainNumber`              | String | No       | The chain number.                                                                                                                                 |
| `countryCode`              | String | No       | The country code.                                                                                                                                 |
| `timeZoneInd`              | String | No       | The time zone indicator.                                                                                                                          |
| `authTid`                  | String | No       | The authorization Terminal ID.                                                                                                                    |
| `settlementTid`            | String | No       | The settlement Terminal ID.                                                                                                                       |
| `termLifecycleCode`        | String | No       | The terminal lifecycle code.                                                                                                                      |
| `semiIntegratedDownloadId` | Object | No       | Semi-integrated download parameters. See [SemiIntegratedDownloadId Object](https://www.google.com/search?q=%23semiintegrateddownloadid-object).   |
| `paymentAppParams`         | Object | No       | A comprehensive set of payment application parameters. See [PaymentAppParams Object](https://www.google.com/search?q=%23paymentappparams-object). |

#### **MerchantAddress Object**

| Parameter  | Type   | Required | Description             |
| ---------- | ------ | -------- | ----------------------- |
| `address1` | String | No       | Primary address line.   |
| `address2` | String | No       | Secondary address line. |
| `city`     | String | No       | The city.               |
| `state`    | String | No       | The state or province.  |
| `zipcode`  | String | No       | The postal code.        |

#### **CardTypesAccepted Object**

| Parameter                 | Type   | Required | Description                                           |
| ------------------------- | ------ | -------- | ----------------------------------------------------- |
| `americanExpress`         | String | No       | American Express configuration.                       |
| `discoverPayPalDinersJCB` | String | No       | Configuration for Discover, PayPal, Diners Club, JCB. |

#### **SemiIntegratedDownloadId Object**

| Parameter        | Type   | Required | Description                   |
| ---------------- | ------ | -------- | ----------------------------- |
| `downloadId`     | String | No       | The download ID.              |
| `gatewayAddress` | String | No       | The gateway URL.              |
| `ipAddress`      | String | No       | The IP address.               |
| `dns1`           | String | No       | Primary DNS server address.   |
| `subnetMask`     | String | No       | The subnet mask.              |
| `dns2`           | String | No       | Secondary DNS server address. |

#### **PaymentAppParams Object**

This object contains a large number of detailed settings for the payment application. All parameters within this object are optional.

*(For brevity, a partial list is shown here. Refer to the request example for the complete structure.)*

| Parameter              | Type   | Description                                                     |
| ---------------------- | ------ | --------------------------------------------------------------- |
| `adminPass`            | String | The administrator password.                                     |
| `merchantPass`         | String | The merchant password.                                          |
| `mid`                  | String | The Merchant ID.                                                |
| `deviceId`             | String | The Device ID (often the same as `terminalSn`).                 |
| `merchantCategoryCode` | String | The Merchant Category Code (MCC).                               |
| `countryCode`          | String | The country code (e.g., "840" for USA).                         |
| `currencyCode`         | String | The currency code (e.g., "840" for USD).                        |
| `autoSettle`           | String | Flag to enable/disable auto-settlement (e.g., "1" for enabled). |
| `businessCloseTime`    | String | The time when the business day closes for settlement.           |
| `enableTip`            | String | Flag to enable/disable tip functionality.                       |
| ...                    | ...    | ...                                                             |

***

## **Request Example**

*Note: The `paymentAppParams` object is extensive. This example shows the complete structure.*

```json
{
    "clientId": "client12345",
    "pushData": {
        "terminalSn": "V5377738",
        "merchantId": "5436845560417213",
        "terminalNumber": "0004",
        "dbaName": "Your company name here",
        "merchantAddress": {
            "address1": "Your address here",
            "city": "CITY",
            "state": "MD",
            "zipcode": "20852"
        },
        "legalPhone": "(301) 123-4567",
        "dbaPhone": "(301) 123-4567",
        "cardTypesAccepted": {
            "americanExpress": "1052487246",
            "discoverPayPalDinersJCB": "601115011396817"
        },
        "ebtFcsAndService": "N",
        "vitalMerchantId": "556041721300",
        "location": "000001",
        "application": "MultiPass",
        "closeMethod": "NONE",
        "authPrimaryPhone": "123456789",
        "authSecondPhone": "123456789",
        "settlePrimaryPhone": "123456789",
        "settleSecondPhone": "123456789",
        "sicCode": "8999",
        "agencyNumber": "100740",
        "storeNumber": "0001",
        "acquirerId": "427539",
        "chainNumber": "000000",
        "countryCode": "840",
        "timeZoneInd": "705",
        "authTid": "D0.4275395436845560417213000001000489998402085270501",
        "settlementTid": "54368455604172130000010004",
        "termLifecycleCode": "",
        "semiIntegratedDownloadId": {
            "downloadId": "",
            "gatewayAddress": "https://gateway.transit-pass.com/servlets/",
            "ipAddress": "",
            "dns1": "",
            "subnetMask": "",
            "dns2": ""
        },
        "paymentAppParams": {
            "adminPass": "99999999",
            "merchantPass": "1234",
            "superPass": "123456",
            "refundPass": "5555",
            "reversalPass": "5555",
            "mid": "5436845560417213",
            "deviceId": "V5377738",
            "merchantCategoryCode": "8999",
            "countryCode": "840",
            "currencyCode": "",
            "unattended": "0",
            "userId": "",
            "userPassword": "",
            "developerId": "003546G001",
            "merchantName": "Your merchant name here",
            "merchantAddress1": "Your address here",
            "merchantCity": "CITY",
            "merchantState": "MD",
            "ebtFcsid": "N",
            "merchantPhone": "(301) 123-4567",
            "autoSettle": "1",
            "businessCloseTime": "NONE",
            "enableTip": "0",
            "primIp": "https://gateway.transit-pass.com/servlets/",
            "tmkIndex": "1",
            "traceNo": "1",
            "batchNumber": "1",
            "transExpiredDays": "30",
            "tacDenial": "0010000000",
            "tacOnline": "DE00FC9800",
            "tacDefault": "DC50FC9800",
            "contactlessLimit": "99999999",
            "contactlessCVM": "10000",
            "terminalCap": "A008C8",
            "supportMaestro": "1",
            "maxTrans": "500",
            "creditSale": "1",
            "debitSale": "1",
            "forceAuth": "1",
            "creditReturn": "1",
            "debitReturn": "1",
            "reversalMenu": "1",
            "printMenu": "1",
            "moreFunctionMenu": "1",
            "authOnly": "1",
            "authIncrement": "1",
            "tipAdjust": "1",
            "capture": "1",
            "closeBatch": "1"
        }
    }
}
```

***

## **Response Body**

The response acknowledges the request and provides the status of the configuration push.

| 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.pushId` | String  | A unique ID for this configuration push operation.                                                                                        |
| `data.status` | Integer | An integer code representing the status of the push. See [Push Status Codes](https://www.google.com/search?q=%23push-status-codes) below. |

### **Push Status Codes**

| Status Code | Description                                   |
| ----------- | --------------------------------------------- |
| `0`         | In Progress (Parameters are being pushed)     |
| `1`         | Success (Parameters were pushed successfully) |
| `2`         | Failure (Parameter push failed)               |

## **Success Response Example**

```json
{
    "code": 200,
    "msg": "success",
    "timestamp": "2024-08-12 14:45:54",
    "data": {
        "pushId": "768206988353077248",
        "status": 0
    }
}
```
