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

Test Enviroment:

POST https://uat.paywizard.biz/ovstrade/semiOpen/v3/registerTerminal

Production Enviroment:

POST 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

---

Request Body

Name	Type	Mandatory	Description
clientId	string		Developer ID provided by Paywizard
merchantId	String		Merchant ID
posId	String		Point of Sale ID
terminalId	String		Payment Terminal ID (Payment Processor TID)
terminalSn	String		Payment Terminal S/N (Device S/N)

merchantId (Merchant ID)

• What it is: A unique identifier for your business account.

• Who provides it: The Payment Processor.

• In the Sandbox: 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.

• In the Sandbox: 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

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

Response Body

Name	Type	Mandatory	Description
code	int		Response Code (200 Success, Non-200 Failed)
msg	String		Response Message
timestamp	String		Date/Time(UTC)

Response Sample

200

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