> For the complete documentation index, see [llms.txt](https://smartpossdk.gitbook.io/paywizard-open-api/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://smartpossdk.gitbook.io/paywizard-open-api/cloud-api/pos-and-payment-terminal-binding-process/api-bind-pos-and-payment-terminal.md).

# API: Bind POS & Payment Terminal

### Through this API interface, you will be able to register your own POS to the platform and simultaneously bind the payment terminal

## Register POS and Bind POS with Payment Terminal

<mark style="background-color:blue;">**Test Enviroment:**</mark>

<mark style="color:green;">`POST`</mark> [https://uat.paywizard.biz/ovstrade/semiOpen/v3/registerTerminal](https://oversea.paywizard.biz/ovstrade/semiOpen/v3/registerTerminal)

<mark style="background-color:green;">**Production Enviroment:**</mark>

<mark style="color:green;">`POST`</mark> <https://portal.paywizard.biz/ovstrade/semiOpen/v3/registerTerminal>

**Headers**

| Name         | Value                                                                                                                             |
| ------------ | --------------------------------------------------------------------------------------------------------------------------------- |
| Content-Type | `application/json`                                                                                                                |
| jwt-token    | Merchant Token provided by Paywizard                                                                                              |
| sign         | [PayWizard Open Platform API Signature Guide V3](/paywizard-open-api/cloud-api/paywizard-open-platform-api-signature-guide-v3.md) |

***

**Request Body**

<table><thead><tr><th>Name</th><th>Type</th><th data-type="checkbox">Mandatory</th><th>Description</th></tr></thead><tbody><tr><td>clientId</td><td>string</td><td>true</td><td>Developer ID provided by Paywizard </td></tr><tr><td>merchantId</td><td>String</td><td>true</td><td><a href="#merchantid-merchant-id">Merchant ID</a></td></tr><tr><td>posId</td><td>String</td><td>true</td><td><a href="#posid-point-of-sale-id">Point of Sale ID</a></td></tr><tr><td>terminalId</td><td>String</td><td>true</td><td><p><a href="#terminalid-payment-terminal-id-tid">Payment Terminal ID</a></p><p><a href="#terminalid-payment-terminal-id-tid"><mark style="background-color:blue;">(Payment Processor TID)</mark></a></p></td></tr><tr><td>terminalSn</td><td>String</td><td>true</td><td><p>Payment Terminal S/N</p><p><mark style="background-color:blue;">(Device S/N)</mark></p></td></tr></tbody></table>

#### **`merchantId` (Merchant ID)**

* **What it is:** A unique identifier for your business account.
* **Who provides it:** The Payment Processor.
* <mark style="color:$danger;">**In the Sandbox:**</mark> For testing purposes, Paywizard will give you a specific test `merchantId`. This ensures that your test transactions are processed in the sandbox environment and not with real money.

#### **`terminalId` (Payment Terminal ID / TID)**

* **What it is:** A unique identifier for a specific payment terminal (the physical devices that reads the credit/debit card).
* **Who provides it:** Also provided and registered by the Payment Processor. A single merchant can have many terminals, and each one will have its own unique `terminalId`.
* <mark style="color:$danger;">**In the Sandbox:**</mark> Since you are not using a real, physical payment terminal during testing, you don't need a real, registered ID. That is why you can use any 8-digit number as a placeholder `terminalId`.

#### **`posId` (Point of Sale ID)**

* **What it is:** A unique identifier for the device that *initiates* the payment request. This is your internal ID.
* **Who provides it:** You (the developer or the business) create and manage this ID within your own software system. The Payment Processor does not know or provide this ID.
* **Purpose:** The `posId` identifies the specific point of sale in your system. This could be:
  * A cash register (e.g., `CASH_REGISTER_01`)
  * A self-service kiosk (e.g., `KIOSK_LOBBY_A`)
  * A PC running billing software (e.g., `FRONT_DESK_PC`)
  * Any other device that can start a transaction.
* **Why it must be unique in your system:** The most important role of the `posId` is to create a one-to-one pairing between your initiating device and a specific payment terminal (`terminalId`). When a cashier at "Checkout 3" (`posId` = `CHECKOUT_3`) presses the "Pay by Card" button, your system knows it must send the payment request to the specific payment terminal paired with that POS (e.g., `terminalId` = `87654321`).

**Request Sample**

```json
{
    "clientId": "client12345",
    "merchantId": "10800000003",
    "posId": "D31231234567890",
    "terminalId": "12345678",
    "terminalSn": "WP123987987897",
}
```

**Response Body**

<table><thead><tr><th>Name</th><th>Type</th><th data-type="checkbox">Mandatory</th><th>Description</th></tr></thead><tbody><tr><td>code</td><td>int</td><td>true</td><td><p>Response Code</p><p><code>(200 Success,</code></p><p><code>Non-200 Failed)</code></p></td></tr><tr><td>msg</td><td>String</td><td>true</td><td>Response Message</td></tr><tr><td>timestamp</td><td>String</td><td>true</td><td>Date/Time(UTC)</td></tr></tbody></table>

**Response Sample**

{% tabs %}
{% tab title="200" %}

```json
{
    "code": 200,
    "msg": "200",
    "timestamp": "2024-07-23 17:57:00"
}
```

{% endtab %}
{% endtabs %}