API: POS Initiate Transaction

Through this API interface, you will be able to initiate a transaction from your Point Of Sale system or web platform.

This API is for Point of Sale system

The payment terminal which receiving the transaction request is the one binded to the POSID which belongs to the merchant.

Initiate a Transaction

Test Enviroment:

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

Production Enviroment:

POST https://portal.paywizard.biz/ovstrade/semiOpen/v3/internetTrans

Headers

Name	Value
Content-Type	application/json
jwt-token	Merchant Token provided by Paywizard in merchant token email
sign	PayWizard Open Platform API Signature Guide V3

Request Body

Name	Type	Mandatory	Description
clientId	string		Developer ID
merchantId	String		Merchant ID
posId	String		POSID
tradeNo	String		Third-party POS systems order numbers, must be unique under the same ISO/ISV.
transType	String		See support transaction type
transScheme	String		{Credit,Debit,EBT,ECS} Default can be Credit if not sure
callerName	String		Merchant Name
transAmount	Long		This is the final total transaction amount. Mandatory if it is a financial transaction. The number of decimal places is determined by the CurrencyCode.
otherAmount	Long		Cash back amount
tipAmount	Long		Tip amount
currencyCode	String		Currency Code Mandatory if it is a financial transaction.
reqTransDate	String		Trans Date (YYYYMMDD)
reqTransTime	String		Trans Time(hhmmss)
oriTransIndexCode	String		Origin Transaction Index Code
oriTraceNum	String		Origin Transaction Trace Number
oriInvoiceNum	String		Origin Transaction Invoice Number
oriTransId	String		Origin Transaction ID
oriRrn	String		Origin Transaction Reference Number
enableReceipt	boolean		{false,true} Print receipt flag: false: do not print, true: print.
appendingReceiptInfo	String		Additional information to print on the receipt.
skipConfirmProcedure	boolean		{false,true} Skip confirmation step: false: do not skip. true: skip
callBackUrl	String		If the POS system is cloud-based, the transaction result can be obtained through this URL. Please see: Transaction result callback interface

Request Sample

Purchase

{
    "clientId": "825420368247390208",
    "merchantId": "10800000003",
    "posId": "testPos",
    "tradeNo": "202404231080000000908",
    "transType": "Purchase",
    "transScheme": "Credit",
    "callerName": "test merchant",
    "transAmount": 100,
    "otherAmount": 0,
    "tipAmount": 0,
    "currencyCode": "458",
    "reqTransDate": "20241219",
    "reqTransTime": "095200",
    "enableReceipt": false,
    "appendingReceiptInfo": "",
    "skipConfirmProcedure": false
}

Refund

Void/Reversal

PreAuth

IncrementalAuth

PartialReversal

AuthCompletion

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-08-12 14:45:54"
}

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.