# Table of Contents
- [CloudPOS SDK](#cloudpos-sdk)
- [Welcome to Catering & Retail Solution User Guide | WizarPOS Catering & Retail Soloution User Guide](#welcome-to-catering-retail-solution-user-guide-wizarpos-catering-retail-soloution-user-guide)
- [Payments | WizarPOS Catering & Retail Soloution User Guide](#payments-wizarpos-catering-retail-soloution-user-guide)
- [Smart Retail | WizarPOS Catering & Retail Soloution User Guide](#smart-retail-wizarpos-catering-retail-soloution-user-guide)
- [Intro | WizarPOS Catering & Retail Soloution User Guide](#intro-wizarpos-catering-retail-soloution-user-guide)
- [Smart Catering | WizarPOS Catering & Retail Soloution User Guide](#smart-catering-wizarpos-catering-retail-soloution-user-guide)
- [Loyalty | WizarPOS Catering & Retail Soloution User Guide](#loyalty-wizarpos-catering-retail-soloution-user-guide)
- [Smart Catering | WizarPOS Catering & Retail Soloution User Guide](#smart-catering-wizarpos-catering-retail-soloution-user-guide)
- [Intergrations | WizarPOS Catering & Retail Soloution User Guide](#intergrations-wizarpos-catering-retail-soloution-user-guide)
- [Catering Online Store User Guide | WizarPOS Catering & Retail Soloution User Guide](#catering-online-store-user-guide-wizarpos-catering-retail-soloution-user-guide)
- [Catering Terminal APP User Guide | WizarPOS Catering & Retail Soloution User Guide](#catering-terminal-app-user-guide-wizarpos-catering-retail-soloution-user-guide)
- [Smart Retail | WizarPOS Catering & Retail Soloution User Guide](#smart-retail-wizarpos-catering-retail-soloution-user-guide)
- [Management | WizarPOS Catering & Retail Soloution User Guide](#management-wizarpos-catering-retail-soloution-user-guide)
- [Retail Online Store User Guide | WizarPOS Catering & Retail Soloution User Guide](#retail-online-store-user-guide-wizarpos-catering-retail-soloution-user-guide)
- [Retail Terminal APP User Guide | WizarPOS Catering & Retail Soloution User Guide](#retail-terminal-app-user-guide-wizarpos-catering-retail-soloution-user-guide)
- [Catering Smart ECR User Guide | WizarPOS Catering & Retail Soloution User Guide](#catering-smart-ecr-user-guide-wizarpos-catering-retail-soloution-user-guide)
- [POS_Specs | CloudPOS SDK](#pos-specs-cloudpos-sdk)
- [Permissions | CloudPOS SDK](#permissions-cloudpos-sdk)
- [EMV Develop Spec | CloudPOS SDK](#emv-develop-spec-cloudpos-sdk)
- [Java API Samples | CloudPOS SDK](#java-api-samples-cloudpos-sdk)
- [Scanning Service Usage | CloudPOS SDK](#scanning-service-usage-cloudpos-sdk)
- [Retail Smart ECR User Guide | WizarPOS Catering & Retail Soloution User Guide](#retail-smart-ecr-user-guide-wizarpos-catering-retail-soloution-user-guide)
- [Manual for Maintenance Management Portal | WizarPOS Catering & Retail Soloution User Guide](#manual-for-maintenance-management-portal-wizarpos-catering-retail-soloution-user-guide)
- [Manual for Catering Portal | WizarPOS Catering & Retail Soloution User Guide](#manual-for-catering-portal-wizarpos-catering-retail-soloution-user-guide)
- [MDB Communication Protocal | CloudPOS SDK](#mdb-communication-protocal-cloudpos-sdk)
- [CloudPOS SDK AAR | CloudPOS SDK](#cloudpos-sdk-aar-cloudpos-sdk)
- [Contactless Card | CloudPOS SDK](#contactless-card-cloudpos-sdk)
- [SDK Error Collection | CloudPOS SDK](#sdk-error-collection-cloudpos-sdk)
- [IC Card | CloudPOS SDK](#ic-card-cloudpos-sdk)
- [PINPAD | CloudPOS SDK](#pinpad-cloudpos-sdk)
- [MSR Card | CloudPOS SDK](#msr-card-cloudpos-sdk)
- [Hardware/Repair | CloudPOS SDK](#hardware-repair-cloudpos-sdk)
- [Choose Your Best Practice | Paywizard Integration](#choose-your-best-practice-paywizard-integration)
- [Integration & Go-Live Guide | Paywizard Integration](#integration-go-live-guide-paywizard-integration)
- [PayWizard Open Platform API Signature Guide V3 | Paywizard Integration](#paywizard-open-platform-api-signature-guide-v3-paywizard-integration)
- [Integration Best Practices | Paywizard Integration](#integration-best-practices-paywizard-integration)
- [Quick Start - Cloud API | Paywizard Integration](#quick-start-cloud-api-paywizard-integration)
- [Overview | Paywizard Integration](#overview-paywizard-integration)
- [POS & Payment Terminal Binding Process | Paywizard Integration](#pos-payment-terminal-binding-process-paywizard-integration)
- [Do Transactions | Paywizard Integration](#do-transactions-paywizard-integration)
- [Close Order | Paywizard Integration](#close-order-paywizard-integration)
- [Quick Start: QR Payment API Integration | Paywizard Integration](#quick-start-qr-payment-api-integration-paywizard-integration)
- [Quick Start - Payment Parameter Push | Paywizard Integration](#quick-start-payment-parameter-push-paywizard-integration)
- [Local Integration | Paywizard Integration](#local-integration-paywizard-integration)
- [Get Transaction Result | Paywizard Integration](#get-transaction-result-paywizard-integration)
- [E-Receipt Intro | Paywizard Integration](#e-receipt-intro-paywizard-integration)
- [Query Push Status | Paywizard Integration](#query-push-status-paywizard-integration)
- [Fiserv Parameter Push | Paywizard Integration](#fiserv-parameter-push-paywizard-integration)
- [Internal Integration | Paywizard Integration](#internal-integration-paywizard-integration)
- [Quick Start - Semi Integration | Paywizard Integration](#quick-start-semi-integration-paywizard-integration)
- [Quick Start - Online Payment | Paywizard Integration](#quick-start-online-payment-paywizard-integration)
- [Web Element Integration | Paywizard Integration](#web-element-integration-paywizard-integration)
- [Query Transaction Status | Paywizard Integration](#query-transaction-status-paywizard-integration)
- [Quick Pay - Merchant Scan | Paywizard Integration](#quick-pay-merchant-scan-paywizard-integration)
- [Generate QR Code - Customer Scan | Paywizard Integration](#generate-qr-code-customer-scan-paywizard-integration)
- [TSYS Transit Parameter Push | Paywizard Integration](#tsys-transit-parameter-push-paywizard-integration)
- [VOID | Paywizard Integration](#void-paywizard-integration)
- [Redeem Points | Paywizard Integration](#redeem-points-paywizard-integration)
- [Add Tip | Paywizard Integration](#add-tip-paywizard-integration)
- [Void | Paywizard Integration](#void-paywizard-integration)
- [Refund | Paywizard Integration](#refund-paywizard-integration)
- [Query | Paywizard Integration](#query-paywizard-integration)
- [Quick Start - Loyalty API | Paywizard Integration](#quick-start-loyalty-api-paywizard-integration)
- [Activate | Paywizard Integration](#activate-paywizard-integration)
- [Top-up | Paywizard Integration](#top-up-paywizard-integration)
- [Issue Points | Paywizard Integration](#issue-points-paywizard-integration)
- [Pay | Paywizard Integration](#pay-paywizard-integration)
- [Payment App Integration Protocol | Paywizard Integration](#payment-app-integration-protocol-paywizard-integration)
- [Payment App AIDL Integration Protocol | Paywizard Integration](#payment-app-aidl-integration-protocol-paywizard-integration)
- [Client SDK API | Paywizard Integration](#client-sdk-api-paywizard-integration)
- [Get Access Tokens | Paywizard Integration](#get-access-tokens-paywizard-integration)
- [API: POS Initiate Transaction | Paywizard Integration](#api-pos-initiate-transaction-paywizard-integration)
- [API: Get POS & Terminal Binding List | Paywizard Integration](#api-get-pos-terminal-binding-list-paywizard-integration)
- [Transaction Type | Paywizard Integration](#transaction-type-paywizard-integration)
- [API: Unbind Terminal with POS | Paywizard Integration](#api-unbind-terminal-with-pos-paywizard-integration)
- [Terminal API: Subscribe Transaction Results | Paywizard Integration](#terminal-api-subscribe-transaction-results-paywizard-integration)
- [API: Bind POS & Payment Terminal | Paywizard Integration](#api-bind-pos-payment-terminal-paywizard-integration)
- [Serial Connection Best Practice | Paywizard Integration](#serial-connection-best-practice-paywizard-integration)
- [API: Get Transaction Result | Paywizard Integration](#api-get-transaction-result-paywizard-integration)
- [API: Get Merchant Transaction | Paywizard Integration](#api-get-merchant-transaction-paywizard-integration)
- [Socket Connection Best Practice | Paywizard Integration](#socket-connection-best-practice-paywizard-integration)
- [Webhook: Push Transaction Result | Paywizard Integration](#webhook-push-transaction-result-paywizard-integration)
- [MDB Connection Best Practice | Paywizard Integration](#mdb-connection-best-practice-paywizard-integration)
- [API: Get Merchant Infomation | Paywizard Integration](#api-get-merchant-infomation-paywizard-integration)
- [APM (QR/WALLET) API | Paywizard Integration](#apm-qr-wallet-api-paywizard-integration)
- [Webhook: Push Settlement Information | Paywizard Integration](#webhook-push-settlement-information-paywizard-integration)
- [Terminal API : Upload Settlement Info | Paywizard Integration](#terminal-api-upload-settlement-info-paywizard-integration)
- [AIDL Integration Best Practice | Paywizard Integration](#aidl-integration-best-practice-paywizard-integration)
- [Terminal API : Upload Transaction Info | Paywizard Integration](#terminal-api-upload-transaction-info-paywizard-integration)
- [LOYALTY API | Paywizard Integration](#loyalty-api-paywizard-integration)
- [Transaction Request Example | Paywizard Integration](#transaction-request-example-paywizard-integration)
---
# CloudPOS SDK
This comprehensive documentation aims to guide Android application developers for the Smart POS. It covers EMV payment specifications, barcode scanning, the Device Java API, API details, samples, a quick start guide, and additional resources.
For more details, please refer to the provided links and sections.
###
[hashtag](https://smartpossdk.gitbook.io/cloudpossdk#emv-payment)
EMV Payment
The EMV Payment SDK is designed to facilitate the development of payment applications (APPs).
* [EMV Develop Spec](https://smartpossdk.gitbook.io/cloudpossdk/cloudpos-sdk/emv-develop-spec)
###
[hashtag](https://smartpossdk.gitbook.io/cloudpossdk#barcode-scanning)
Barcode Scanning
* [Scanning Service Usage](https://smartpossdk.gitbook.io/cloudpossdk/cloudpos-sdk/scanning-service-usage)
###
[hashtag](https://smartpossdk.gitbook.io/cloudpossdk#device-java-api)
Device Java API
The Device Java API simplifies development by being packaged as an AAR library file, providing Android developers with easy integration. This API includes functionalities such as Printer, PINPad, MSR, SmartCard, RFCard, SerialPort, LED, Fingerprint, and HSM.
* [API Specificationsarrow-up-right](http://sdkwiki.wizarpos.com/wizarposapi/)
* [API Specifications Downloadarrow-up-right](https://ftp.wizarpos.com/device/java/javadoc_20250527.zip)
* [CloudPOS SDK AAR](https://smartpossdk.gitbook.io/cloudpossdk/cloudpos-sdk/cloudpos-sdk-aar)
* [Samples](https://smartpossdk.gitbook.io/cloudpossdk/cloudpos-sdk/java-api-samples)
* [Permissions Definition](https://smartpossdk.gitbook.io/cloudpossdk/cloudpos-sdk/permissions)
* [Error Code](https://smartpossdk.gitbook.io/cloudpossdk/cloudpos-sdk/error-code)
* [Printer Technical Manualarrow-up-right](http://ftp.wizarpos.com/device/CloudPOSPrinter_TechnicalManual_20231222_en.pdf)
###
[hashtag](https://smartpossdk.gitbook.io/cloudpossdk#mdb-interface)
MDB Interface
* [MDB Communication Protocal](https://smartpossdk.gitbook.io/cloudpossdk/cloudpos-sdk/mdb-communication-protocal)
###
[hashtag](https://smartpossdk.gitbook.io/cloudpossdk#quick-start-guide)
Quick Start Guide
* [USB Driver Download](https://smartpossdk.gitbook.io/cloudpossdk/faq/usb-serial-port/install-terminal-usb-drivers)
* [Install App](https://smartpossdk.gitbook.io/cloudpossdk/faq/other-development/install-pos-applications)
* [Apply App Certificate](https://smartpossdk.gitbook.io/cloudpossdk/faq/certificate/apply-app-certificates)
* [Sign App](https://smartpossdk.gitbook.io/cloudpossdk/faq/other-development/app-signing-process)
* [Apply TMS Account](https://smartpossdk.gitbook.io/cloudpossdk/faq/tms-wizarview/apply-wizarview-account)
* [TMS Manualarrow-up-right](https://ftp.wizarpos.com/device/TMSManual.pdf)
[NextEMV Develop Specchevron-right](https://smartpossdk.gitbook.io/cloudpossdk/cloudpos-sdk/emv-develop-spec)
Last updated 3 days ago
* [EMV Payment](https://smartpossdk.gitbook.io/cloudpossdk#emv-payment)
* [Barcode Scanning](https://smartpossdk.gitbook.io/cloudpossdk#barcode-scanning)
* [Device Java API](https://smartpossdk.gitbook.io/cloudpossdk#device-java-api)
* [MDB Interface](https://smartpossdk.gitbook.io/cloudpossdk#mdb-interface)
* [Quick Start Guide](https://smartpossdk.gitbook.io/cloudpossdk#quick-start-guide)
---
# Welcome to Catering & Retail Solution User Guide | WizarPOS Catering & Retail Soloution User Guide
[hashtag](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide#overview)
OVERVIEW
------------------------------------------------------------------------------------------------------------------
[✨Introchevron-right](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/overview/intro)
[🍕Smart Cateringchevron-right](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/overview/smart-catering)
[🏪Smart Retailchevron-right](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/overview/smart-retail)
[💳Paymentschevron-right](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/overview/payments)
[🫂Loyaltychevron-right](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/overview/loyalty)
[⚙️Intergrationschevron-right](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/overview/intergrations)
[hashtag](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide#user-guide)
USER GUIDE
----------------------------------------------------------------------------------------------------------------------
We've put together some helpful guides for you to get setup with our product quickly and easily.
[🍕Smart Cateringchevron-right](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/smart-catering)
[🏪Smart Retailchevron-right](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/smart-retail)
[NextIntrochevron-right](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/overview/intro)
Last updated 1 year ago
* [OVERVIEW](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide#overview)
* [USER GUIDE](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide#user-guide)
---
# Payments | WizarPOS Catering & Retail Soloution User Guide
[PreviousSmart Retailchevron-left](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/overview/smart-retail)
[NextLoyaltychevron-right](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/overview/loyalty)
Last updated 2 years ago
---
# Smart Retail | WizarPOS Catering & Retail Soloution User Guide
[PreviousSmart Cateringchevron-left](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/overview/smart-catering)
[NextPaymentschevron-right](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/overview/payments)
Last updated 2 years ago
---
# Intro | WizarPOS Catering & Retail Soloution User Guide
[PreviousWelcome to Catering & Retail Solution User Guidechevron-left](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide)
[NextSmart Cateringchevron-right](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/overview/smart-catering)
Last updated 2 years ago
---
# Smart Catering | WizarPOS Catering & Retail Soloution User Guide
[PreviousIntrochevron-left](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/overview/intro)
[NextSmart Retailchevron-right](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/overview/smart-retail)
Last updated 2 years ago
---
# Loyalty | WizarPOS Catering & Retail Soloution User Guide
[PreviousPaymentschevron-left](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/overview/payments)
[NextIntergrationschevron-right](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/overview/intergrations)
Last updated 2 years ago
---
# Smart Catering | WizarPOS Catering & Retail Soloution User Guide
[PreviousIntergrationschevron-left](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/overview/intergrations)
[NextCatering Online Store User Guidechevron-right](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/smart-catering/catering-online-store-user-guide)
Last updated 1 year ago
---
# Intergrations | WizarPOS Catering & Retail Soloution User Guide
[PreviousLoyaltychevron-left](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/overview/loyalty)
[NextSmart Cateringchevron-right](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/smart-catering)
Last updated 2 years ago
---
# Catering Online Store User Guide | WizarPOS Catering & Retail Soloution User Guide
[hashtag](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/smart-catering/catering-online-store-user-guide#toc14333)
1.Login
-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
After the customer scans the ordering QR code, he will be prompted to log in, and then enter the correct account number and password to log in. If there is no account then he has to register first.
07bfdc8416055f9512ab8efe5c842d6
f8cc39e7a4266e7a8a2b8bb75716679
You can enter your email address to create a new account, and you can reset your password if you forget it.
2b7f5c2a9b78fea70622e0005ce64ac
976f0aff6a8c142ea4648319b91fcf3
[hashtag](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/smart-catering/catering-online-store-user-guide#toc17206)
2.Home
------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
The home page shows customers the business name and address, as well as dine-in, take-out, dish recommendations, orders and recommended dishes.
5085a312fe1b1cc1f137e2190ee8f50
[hashtag](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/smart-catering/catering-online-store-user-guide#toc3235)
3.Dine in
--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
After scanning the table QR code enter the home page, click Dine in, you will enter the table and order food. There are various specifications of dishes to choose from depending on the restaurant.
ba163212cab967f4811f920c1167219
3cb62891bc2468f9b18d418d5218d8e
After ordering, you can view, modify and delete the number of dishes in the shopping cart and then you can check out.
24d9c45ba671cf11ac40a1cd31303ab
24c58452660919e22b7151d250ddab7
When check out, you can choose whether you want to pay by yourself or split the bill, you can choose the tip ratio, or you can customize the tip amount.
You can choose to pay by membership card or bank card.
a6dd3d23ff3b46722d6ea7743bd2bb6
6f6f29a910a0436f20a158ebd092dba
02c9be9d8d37e44a3a46baa091e47fb
[hashtag](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/smart-catering/catering-online-store-user-guide#toc30275)
4.Takeout
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
Click Takeaway, the same as dine-in process, the difference between takeaway and dine-in is that there is a packing fee, you can also choose the address, choose whether to pick up or deliver
cb30a02354bff5b95dd0382e71b9423
e8c2a3ab9479bde28e2979a4c5761d3
Choose delivery method or self-pickup
ac9a0ee6ab0a4cd2efd6e3fc85e8231
1ed4023ca6229202a6b8b5df96f5b8e
[hashtag](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/smart-catering/catering-online-store-user-guide#toc4635)
5.Recommand
----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
Click More on the home page to enter the list of recommended dishes. You can order food and add it to the shopping cart directly to place an order and checkout
7226c12abdf0f0eeb92a84bbda39d6c
69e44fd9cbf899f5a8e8fe7973dff38
[hashtag](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/smart-catering/catering-online-store-user-guide#toc24936)
6.Orders
--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
Click Orders to display all by type, unpaid, refunded, and completed 4 types of orders. Click an order to view the details.
490ee3691c852b767c5ca2d133bfbee
25237d84ec42b3317263beaeb33bc77
[hashtag](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/smart-catering/catering-online-store-user-guide#toc9850)
7.Mine
-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
Click Mine to display my page, which needs to be displayed after the user logs in.
After logging in, you can view member information, membership code, point mall, and modify your member information.
You can also view your membership balance, consumption records, recharge records
Points Mall, where you can choose the product you want to exchange by using points.
Click on Exchange Records, you can redeem the products with your own points, click on the exchanged QR code, go to the store and ask the waiter to scan the code to exchange products.
\\
[PreviousSmart Cateringchevron-left](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/smart-catering)
[NextCatering Terminal APP User Guidechevron-right](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/smart-catering/catering-terminal-app-user-guide)
Last updated 1 year ago
* [1.Login](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/smart-catering/catering-online-store-user-guide#toc14333)
* [2.Home](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/smart-catering/catering-online-store-user-guide#toc17206)
* [3.Dine in](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/smart-catering/catering-online-store-user-guide#toc3235)
* [4.Takeout](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/smart-catering/catering-online-store-user-guide#toc30275)
* [5.Recommand](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/smart-catering/catering-online-store-user-guide#toc4635)
* [6.Orders](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/smart-catering/catering-online-store-user-guide#toc24936)
* [7.Mine](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/smart-catering/catering-online-store-user-guide#toc9850)
---
# Catering Terminal APP User Guide | WizarPOS Catering & Retail Soloution User Guide
[hashtag](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/smart-catering/catering-terminal-app-user-guide#toc18639)
1\. Function overview
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
WizarPOS handheld ordering app is an ordering system for Android POS terminals. Waiters at catering merchants use handheld devices to provide ordering services to customers. The main functions provided by the system are as follows:
###
[hashtag](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/smart-catering/catering-terminal-app-user-guide#menu)
**Menu**
The merchant uploads various types of dishes, hot dishes, cold dishes, Western food, dim sum, snacks, etc. And displays all the dishes in the menu. When ordering, the dishes can be customized according to the specifications, tastes, methods, and toppings.
###
[hashtag](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/smart-catering/catering-terminal-app-user-guide#promotions)
**Promotions**
Merchants can set up various types of marketing activities through the merchant portal, including discounts, full discounts, special offers, points malls, coupons for consumption and other activities, which can provide great dining experiences.
###
[hashtag](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/smart-catering/catering-terminal-app-user-guide#membership)
**Membership**
Each catering merchant can use the table QR code or takeout QR code to allow customers to scan the QR to register and become a member of the merchant. The waiter can use terminal to recharge for the members, and the member balance can be used when order and pay. Members can get coupons through consumption.
###
[hashtag](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/smart-catering/catering-terminal-app-user-guide#payment)
**Payment**
Handheld ordering can support cash, bank cards, membership payment, membership coupons and other payment methods.
###
[hashtag](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/smart-catering/catering-terminal-app-user-guide#points)
**Points**
Merchants can configure goods for exchange in the merchant portal, such as 100 points to exchange for a bottle of Coke, 500 points to exchange for a dish. The waiter uses a terminal to scan the customer's redemption code and redeem the goods for the customer.
[hashtag](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/smart-catering/catering-terminal-app-user-guide#toc11376)
2\. Login
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
If you want to log in to the terminal, you need to enter the merchant ID, username and password.
The merchant ID is when the service provider onboarding the merchant. An assigned merchant ID can be obtained from the email after the merchant is successfully onboarded. At the same time, the merchant administrator account and initial password will be given. The merchant administrator must log in to the merchant backend for the first time, change the initial password, and create an operator account in System Settings -> Account Management. The created operator account can be used to log in to the terminal catering application.
circle-info
**Note:** **The administrator account of the merchant received by email cannot be used to log in to the terminal application.**
1dc914aa645d6c4157ad7768a7923bc
[hashtag](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/smart-catering/catering-terminal-app-user-guide#toc14554)
3\. Home
--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
The merchant’s name, merchant number, merchant logo and settings are displayed at the top of the homepage.
**Function list:**
1. **Dine-In**: In store order.
2. **Takeout**: Takeout food
3. **Bill**: Business report
4. **Report**: Daily summary
5. **Sales Order**: Sales order list
6. **Today Sum**: Dish statistics
7. **Print**: Receipt printing
8. **Tips**: Tips report
9. **Member**: Membership manager
10. **Points**: Points redeem
11. **Reservation**: Wait for a table
12. **Takeout Man**: Takeout order management
13. **Notification**: Message notification
[hashtag](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/smart-catering/catering-terminal-app-user-guide#toc4239)
4\. Dine-in
----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
Merchants click on Dine-in to the table selection page.
###
[hashtag](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/smart-catering/catering-terminal-app-user-guide#step-1-choose-table)
Step 1: Choose Table
The table displays the table name, maximum customer of the table allowed and status. The table status is divided into idle and occupied. (Table can be managed at the merchant portal.) Select the table which customer is sitting at to enter the menu.
###
[hashtag](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/smart-catering/catering-terminal-app-user-guide#step-2-order)
Step 2: Order
At the menu, you can select dishes according to their types. For the dishes, you can select specifications, flavors, toppings, and cooking methods.
Select the dishes and dish specifications and add them to the cart. You can review the selected dishes in the cart. The dishes in the cart can be added or deleted.
###
[hashtag](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/smart-catering/catering-terminal-app-user-guide#step-3-confirm-order)
Step 3: Confirm Order
Click the Order button to jump to the order confirmation page. If customer has special needs then fill in the remark, choose whether to package, and check the total amount of the order. After confirmation, click confirm order. The order is successfully placed and terminal will print the receipt. The table is occupied at this time.
7b55a2d39c107240cf8f7b624eb8b63
###
[hashtag](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/smart-catering/catering-terminal-app-user-guide#step-4-payment)
Step 4: Payment
Click on the dining table to jump to the order details. On this page, waiters can add dishes Order More or modify order Modify.
Click Checkout to jump to the payment page. The cashier displays the payment amount, taxes, discount information and the total order amount. Customer can choose to split the payment (multiple payments), and the customer can also select the tip ratio or directly enters the tip amount.
circle-info
**Note: Click Split to split orders, up to 10p. Click Tip Ratio to choose the rate. The default is 10%, 15%, and 20%. It can also be customized in the system settings.**
Payment methods include cash, bank card, membership payment or other payment. Among them, member payments need to identify membership QR code first. Click on the upper right member icon to identify members.
circle-info
**Note: After identifying the member, if the customer has coupons then click on the coupon to select the member's coupon for discount.**
You can also use other payment methods customized by the merchant to record other types of transactions.
After the payment is successful, the terminal prints the receipt. Click View Orders to view the orders, and click Back To Home to return to the HOME.
[hashtag](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/smart-catering/catering-terminal-app-user-guide#toc25220)
5\. Takeout
-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
Click Takeout on the homepage to enter the takeout ordering process. Takeout scenario is the same as dine-in. The difference is that when placing an order, the Takeout switch will be turned on by default, and the packaging fee will be calculated for the order automatically.
[hashtag](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/smart-catering/catering-terminal-app-user-guide#toc12691)
6\. Bills
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
Click on the Bill to enter the order list. All dine-in and mobile orders are displayed here.
Click on the order to view the order details, including amount, payment time, payment method, discount information, etc.
[hashtag](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/smart-catering/catering-terminal-app-user-guide#toc17679)
7\. Business Report
-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
Click Report on the home page to enter the report page. The sales report displays all income, discounts, refunds, etc. based on date. Click Print icon in the upper right corner to print out the report receipt.
[hashtag](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/smart-catering/catering-terminal-app-user-guide#toc23121)
8\. Sales Orders
----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
Click Sales Order to display the sales order list, which can include all mobile and dine-in orders.
Click on the order details to print and refund the order. When refund, you need to enter the manager password. The manager password is set in the merchant's portal.
Entering the password to perform the refund operation, a refund receipt will be printed.
[hashtag](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/smart-catering/catering-terminal-app-user-guide#toc30298)
9\. Summary of the day
----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
Click Today Sum to enter the day's summary, view the dishes sold on the day, and print the day's summary of the dishes.
[hashtag](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/smart-catering/catering-terminal-app-user-guide#toc28164)
10\. Print
----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
Click Print on the home page to enter the network printing list. The page displays the receipts printed successfully and failed by the network printer (for kitchen use). If the receipt fails to print, it will be displayed in the Not Printed column, and the merchant clicks Reprint to reprint. Click the icon in the upper right corner to view the configuration of the current merchant's network printers. If you want to configure a network printer, you can configure it in the merchant's portal. The terminal can only enable and disable network printers.
[hashtag](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/smart-catering/catering-terminal-app-user-guide#toc17955)
11\. Tip Report
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
Click Tips to enter tip report. You can check the tip amount and number of orders based on employees and time.
[hashtag](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/smart-catering/catering-terminal-app-user-guide#toc22811)
12\. Membership
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
Click Member to enter the member management. You can enter the member ID or scan the member QR ID. After identifying the member, his balance, points and coupons will be showed. You can recharge for the customer, and you can also view recharge details and transaction details.
Click on Member Details - > Rechange enters the recharge page. The payment method supports cash and bank card. After the payment is successful, the balance will be credited immediately. Member accounts can also view points and coupons.
[hashtag](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/smart-catering/catering-terminal-app-user-guide#toc1061)
13\. Points
----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
Click on Member Details - > Point, enter the points redemption function, and the items currently redeemed and to be redeemed will be displayed. The waiter can use the scan function in the upper right corner to scan the customer's points redemption QR code to redeem items.
[hashtag](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/smart-catering/catering-terminal-app-user-guide#toc30049)
14\. Takeout Management
-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
Click Takeout Man on the homepage to enter the takeout list. The takeout page displays two lists: Taken and Untaken.
Click Untaken on the unpicked meal list, click on the order, and click on Confirm Pickup to pick up the meal. After clicking, the status of the order changes to (Finished).
[hashtag](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/smart-catering/catering-terminal-app-user-guide#toc12302)
15\. Settings
-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
Click the settings icon in the upper right corner of the homepage to enter the system settings page, which will display relevant information such as the current merchant number and merchant name. You can turn on or off the message notification function as needed, and choose whether to automatically receive orders. By default, these two functions are turned off. When turned off, you need to manually receive orders and print operations. When turned on, the terminal will automatically print new orders. Merchants can also set different tip ratios according to needs.
[hashtag](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/smart-catering/catering-terminal-app-user-guide#toc25752)
16\. Notifications
------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
There is a notification area at the bottom of the homepage, which can receive order notifications from customers who order online. The green icon represents a dine-in order. If a customer places an order but does not pay yet, they will receive a corresponding order notification and the waiter can click to place the order and print it. The yellow icon represents a takeout order. After the customer places the order and completes the payment, the order notification will be received in the message notification bar, and the waiter can click to take the order and print it. If the kitchen network printer has been configured , the kitchen receipt will be automatically printed .
Click Notification - More to view more messages. Click to enter the order details page, where you can accept or reject the order. After placing the order, receipt will be printed. If the order is rejected, a refund will be processed.
[hashtag](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/smart-catering/catering-terminal-app-user-guide#toc10812)
17\. Reservation
----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
Click Reservation on the home page to enter the queuing page. On the page, you can check the queuing status of the table, such as the number of people at the table, waiting time, etc. The waiter can click on the three icons in the list to perform voice announcements, customer dining and queuing invalidation. Click the icon in the upper right corner to view expired historical queue information.
Click the Reservation - Reserve button, select the table, and the terminal will print a receipt to the customer. Customers can use their mobile phone browser to scan the QR code on the receipt to check the queue information in real time to prevent overdue.
After scanning the QR code, customer can check the current dining queue status on your mobile browser.
[PreviousCatering Online Store User Guidechevron-left](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/smart-catering/catering-online-store-user-guide)
[NextCatering Smart ECR User Guidechevron-right](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/smart-catering/catering-smart-ecr-user-guide)
Last updated 2 years ago
* [1\. Function overview](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/smart-catering/catering-terminal-app-user-guide#toc18639)
* [Menu](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/smart-catering/catering-terminal-app-user-guide#menu)
* [Promotions](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/smart-catering/catering-terminal-app-user-guide#promotions)
* [Membership](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/smart-catering/catering-terminal-app-user-guide#membership)
* [Payment](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/smart-catering/catering-terminal-app-user-guide#payment)
* [Points](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/smart-catering/catering-terminal-app-user-guide#points)
* [2\. Login](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/smart-catering/catering-terminal-app-user-guide#toc11376)
* [3\. Home](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/smart-catering/catering-terminal-app-user-guide#toc14554)
* [4\. Dine-in](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/smart-catering/catering-terminal-app-user-guide#toc4239)
* [Step 1: Choose Table](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/smart-catering/catering-terminal-app-user-guide#step-1-choose-table)
* [Step 2: Order](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/smart-catering/catering-terminal-app-user-guide#step-2-order)
* [Step 3: Confirm Order](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/smart-catering/catering-terminal-app-user-guide#step-3-confirm-order)
* [Step 4: Payment](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/smart-catering/catering-terminal-app-user-guide#step-4-payment)
* [5\. Takeout](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/smart-catering/catering-terminal-app-user-guide#toc25220)
* [6\. Bills](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/smart-catering/catering-terminal-app-user-guide#toc12691)
* [7\. Business Report](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/smart-catering/catering-terminal-app-user-guide#toc17679)
* [8\. Sales Orders](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/smart-catering/catering-terminal-app-user-guide#toc23121)
* [9\. Summary of the day](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/smart-catering/catering-terminal-app-user-guide#toc30298)
* [10\. Print](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/smart-catering/catering-terminal-app-user-guide#toc28164)
* [11\. Tip Report](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/smart-catering/catering-terminal-app-user-guide#toc17955)
* [12\. Membership](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/smart-catering/catering-terminal-app-user-guide#toc22811)
* [13\. Points](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/smart-catering/catering-terminal-app-user-guide#toc1061)
* [14\. Takeout Management](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/smart-catering/catering-terminal-app-user-guide#toc30049)
* [15\. Settings](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/smart-catering/catering-terminal-app-user-guide#toc12302)
* [16\. Notifications](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/smart-catering/catering-terminal-app-user-guide#toc25752)
* [17\. Reservation](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/smart-catering/catering-terminal-app-user-guide#toc10812)
---
# Smart Retail | WizarPOS Catering & Retail Soloution User Guide
[PreviousCatering Smart ECR User Guidechevron-left](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/smart-catering/catering-smart-ecr-user-guide)
[NextRetail Terminal APP User Guidechevron-right](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/smart-retail/retail-terminal-app-user-guide)
Last updated 2 years ago
---
# Management | WizarPOS Catering & Retail Soloution User Guide
[Manual for Maintenance Management Portalchevron-right](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/management/manual-for-maintenance-management-portal)
[Manual for Catering Portalchevron-right](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/management/manual-for-catering-portal)
[PreviousRetail Smart ECR User Guidechevron-left](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/smart-retail/retail-smart-ecr-user-guide)
[NextManual for Maintenance Management Portalchevron-right](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/management/manual-for-maintenance-management-portal)
Last updated 1 year ago
---
# Retail Online Store User Guide | WizarPOS Catering & Retail Soloution User Guide
[hashtag](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/smart-retail/retail-online-store-user-guide#toc18639)
1\. Function Overview
-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
WizarPOS retail online store is a mall system based on HTML5. Customer use mobile phone scan function to scan the online store QR code of the retail merchant to enter the mall for shopping or direct click the store URL. The system provides the following functions:
**1\. Goods**
Merchants upload various types of products in the merchant portal and display all products in the product list. They can also select several of the products as hot-selling products and display them in the recommendation bar on the homepage.
**2\. Promotions**
Merchants can set up various types of marketing activities through the merchant portal, including discounts, full discounts , special offers , points malls, coupons for consumption and other activities, which can better provide users with better shopping experiences.
**3\. Membership**
Each retail merchant can recommend the merchant's online store to the customer through links or QR code. Customers scan the QR code to register and become a member of the merchant. The staff can use the terminal to recharge the balance. The member's balance can be used at checkout. Members can receive coupons for consumption, which can be deducted when making purchases.
**4\. Payment**
Retail online store membership card balance, bank cards, coupons and other payment methods.
**5\. Points Mall**
Merchants can configure points redemption activities in the merchant portal, such as 100 points redeeming a bottle of Coke, 200 points redeeming a pack of snacks, etc.
**6\. Chain stores**
If a merchant has multiple stores and supports the chain store function, you can switch to the store list on the mall page, view all stores under the merchant, and then enter one of the stores for shopping in the mall.
[hashtag](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/smart-retail/retail-online-store-user-guide#toc20911)
2\. Login
-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
Customer need to register as a member to log in for the first time.
Enter email address and password. After successful registration, you can log in with your registered email address and password.
fde40e6574e6d4f338ceb946a6d462f
974114854b38ddadcb70515d4c101ca
If you forget your password or want to reset it, you can click Forgot Password to reset your login password.
b01c6943aa43701169b259faabf43a4
0a57214ae7120619eea4c4e2e429c22
[hashtag](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/smart-retail/retail-online-store-user-guide#toc4116)
3\. Home
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
After successfully logging in, the product recommendation images and lists displayed on the homepage can be set in the merchant portal. You can quickly find the products you want through search. Click on the product list below to see all products. You can also click on Me to view personal information status.
f20b2347cd7a37425755277a2098bca
1675332857509
[hashtag](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/smart-retail/retail-online-store-user-guide#toc19015)
4\. Product Categories
------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
Click Menu to see all the product lists. You can also quickly find products through search, and you can also click on the sort order to arrange the products. For example, click on the price, and the products will be presented from low to high, or from high to low. The category supports up to level 2. Click on the product to view the product details. The taste, price and other parameters of the product can be set in the background.
ce639b2ff10fb1cd3c14efa1af3927b
1f5b6ed5ed03b8ff56226410a6660ff
[hashtag](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/smart-retail/retail-online-store-user-guide#toc31293)
5\. Shopping Cart
-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
After you select the product, add the product to the shopping cart. You can choose delivery or self-pickup. To choose delivery, you need to enter your address, mobile phone number and other personal information before submitting the order.
1913043cd3cd5c1f914101aaab52bab
32e057f0ba49f0d95a77f7348a724b2
ba2161dee3bd6a42f9ec77b4599f3c0
0aafb79101f1c66149679a1be9c1876
5cd23819f5d02285828ff05a62f866c
After you select a shipping address and a shipping time, you can submit the order for checkout.
5e38ebdbfa0e8d5d474158d7e651d6d
bfcd3b5191e925ef42ad0c89858fe8a
aa76c7f8d9ad41f3786d9e5ddb7e08a
On the payment page, you can choose various payment methods such as membership card, bank card, etc. After a successful payment, wait for delivery or pick up at the store according to the method you selected previously.
eab18f5934664b51480c5adba371ad7
185baa5dd70cac2f681ff30988e3231
[hashtag](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/smart-retail/retail-online-store-user-guide#id-6.-me)
6\. Me
--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
Click the avatar, you can fill in or edit your member information, such as mobile phone number, name, birthday, gender and other information. Click Confirm to submit, and the modifications are completed.
Click on the QR code icon. Your membership QR code will be displayed. With this membership QR code, you can show it to the terminal to recharge, identify membership, and other operations.
Click Me to enter my page, where you can see the user's own membership information, balance, points, membership coupons, membership codes, orders and other information.
c4ba99daf639906596b582146927140
Click Balance to view your member's balance. Click Recharge Record to view the member's recharge record. You can select a time to view the recharge record for a specific date.
Members can receive coupons after their purchase meets the amount set for the promotions. Next time when your purchase amount reaches a certain amount, you can use the coupon, the used coupon and Expired coupons will become invalid
Click ALL in My Order to enter my order list and view orders with pending payment, pending shipment, picked up, and completed status.
For unpaid orders, you can choose to cancel or pay. For orders that have been shipped, the customer can confirm receipt after receiving the goods and they will be converted into completed orders.
For completed orders, if you want to purchase again, you can click to view the details and place an order again.
If you want to know the merchant's information, you can click Store profile to view the merchant's profile, and click Store address to view the merchant's address.
[hashtag](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/smart-retail/retail-online-store-user-guide#toc17650)
7\. Points Redeem
-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
On Me page, click Points to enter the redemption page of the points mall. The products and points redemption displayed here are set by the merchant portal. You can click Redeem to use existing points to redeem the product. Click Exchange Records, you can see the redeemed products, click to apply, a QR code will appear, and then use the terminal to scan and redeem.
[hashtag](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/smart-retail/retail-online-store-user-guide#toc7944)
8\. Store List
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
If a merchant has multiple stores, you can enter the list of all stores under the merchant on the homepage of the mall and switch stores for shopping.
[PreviousRetail Terminal APP User Guidechevron-left](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/smart-retail/retail-terminal-app-user-guide)
[NextRetail Smart ECR User Guidechevron-right](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/smart-retail/retail-smart-ecr-user-guide)
Last updated 2 years ago
* [1\. Function Overview](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/smart-retail/retail-online-store-user-guide#toc18639)
* [2\. Login](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/smart-retail/retail-online-store-user-guide#toc20911)
* [3\. Home](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/smart-retail/retail-online-store-user-guide#toc4116)
* [4\. Product Categories](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/smart-retail/retail-online-store-user-guide#toc19015)
* [5\. Shopping Cart](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/smart-retail/retail-online-store-user-guide#toc31293)
* [6\. Me](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/smart-retail/retail-online-store-user-guide#id-6.-me)
* [7\. Points Redeem](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/smart-retail/retail-online-store-user-guide#toc17650)
* [8\. Store List](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/smart-retail/retail-online-store-user-guide#toc7944)
---
# Retail Terminal APP User Guide | WizarPOS Catering & Retail Soloution User Guide
[hashtag](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/smart-retail/retail-terminal-app-user-guide#toc18639)
1\. Function Overview
-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
WizarPOS terminal retail app is a retail cashier system for Android terminal. It is used in retail stores. The main functions provided by the system are as follows:
**Goods**
Merchants upload various types of goods in the merchant portal and save all products in the product list. When customers shopping, the waiter scans the barcode of the goods to checkout.
**Promotions**
Merchants can set up various types of marketing activities through the merchant portal, including discounts, full discounts, special offers, points malls, coupons for consumption and other activities, which can provide a better shopping experience.
**Membership**
Each retail merchant can recommend the merchant's online store to the customer through links or QR code. Customers scan the QR code to register and become a member of the merchant. The staff can use the terminal to recharge the balance. The member's balance can be used at checkout. Members can receive coupons for consumption, which can be deducted when making purchases.
**Payment**
Retail APP support cash, bank cards, membership cards, membership coupons and other payment methods.
**Points**
Merchants can configure points redemption activities in the merchant portal, such as 100 points redeeming a bottle of Coke, 200 points redeeming a pack of snacks, etc. The waiter uses terminal to scan the customer's redemption code and redeem the product for the customer.
**Chain stores**
If a merchant has multiple stores, it supports the chain store function. Customers can register as a member at any store under the merchant. The membership balance can be used across all stores. The membership coupons obtained through consumption can also be used at any store.
[hashtag](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/smart-retail/retail-terminal-app-user-guide#toc22756)
2\. Login
-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
Please check the email of the merchant’s account. For accounts with operator roles, enter the merchant ID, username, and password to log in to the app. Check auto login will let you automatically log in next time.
40f2675ac9dc17f1328e0a98e062737
[hashtag](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/smart-retail/retail-terminal-app-user-guide#toc5448)
3\. Home
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
The search bar allows you to search for products.
Scan function support 3 types of code:
1.Product barcode
2.Membership QR code
3.Pickup code
Stuff can place pending orders (unchecked orders are temporarily suspended), membership identify.
Click the Scan icon to scan the barcode of the product package with terminal and add it to the product list.
[hashtag](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/smart-retail/retail-terminal-app-user-guide#toc20898)
4\. Pending Order
-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
The cashier can temporarily held the orders, for customers who want to postpone the checkout, so that the next customers can checkout first, and then select unchecked orders from the pending order list to perform checkout operations.
[hashtag](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/smart-retail/retail-terminal-app-user-guide#toc10489)
5\. Checkout
--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
Click Check out on the home page to enter the checkout page. You can use cash or bank cards to pay.
###
[hashtag](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/smart-retail/retail-terminal-app-user-guide#identify-membership)
Identify Membership
The customer can present the membership QR code before checkout. The cashier clicks Membership to identify the membership, and the current member's info and balance will be displayed. At this time, the membership card icon and coupon icon will be available at checkout page. Checkout supports multiple payments with any payment method.
circle-info
**Note: Only one coupon can be used at checkout.**
[hashtag](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/smart-retail/retail-terminal-app-user-guide#id-6.-search)
6\. Search
----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
You can search for products at the top of the homepage. By manually entering part of the product name or barcode number.
1688700618646
[hashtag](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/smart-retail/retail-terminal-app-user-guide#toc19254)
7\. Online Order
------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
Click Online order on the left menu to enter the mall order page. You can view the orders to be shipped, shipped, pending payment, completed, and canceled. The orders are divided into delivery and self-pickup. You can enter the order details. Click Delivery. For self-pickup orders, customers can show the delivery code, then scan the code to quickly locate the order and perform delivery operations.
For shipped orders, you can view details and reprint the order receipt.
[hashtag](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/smart-retail/retail-terminal-app-user-guide#toc6897)
8\. Member
-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
Click Gift card on the left menu to enter the member identification page. You can identify members by scanning the QR code and entering the membership card number manually..
After the identification is successful, you can check the members info such as membership number, balance, and other information. Customer can recharge their membership card with cash or bank card. Also, can check the member's transaction history and the member's coupons.
[hashtag](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/smart-retail/retail-terminal-app-user-guide#id-9.-points-mall)
9\. Points Mall
--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
Click Points on the left menu to enter the points redemption function. Items currently redeemed and to be redeemed will be displayed. The cashier can use the scan function to scan the customer's points redemption QR code to redeem items.
[hashtag](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/smart-retail/retail-terminal-app-user-guide#toc7772)
10\. Sales Report
------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
Click Sale report to enter the sales report, which displays the sales summary of the day. Click Print to print the report receipt.
[hashtag](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/smart-retail/retail-terminal-app-user-guide#toc21993)
11\. Product Categories
-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
Click Goods & Categories to enter the category list. Click a category to enter the product list under that category. You can view product prices and de tails, add products, and edit and delete products.
Click + to add new products.
[hashtag](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/smart-retail/retail-terminal-app-user-guide#toc5839)
12\. Sales Order
-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
Click Sales Order to view all sales orders. Click on an order to view details. For sales orders, you can refund the order. After entering the manager password, you can perform refund operations.
[hashtag](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/smart-retail/retail-terminal-app-user-guide#toc21954)
13\. Inventory Manage
-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
Click Inventory Manage to enter warehouse management.
Click Stockin to enter the stock in process. You can scan the QR code and manually select the product. After confirming, the process is completed.
Click Stockout to enter the stock in process. You can scan the QR code and manually select the product. After confirming, the process is completed.
Click Inventory to enter the inventory count page. You can scan the QR code and manually select the product, then enter the inventory quantity of the product, and complete the count process.
Click Stock query to enter the inventory query.
Click Stockin query to enter the stockin query. The list displays all stockin orders. Select a stockin order to enter and query the stockin details.
Click Stockout query to enter the stockout query. The list displays all stockout orders. Select a certain stockout order to enter and query the stockout details.
Click Inventory query to enter the inventory query and display all inventory orders. Click to view the details of a certain inventory order. You can also filter the inventory orders within a certain time period based on time to view.
[hashtag](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/smart-retail/retail-terminal-app-user-guide#toc1778)
14\. Parameter settings
------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
In the parameter setting page, you can view the quantity of the current order receipt. You can turn on/off message notifications. After turning it on, the order placed by the customer in the mall will be notified to the handheld retail store. You can clear the cache and data below.
[PreviousSmart Retailchevron-left](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/smart-retail)
[NextRetail Online Store User Guidechevron-right](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/smart-retail/retail-online-store-user-guide)
Last updated 2 years ago
* [1\. Function Overview](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/smart-retail/retail-terminal-app-user-guide#toc18639)
* [2\. Login](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/smart-retail/retail-terminal-app-user-guide#toc22756)
* [3\. Home](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/smart-retail/retail-terminal-app-user-guide#toc5448)
* [4\. Pending Order](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/smart-retail/retail-terminal-app-user-guide#toc20898)
* [5\. Checkout](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/smart-retail/retail-terminal-app-user-guide#toc10489)
* [Identify Membership](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/smart-retail/retail-terminal-app-user-guide#identify-membership)
* [6\. Search](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/smart-retail/retail-terminal-app-user-guide#id-6.-search)
* [7\. Online Order](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/smart-retail/retail-terminal-app-user-guide#toc19254)
* [8\. Member](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/smart-retail/retail-terminal-app-user-guide#toc6897)
* [9\. Points Mall](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/smart-retail/retail-terminal-app-user-guide#id-9.-points-mall)
* [10\. Sales Report](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/smart-retail/retail-terminal-app-user-guide#toc7772)
* [11\. Product Categories](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/smart-retail/retail-terminal-app-user-guide#toc21993)
* [12\. Sales Order](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/smart-retail/retail-terminal-app-user-guide#toc5839)
* [13\. Inventory Manage](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/smart-retail/retail-terminal-app-user-guide#toc21954)
* [14\. Parameter settings](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/smart-retail/retail-terminal-app-user-guide#toc1778)
---
# Catering Smart ECR User Guide | WizarPOS Catering & Retail Soloution User Guide
WizarPOS Catering Solution
[hashtag](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/smart-catering/catering-smart-ecr-user-guide#toc143508823)
1\. Function Overview
----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
WizarPOS Smart ECR Catering is a professional ordering system based on Android devices, providing efficient services and convenient ordering experience to catering merchants. The system has the following functions:
**1\. Menu**
The merchant uploads various types of dishes, hot dishes, cold dishes, Western food, dim sum, snacks, etc. And displays all the dishes in the menu. When ordering, the dishes can be customized according to the specifications, tastes, methods, and toppings.
**2\. Promotions**
Merchants can set up various types of marketing activities through the merchant portal, including discounts, full discounts, special offers, points malls, coupons for consumption and other activities, which can provide great dining experiences.
**3\. Membership**
Each catering merchant can use the table QR code or takeout QR code to allow customers to scan the QR to register and become a member of the merchant. The waiter can use terminal to recharge for the members, and the member balance can be used when order and pay. Members can get coupons through consumption.
**4\. Payment**
Handheld ordering can support cash, bank cards, membership payment, membership coupons and other payment methods.
**5\. Points**
Merchants can configure goods for exchange in the merchant portal, such as 100 points to exchange for a bottle of Coke, 500 points to exchange for a dish. The waiter uses a terminal to scan the customer's redemption code and redeem the goods for the customer.
[hashtag](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/smart-catering/catering-smart-ecr-user-guide#toc143508824)
2\. Login
----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
If you want to log in to the terminal, you need to enter the merchant ID, username and password.
The merchant ID is when the service provider onboarding the merchant. An assigned merchant ID can be obtained from the email after the merchant is successfully onboarded. At the same time, the merchant administrator account and initial password will be given. The merchant administrator must log in to the merchant backend for the first time, change the initial password, and create an operator account in System Settings -> Account Management. The created operator account can be used to log in to the terminal catering application.
**Note:** **The administrator account of the merchant received by email cannot be used to log in to the terminal application.**
Enter the MID, username, and password, and click Login to enter the homepage.
[hashtag](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/smart-catering/catering-smart-ecr-user-guide#toc143508825)
3\. Home
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
The home page is divided into three areas, function area on the left, display area in the middle, and the checkout area below.
The function area has the following functions:
Dine-in, reservations, reports, membership, points, takeout, notifications, menu management and settings.
[hashtag](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/smart-catering/catering-smart-ecr-user-guide#toc143508826)
4\. Dine-in
------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
The merchant clicks on the dine-in to choose the table, and the table displays the table name, maximum customer and status. The table status is divided into free and dining. The table is set in the merchant portal. Click the table to enter the menu.
In the menu, you can select dishes according to the category of the dishes, and you can choose the specifications, tastes, toppings, and methods of the dishes.
Select dishes and dish specifications to add to the ordering list on the right. You can view the selected dishes in the ordering list, and support modify dishes. Click Remarks below to fill in the remark information.
Click Order to place an order. The table status changes to dining, the printer print receipts and kitchen receipts, and the kitchen prepares dishes according to the order.
Select the table and click the dining button on the lower right to jump to the ordering list. On this page, waiter can modify dishes .
Select the dining table and click the bill button to jump to the payment. The cashier displays the payment amount, taxes, discount information on the total order amount, etc. You can choose the payment method, such as split payment (multiple payments), and the customer selects the tip ratio or directly enters the tip amount.
Click on the number of people to split the order, up to 10 orders; click on the tipping ratio, the default is 10%, 15%, 20%, which can also be customized in the system settings.
Payment methods include cash payment, bank card payment, membership payment or other payment. Among them, bank cards need to be connected to payment channels, and membership payments need to identify membership QR code. Click on the lower right corner for member identification.
After identifying the member, you can choose a membership card or coupon to pay. You can also use other payment methods customized by the merchant to record other types of transactions.
After a success payment, you will be redirected to the home page, the table will be changed to idle, and the label machine will print the receipt.
[hashtag](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/smart-catering/catering-smart-ecr-user-guide#toc143508827)
5\. Reservations
-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
Click Book to enter the table reservation list. The page can manage customers' reservation table information. Make reservations for customers based on table. Reservation information includes date, reservation time, number of diners, etc.
[hashtag](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/smart-catering/catering-smart-ecr-user-guide#toc143508828)
6\. Reports
------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
Click the report menu, and the page displays business reports, sales orders, today's summary and tip reports. These reports are summary queries that can query order information based on time period and type.
###
[hashtag](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/smart-catering/catering-smart-ecr-user-guide#toc143508829)
6.1 Sales Reports
The business report displays the revenue, discounts, refunds and other information of the day's business, and supports printing of business report documents.
###
[hashtag](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/smart-catering/catering-smart-ecr-user-guide#toc143508830)
6.2 Sales Order
Sales reports can query order details based on time range and type.
Sales Orders display all online and dine-in orders.
Select an order and click to view details. In the pop-up window, you can view all the details of the order, and you can print or return the order. Refund requires entering the manager password, which is set in the merchant's portal.
After entering the password to perform the refund operation, a refund receipt will be printed.
###
[hashtag](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/smart-catering/catering-smart-ecr-user-guide#toc143508831)
6.3 Today’s Summary
You can view all the dishes sold today on today's summary page.
###
[hashtag](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/smart-catering/catering-smart-ecr-user-guide#toc143508832)
6.4 Tip Report
Click Tips Report to enter tip statistics. You can check the tip amount and number of orders based on employees and time.
[hashtag](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/smart-catering/catering-smart-ecr-user-guide#toc143508833)
7\. Membership
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
Click the member menu to enter the member inquiry page. You can enter the member ID or scan the QR code. After identifying the member, its balance, number of points, and number of coupons will be displayed. You can recharge for the members, and you can also view recharge details and transaction details.
Click Recharge to enter the recharge page. The payment method supports cash and bank card. Enter the recharge amount. After the payment is successful, the balance will be credited immediately. Member accounts can also view coupons.
[hashtag](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/smart-catering/catering-smart-ecr-user-guide#toc143508834)
8\. Points
-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
Click the points menu to enter the points redemption function. The page displays the redemption records, including items used and to be used. The waiter can use the scanner to scan the customer's points redemption QR code to redeem items.
[hashtag](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/smart-catering/catering-smart-ecr-user-guide#toc143508835)
9\. Delivery
-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
Click on Delivery to enter the takeout list. The page displays two lists of picked up and unpicked meals. Select the unpicked meal list, click on the order and click on the lower right corner to pick up the meal, then the status of the order will change to Completed.
[hashtag](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/smart-catering/catering-smart-ecr-user-guide#toc143508836)
10\. Queue
-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
Enter the queuing page. On the page, you can check the queuing status of the table, such as the number of people at the table, waiting time, etc. The waiter can click the three icons in the list to perform voice announcements, customer dining and queuing invalidation. Click on the number transfer information at the bottom right to view the historical queue details that have expired.
Click the pick up number button, select the type of the table, and the terminal will print a receipt to the customer. Customers can use their mobile phone browser to scan the QR code on the ticket to check the queue information in real time to prevent passing the number.
After scanning the QR code, check the current dining queue status on your mobile browser.
[hashtag](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/smart-catering/catering-smart-ecr-user-guide#toc143508837)
11\. Menu Management
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
The menu management page supports the operations of adding, modifying, and deleting dishes. You can modify the sold out status of a dish.
[hashtag](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/smart-catering/catering-smart-ecr-user-guide#toc143508838)
12\. Category Management
-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
In category management, you can create categories for dishes to make it easier to manage dishes.
[hashtag](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/smart-catering/catering-smart-ecr-user-guide#toc143508839)
13\. Settings
--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
Click the settings menu to enter the system settings page, which displays basic parameters, printing parameters, and other payment settings. The basic parameters display relevant information such as the current merchant number and merchant name. You can turn on or off the message notification function as needed, and choose whether to automatically receive orders. By default, these two functions are turned off. When turned off, you need to manually receive orders and print operations. When turned on, the terminal will automatically print new orders. Merchants can also set different tip ratios according to needs.
In the printing parameters, you can configure the parameters related to the back kitchen and front desk cashier printing.
Other payments are to configure payment methods other than mainstream payment methods.
[hashtag](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/smart-catering/catering-smart-ecr-user-guide#toc143508840)
14\. Notification
------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
In the notification menu, you can receive order notifications for customers' online orders on their mobile phones. The green icon represents a dine-in order. If a customer places an order but does not pay, they will receive a corresponding order notification and the waiter can click to take the order and print it. The yellow icon represents a takeout order. After the customer places the order and completes the payment, the order notification will be received in the message notification bar, and the waiter can click to take the order and print it. If the kitchen network printer has been configured , the kitchen receipt will be automatically printed.
[PreviousCatering Terminal APP User Guidechevron-left](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/smart-catering/catering-terminal-app-user-guide)
[NextSmart Retailchevron-right](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/smart-retail)
Last updated 2 years ago
* [1\. Function Overview](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/smart-catering/catering-smart-ecr-user-guide#toc143508823)
* [2\. Login](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/smart-catering/catering-smart-ecr-user-guide#toc143508824)
* [3\. Home](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/smart-catering/catering-smart-ecr-user-guide#toc143508825)
* [4\. Dine-in](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/smart-catering/catering-smart-ecr-user-guide#toc143508826)
* [5\. Reservations](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/smart-catering/catering-smart-ecr-user-guide#toc143508827)
* [6\. Reports](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/smart-catering/catering-smart-ecr-user-guide#toc143508828)
* [6.1 Sales Reports](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/smart-catering/catering-smart-ecr-user-guide#toc143508829)
* [6.2 Sales Order](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/smart-catering/catering-smart-ecr-user-guide#toc143508830)
* [6.3 Today’s Summary](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/smart-catering/catering-smart-ecr-user-guide#toc143508831)
* [6.4 Tip Report](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/smart-catering/catering-smart-ecr-user-guide#toc143508832)
* [7\. Membership](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/smart-catering/catering-smart-ecr-user-guide#toc143508833)
* [8\. Points](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/smart-catering/catering-smart-ecr-user-guide#toc143508834)
* [9\. Delivery](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/smart-catering/catering-smart-ecr-user-guide#toc143508835)
* [10\. Queue](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/smart-catering/catering-smart-ecr-user-guide#toc143508836)
* [11\. Menu Management](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/smart-catering/catering-smart-ecr-user-guide#toc143508837)
* [12\. Category Management](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/smart-catering/catering-smart-ecr-user-guide#toc143508838)
* [13\. Settings](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/smart-catering/catering-smart-ecr-user-guide#toc143508839)
* [14\. Notification](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/smart-catering/catering-smart-ecr-user-guide#toc143508840)
---
# POS_Specs | CloudPOS SDK
###
[hashtag](https://smartpossdk.gitbook.io/cloudpossdk/pos_specs#q1-all-in-one-handheld-smart-pos)
Q1(All-in-one Handheld Smart POS)
####
[hashtag](https://smartpossdk.gitbook.io/cloudpossdk/pos_specs#spec)
[Specarrow-up-right](http://ftp.wizarpos.com/advanceSDK/posspec/wizarPOS_Q1.pdf)
####
[hashtag](https://smartpossdk.gitbook.io/cloudpossdk/pos_specs#user-manual)
[User Manualarrow-up-right](http://ftp.wizarpos.com/device/Q1usermanualENV1.2,202104.pdf)
###
[hashtag](https://smartpossdk.gitbook.io/cloudpossdk/pos_specs#q2-most-affordable-smart-pos)
Q2(Most Affordable Smart POS)
####
[hashtag](https://smartpossdk.gitbook.io/cloudpossdk/pos_specs#spec-1)
[Specarrow-up-right](http://ftp.wizarpos.com/advanceSDK/posspec/wizarPOS_Q2.pdf)
####
[hashtag](https://smartpossdk.gitbook.io/cloudpossdk/pos_specs#user-manual-1)
[User Manualarrow-up-right](http://ftp.wizarpos.com/device/Q2usermanualENV1.2,20221.11.pdf)
###
[hashtag](https://smartpossdk.gitbook.io/cloudpossdk/pos_specs#q2-k2-tap-and-go-smart-pos)
Q2(K2,Tap and Go Smart POS)
####
[hashtag](https://smartpossdk.gitbook.io/cloudpossdk/pos_specs#spec-2)
[Specarrow-up-right](http://ftp.wizarpos.com/advanceSDK/posspec/K2.pdf)
####
[hashtag](https://smartpossdk.gitbook.io/cloudpossdk/pos_specs#user-manual-2)
[User Manualarrow-up-right](https://ftp.wizarpos.com/techsupport/specs/K2UserManual.pdf)
###
[hashtag](https://smartpossdk.gitbook.io/cloudpossdk/pos_specs#q2-qd6-tap-and-go-smart-pos)
Q2(QD6,Tap and Go Smart POS)
####
[hashtag](https://smartpossdk.gitbook.io/cloudpossdk/pos_specs#spec-3)
[Specarrow-up-right](http://ftp.wizarpos.com/advanceSDK/posspec/Customized/QD6.pdf)
###
[hashtag](https://smartpossdk.gitbook.io/cloudpossdk/pos_specs#q2-premium-most-affordable-smart-pos)
Q2 Premium(Most Affordable Smart POS)
####
[hashtag](https://smartpossdk.gitbook.io/cloudpossdk/pos_specs#spec-4)
[Specarrow-up-right](http://ftp.wizarpos.com/advanceSDK/posspec/Q2_Premium.pdf)
####
[hashtag](https://smartpossdk.gitbook.io/cloudpossdk/pos_specs#user-manual-3)
[User Manualarrow-up-right](https://ftp.wizarpos.com/techsupport/specs/Q2PUserManual.pdf)
###
[hashtag](https://smartpossdk.gitbook.io/cloudpossdk/pos_specs#q3-on-screen-contactless-acceptance)
Q3(on-screen contactless acceptance)
####
[hashtag](https://smartpossdk.gitbook.io/cloudpossdk/pos_specs#spec-5)
[Specarrow-up-right](http://ftp.wizarpos.com/advanceSDK/posspec/Q3PINPAD.pdf)
####
[hashtag](https://smartpossdk.gitbook.io/cloudpossdk/pos_specs#user-manual-4)
[User Manualarrow-up-right](http://ftp.wizarpos.com/device/Q3usermanualV1.2,202007.pdf)
###
[hashtag](https://smartpossdk.gitbook.io/cloudpossdk/pos_specs#d22-smart-payment-kiosk)
D22(Smart Payment Kiosk)
####
[hashtag](https://smartpossdk.gitbook.io/cloudpossdk/pos_specs#spec-6)
[Specarrow-up-right](http://ftp.wizarpos.com/advanceSDK/posspec/D22.pdf)
###
[hashtag](https://smartpossdk.gitbook.io/cloudpossdk/pos_specs#d3-smart-ecr)
D3(Smart ECR)
####
[hashtag](https://smartpossdk.gitbook.io/cloudpossdk/pos_specs#spec-7)
[Specarrow-up-right](http://ftp.wizarpos.com/advanceSDK/posspec/D3_Classic_White(Android_11).pdf)
###
[hashtag](https://smartpossdk.gitbook.io/cloudpossdk/pos_specs#unattended-pos-smart-self-service-terminal)
Unattended POS(Smart Self-service Terminal)
####
[hashtag](https://smartpossdk.gitbook.io/cloudpossdk/pos_specs#spec-8)
[Specarrow-up-right](http://ftp.wizarpos.com/advanceSDK/posspec/Wizarpos_UPT.pdf)
####
[hashtag](https://smartpossdk.gitbook.io/cloudpossdk/pos_specs#user-munual)
[User Munualarrow-up-right](https://ftp.wizarpos.com/techsupport/software/UPTManual.pdf)
###
[hashtag](https://smartpossdk.gitbook.io/cloudpossdk/pos_specs#bus-validator)
Bus Validator
####
[hashtag](https://smartpossdk.gitbook.io/cloudpossdk/pos_specs#spec-9)
[Specarrow-up-right](http://ftp.wizarpos.com/advanceSDK/posspec/Ticket_Validator.pdf)
###
[hashtag](https://smartpossdk.gitbook.io/cloudpossdk/pos_specs#q3mini)
Q3Mini
####
[hashtag](https://smartpossdk.gitbook.io/cloudpossdk/pos_specs#spec-10)
[Specarrow-up-right](http://ftp.wizarpos.com/advanceSDK/posspec/Datesheet-Q3MIN.pdf)
####
[hashtag](https://smartpossdk.gitbook.io/cloudpossdk/pos_specs#user-manual-5)
[User Manualarrow-up-right](https://ftp.wizarpos.com/techsupport/specs/Q3MINI-HUserManualNoBase.pdf)
###
[hashtag](https://smartpossdk.gitbook.io/cloudpossdk/pos_specs#q3pro)
Q3PRO
####
[hashtag](https://smartpossdk.gitbook.io/cloudpossdk/pos_specs#spec-11)
[Specarrow-up-right](http://ftp.wizarpos.com/advanceSDK/posspec/Datesheet-Q3PRO.pdf)
####
[hashtag](https://smartpossdk.gitbook.io/cloudpossdk/pos_specs#user-manual-6)
[User Manualarrow-up-right](https://ftp.wizarpos.com/techsupport/specs/Q3proUserManual(Android14)250328.pdf)
###
[hashtag](https://smartpossdk.gitbook.io/cloudpossdk/pos_specs#q3pda)
**Q3PDA**
####
[hashtag](https://smartpossdk.gitbook.io/cloudpossdk/pos_specs#spec-12)
[Specarrow-up-right](http://ftp.wizarpos.com/advanceSDK/posspec/Q3PDA.pdf)
####
[hashtag](https://smartpossdk.gitbook.io/cloudpossdk/pos_specs#user-manual-7)
[User Manualarrow-up-right](https://ftp.wizarpos.com/techsupport/specs/PDAUserManual.pdf)
###
[hashtag](https://smartpossdk.gitbook.io/cloudpossdk/pos_specs#pos1-key-injection-terminal)
POS1(Key Injection Terminal)
####
[hashtag](https://smartpossdk.gitbook.io/cloudpossdk/pos_specs#spec-13)
[Specarrow-up-right](http://ftp.wizarpos.com/device/wizarPOS1EnV2.0_20170623.pdf)
####
[hashtag](https://smartpossdk.gitbook.io/cloudpossdk/pos_specs#user-manual-8)
[User Manualarrow-up-right](http://ftp.wizarpos.com/device/WizarPOS1QIGEN.pdf)
[PreviousMDB Communication Protocalchevron-left](https://smartpossdk.gitbook.io/cloudpossdk/cloudpos-sdk/mdb-communication-protocal)
[NextFAQchevron-right](https://smartpossdk.gitbook.io/cloudpossdk/faq)
Last updated 8 months ago
* [Q1(All-in-one Handheld Smart POS)](https://smartpossdk.gitbook.io/cloudpossdk/pos_specs#q1-all-in-one-handheld-smart-pos)
* [Q2(Most Affordable Smart POS)](https://smartpossdk.gitbook.io/cloudpossdk/pos_specs#q2-most-affordable-smart-pos)
* [Q2(K2,Tap and Go Smart POS)](https://smartpossdk.gitbook.io/cloudpossdk/pos_specs#q2-k2-tap-and-go-smart-pos)
* [Q2(QD6,Tap and Go Smart POS)](https://smartpossdk.gitbook.io/cloudpossdk/pos_specs#q2-qd6-tap-and-go-smart-pos)
* [Q2 Premium(Most Affordable Smart POS)](https://smartpossdk.gitbook.io/cloudpossdk/pos_specs#q2-premium-most-affordable-smart-pos)
* [Q3(on-screen contactless acceptance)](https://smartpossdk.gitbook.io/cloudpossdk/pos_specs#q3-on-screen-contactless-acceptance)
* [D22(Smart Payment Kiosk)](https://smartpossdk.gitbook.io/cloudpossdk/pos_specs#d22-smart-payment-kiosk)
* [D3(Smart ECR)](https://smartpossdk.gitbook.io/cloudpossdk/pos_specs#d3-smart-ecr)
* [Unattended POS(Smart Self-service Terminal)](https://smartpossdk.gitbook.io/cloudpossdk/pos_specs#unattended-pos-smart-self-service-terminal)
* [Bus Validator](https://smartpossdk.gitbook.io/cloudpossdk/pos_specs#bus-validator)
* [Q3Mini](https://smartpossdk.gitbook.io/cloudpossdk/pos_specs#q3mini)
* [Q3PRO](https://smartpossdk.gitbook.io/cloudpossdk/pos_specs#q3pro)
* [Q3PDA](https://smartpossdk.gitbook.io/cloudpossdk/pos_specs#q3pda)
* [POS1(Key Injection Terminal)](https://smartpossdk.gitbook.io/cloudpossdk/pos_specs#pos1-key-injection-terminal)
---
# Permissions | CloudPOS SDK
###
[hashtag](https://smartpossdk.gitbook.io/cloudpossdk/cloudpos-sdk/permissions#permissions)
Permissions
In order to interact with various devices on the terminal, your application needs to declare the relevant permissions for each device. Below is the list of permissions along with their descriptions:
Permission
Description
android.permission.CLOUDPOS\_PRINTER
Access the printer
android.permission.CLOUDPOS\_MSR
Access the mega stripe reader (MSR)
android.permission.CLOUDPOS\_CONTACTLESS\_CARD
Access the contactless card reader (RF card reader)
android.permission.CLOUDPOS\_SMARTCARD
Access the smart card reader
android.permission.CLOUDPOS\_SERIAL
Access the serial port (RS232)
android.permission.CLOUDPOS\_LED
Access the LED device
android.permission.CLOUDPOS\_CUSTOMER\_DISPLAY
Access the second display device
android.permission.CLOUDPOS\_CLONESCREEN
Access the HDMI device
android.permission.CLOUDPOS\_MONEYBOX
Access the cash drawer
android.permission.CLOUDPOS\_FINGERPRINT
Access the fingerprint device
android.permission.CLOUDPOS\_PIN\_GET\_PIN\_BLOCK
Retrieve the encrypted PIN block by PINPad
android.permission.CLOUDPOS\_PIN\_MAC
Calculate the MAC by the MAC key in PINPad
android.permission.CLOUDPOS\_PIN\_ENCRYPT\_DATA
Encrypt data by the data key in PINPad
android.permission.CLOUDPOS\_PIN\_UPDATE\_USER\_KEY
Update the session (user) key of MasterKey/SessionKey schema
android.permission.CLOUDPOS\_SIGNATURE
Access the signature board
android.permission.CLOUDPOS\_SAFE\_MODULE
Access HSM
android.permission.SYSTEM\_ALERT\_WINDOW
Used when printing HTML
android.permission.CLOUDPOS\_EXT\_USB\_CTRL
Access the double USB control
Ensure that your application requests and is granted these permissions appropriately to enable seamless interaction with the CloudPOS SDK. For more detailed information, refer to the documentation sections related to each device API and consult the POS Spec, FAQs, or device-specific manuals.
Explore the CloudPOS SDK resources using the quick links provided, including Device API, Device Samples, EMV Development, BarCode Scan, Printer Manual, and TMS Manual.
Thank you for using wizarPOS, and if you have any questions, feel free to explore the available resources or contact our support team.
[PreviousJava API Sampleschevron-left](https://smartpossdk.gitbook.io/cloudpossdk/cloudpos-sdk/java-api-samples)
[NextError codechevron-right](https://smartpossdk.gitbook.io/cloudpossdk/cloudpos-sdk/error-code)
Last updated 1 year ago
---
# EMV Develop Spec | CloudPOS SDK
This document aims to simplify the understanding of EMV development specifications, providing clear information for Android application developers in the Smart POS industry. Please refer to the provided links for downloads and additional details.
###
[hashtag](https://smartpossdk.gitbook.io/cloudpossdk/cloudpos-sdk/emv-develop-spec#emv-api)
EMV API
Version
Download
Release Time
4.35
[EMV kernel APIarrow-up-right](https://ftp.wizarpos.com/emv/EMVKernel_Android_interface_4.35(20250414).pdf)
2025-04-14
###
[hashtag](https://smartpossdk.gitbook.io/cloudpossdk/cloudpos-sdk/emv-develop-spec#emv-process-flow)
EMV Process Flow
Version
Download
Release Time
230314
[EMV Process Flowarrow-up-right](https://ftp.wizarpos.com/emv/EmvProcessFlow_230314.pdf)
2023-04-17
###
[hashtag](https://smartpossdk.gitbook.io/cloudpossdk/cloudpos-sdk/emv-develop-spec#emv-tag-reference)
[EMV Tag referencearrow-up-right](http://www.emvlab.org/emvtags/)
###
[hashtag](https://smartpossdk.gitbook.io/cloudpossdk/cloudpos-sdk/emv-develop-spec#emv-demo)
EMV Demo
####
[hashtag](https://smartpossdk.gitbook.io/cloudpossdk/cloudpos-sdk/emv-develop-spec#java-api-demo)
Java API Demo
**Note:** After downloading the latest EMV sample, follow these steps:
1. Check for the latest CloudPOS SDK AAR.
2. Replace the existing AAR in the EMV Sample.
Version
Download
Release Time
Description
EMVSample\_240607.zip
[EMVSamplearrow-up-right](https://ftp.wizarpos.com/emv/EMVSample_240607.zip)
2024-06-07
EMVSample Standard
EMVSample\_20250401
[EMVSample(Using the JavaSDK AAR Library)arrow-up-right](https://ftp.wizarpos.com/emv/EMVSample_20250401.zip)
2025-04-01
Supports Android NFC, [refer to the modification methodarrow-up-right](https://ftp.wizarpos.com/emv/ChangehistoryforNFC.txt)
####
[hashtag](https://smartpossdk.gitbook.io/cloudpossdk/cloudpos-sdk/emv-develop-spec#c-api-demo-deprecated)
C API Demo (Deprecated)
Version
Download
Release Time
Description
20230627
[EMVSample(Using the JNI Library)arrow-up-right](https://ftp.wizarpos.com/emv/EMVSampleJNI_20230627.zip)
2023-06-27
support Android 12.
[PreviousCloudPOS SDKchevron-left](https://smartpossdk.gitbook.io/cloudpossdk)
[NextScanning Service Usagechevron-right](https://smartpossdk.gitbook.io/cloudpossdk/cloudpos-sdk/scanning-service-usage)
Last updated 3 months ago
* [EMV API](https://smartpossdk.gitbook.io/cloudpossdk/cloudpos-sdk/emv-develop-spec#emv-api)
* [EMV Process Flow](https://smartpossdk.gitbook.io/cloudpossdk/cloudpos-sdk/emv-develop-spec#emv-process-flow)
* [EMV Tag reference](https://smartpossdk.gitbook.io/cloudpossdk/cloudpos-sdk/emv-develop-spec#emv-tag-reference)
* [EMV Demo](https://smartpossdk.gitbook.io/cloudpossdk/cloudpos-sdk/emv-develop-spec#emv-demo)
---
# Java API Samples | CloudPOS SDK
###
[hashtag](https://smartpossdk.gitbook.io/cloudpossdk/cloudpos-sdk/java-api-samples#java-api-samples)
Java API Samples
###
[hashtag](https://smartpossdk.gitbook.io/cloudpossdk/cloudpos-sdk/java-api-samples#overview)
Overview
Explore the power of the CloudPOS Java API with these practical examples. Before diving in, ensure you have the latest CloudPOS SDK AAR file, available for download at CloudPOS SDK AAR. Replace any outdated files as necessary.
###
[hashtag](https://smartpossdk.gitbook.io/cloudpossdk/cloudpos-sdk/java-api-samples#cloudpos-api-demos)
CloudPOS API Demos
Description
Download
Cloudpos APIDemo for all the device API
[CloudPOS API demoarrow-up-right](https://github.com/SmartPOSSamples/APIDemoForAar.git)
Encapsulate APIDemo, Load HTML using WebView, demonstrate using JavaScript to call SDK interface in HTML/H5
[API calling from JavaScript demoarrow-up-right](https://github.com/SmartPOSSamples/WebviewAPIDemo)
A simple demo for LED light
[LED demo 1.6.1.5arrow-up-right](https://github.com/SmartPOSSamples/LEDDemo.git)
A simple demo for swiping MSR card
[MSR demo 1.6.1.5arrow-up-right](https://github.com/SmartPOSSamples/MSRDemo.git)
A simple demo for PINPAD
[PINPAD demo 1.6.1.5arrow-up-right](https://github.com/SmartPOSSamples/PINPADDemo.git)
A simple demo for the printer
[Printer demo 1.6.1.5arrow-up-right](https://github.com/SmartPOSSamples/PrinterDemo.git)
A simple demo about how to sign on the screen
[Signature demo 1.6.1.5arrow-up-right](https://github.com/SmartPOSSamples/SignatureDemo.git)
A simple swipe card and print calling to simulate payment
[SwipeCard&Print demo 1.6.1.5arrow-up-right](https://github.com/SmartPOSSamples/SimulatePaymentDemo.git)
A demo showcasing fingerprint functionality
F[ingerprint demoarrow-up-right](https://github.com/SmartPOSSamples/FingerprintForAar)
Explore the Biosec ISO fingerprint demo
[Biosec ISO fingerprint demoarrow-up-right](https://github.com/SmartPOSSamples/BiosecISOfingerprint-.git)
Demo for DUKPT (Derived Unique Key Per Transaction) of PINPAD
[DUKPT demo 1.6.1.5arrow-up-right](https://github.com/SmartPOSSamples/DukptDemo.git)
A simple demo for calling the printer API from JavaScript
[Print from JavaScript demoarrow-up-right](https://github.com/SmartPOSSamples/JSPrintDemo.git)
###
[hashtag](https://smartpossdk.gitbook.io/cloudpossdk/cloudpos-sdk/java-api-samples#kotlin-samples)
Kotlin Samples
Explore CloudPOS Kotlin API with the following sample:
Description
Download
Cloudpos Kotlin APIDemo for all device API
[CloudPOS Kotlin API demo 1.6.2.arrow-up-right](https://github.com/SmartPOSSamples/APIDemoForAarBykotlin)
[1arrow-up-right](https://github.com/SmartPOSSamples/APIDemoForAarBykotlin)
Feel free to experiment and integrate these samples into your projects. For any queries or assistance, refer to the CloudPOS SDK documentation or contact our support team.
Thank you for choosing CloudPOS for your development needs!
[PreviousCloudPOS SDK AARchevron-left](https://smartpossdk.gitbook.io/cloudpossdk/cloudpos-sdk/cloudpos-sdk-aar)
[NextPermissionschevron-right](https://smartpossdk.gitbook.io/cloudpossdk/cloudpos-sdk/permissions)
Last updated 5 months ago
* [Java API Samples](https://smartpossdk.gitbook.io/cloudpossdk/cloudpos-sdk/java-api-samples#java-api-samples)
* [Overview](https://smartpossdk.gitbook.io/cloudpossdk/cloudpos-sdk/java-api-samples#overview)
* [CloudPOS API Demos](https://smartpossdk.gitbook.io/cloudpossdk/cloudpos-sdk/java-api-samples#cloudpos-api-demos)
* [Kotlin Samples](https://smartpossdk.gitbook.io/cloudpossdk/cloudpos-sdk/java-api-samples#kotlin-samples)
---
# Scanning Service Usage | CloudPOS SDK
This documentation is crafted to aid Android application developers for the Smart POS. It clarifies the functionality of the scanning service and provides details on the released SDKs, testing applications, and features for quickly launching the scan application. For specific downloads and further information, refer to the provided links and sections.
###
[hashtag](https://smartpossdk.gitbook.io/cloudpossdk/cloudpos-sdk/scanning-service-usage#overview)
Overview
The scanning service enables Android devices equipped with imaging hardware, such as cameras, to scan barcodes or QR codes, retrieving encoded data. This encoded information typically includes a web address, geographic coordinates, small text excerpts, and commercial product codes.
###
[hashtag](https://smartpossdk.gitbook.io/cloudpossdk/cloudpos-sdk/scanning-service-usage#document)
Document
Version
Download
Release Time
3.9.6
[CloudposScannerUsage\_3.9.arrow-up-right](https://ftp.wizarpos.com/barcodescan/CloudposScannerUsage_3.9.6_en.pdf)
[6arrow-up-right](https://ftp.wizarpos.com/barcodescan/CloudposScannerUsage_3.9.6_en.pdf)
2024-04-11
####
[hashtag](https://smartpossdk.gitbook.io/cloudpossdk/cloudpos-sdk/scanning-service-usage#demos)
Demos
Version
Download
Release Time
3.9.5
[CloudposScannerDemoarrow-up-right](https://github.com/SmartPOSSamples/CloudposScannerDemo.git)
2024-02-02
3.9.5
[CloudposScannerFloatModeDemoarrow-up-right](https://github.com/SmartPOSSamples/CloudposScannerFloatModeDemo.git)
2024-02-02
3.9.5
[ScanWithButtonDemoarrow-up-right](https://github.com/SmartPOSSamples/ScanWithButtonDemo)
2024-04-28
Please get the lastest [SDK AAR](https://smartpossdk.gitbook.io/cloudpossdk/cloudpos-sdk/cloudpos-sdk-aar)
###
[hashtag](https://smartpossdk.gitbook.io/cloudpossdk/cloudpos-sdk/scanning-service-usage#scan-barcode-testing-application)
Scan Barcode Testing Application
[Testing APK Downloadarrow-up-right](https://ftp.wizarpos.com/barcodescan/app-cloudposscannerdemo-20231106.apk)
###
[hashtag](https://smartpossdk.gitbook.io/cloudpossdk/cloudpos-sdk/scanning-service-usage#quickly-launch-the-scan-application-in-q2-q3)
Quickly Launch the Scan Application in Q2/Q3
Physical Action: Double-click the power button or long press Volumn+.
This feature enables the swift launch of the scan application. Upon clicking, the system searches for all installed applications and launches the one with the scan intent-filter. If multiple applications exist, the system presents a list for users to choose from, initiating the selected application. The code for the scan intent-filter is as follows:
If no application in the system defines the scan intent-filter, pressing will not work. For instance, to use the scan button effectively, the application must define the scan intent-filter in its Android manifest file, with the category and action defined as follows:
###
[hashtag](https://smartpossdk.gitbook.io/cloudpossdk/cloudpos-sdk/scanning-service-usage#cloudpos-scan-service-in-q1-android-4.4)
CloudPOS Scan Service in Q1 Android 4.4
[CloudposScannerService-v3.12.28arrow-up-right](https://ftp.wizarpos.com/advanceSDK/CloudposScannerService-v3.12.28-r35144-q1_releasekey_forQ1android4.4.apk)
###
[hashtag](https://smartpossdk.gitbook.io/cloudpossdk/cloudpos-sdk/scanning-service-usage#faq)
FAQ
* How to not show the scan window?
Set window\_width=0 and window\_height=0 in ScanParameter.
Generally, physical scanner don't need show the scanner window.
[PreviousEMV Develop Specchevron-left](https://smartpossdk.gitbook.io/cloudpossdk/cloudpos-sdk/emv-develop-spec)
[NextCloudPOS SDK AARchevron-right](https://smartpossdk.gitbook.io/cloudpossdk/cloudpos-sdk/cloudpos-sdk-aar)
Last updated 1 day ago
* [Overview](https://smartpossdk.gitbook.io/cloudpossdk/cloudpos-sdk/scanning-service-usage#overview)
* [Document](https://smartpossdk.gitbook.io/cloudpossdk/cloudpos-sdk/scanning-service-usage#document)
* [Scan Barcode Testing Application](https://smartpossdk.gitbook.io/cloudpossdk/cloudpos-sdk/scanning-service-usage#scan-barcode-testing-application)
* [Quickly Launch the Scan Application in Q2/Q3](https://smartpossdk.gitbook.io/cloudpossdk/cloudpos-sdk/scanning-service-usage#quickly-launch-the-scan-application-in-q2-q3)
* [CloudPOS Scan Service in Q1 Android 4.4](https://smartpossdk.gitbook.io/cloudpossdk/cloudpos-sdk/scanning-service-usage#cloudpos-scan-service-in-q1-android-4.4)
* [FAQ](https://smartpossdk.gitbook.io/cloudpossdk/cloudpos-sdk/scanning-service-usage#faq)
Copy
Copy
---
# Retail Smart ECR User Guide | WizarPOS Catering & Retail Soloution User Guide
V1.2
[hashtag](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/smart-retail/retail-smart-ecr-user-guide#toc22979)
1\. Function overview
--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
WizarPOS Smart ECR retail app is a retail cashier system for Android big screen devices. It is used by cashiers in retail stores who use smart ECR machines to perform cashier operations on customers. The main functions provided by the system are as follows:
**1\. Goods**
Merchants upload various types of goods in the merchant portal and save all products in the product list. When customers shopping, the waiter scans the barcode of the goods to checkout.
**2\. Promotions**
Merchants can set up various types of marketing activities through the merchant portal, including discounts, full discounts, special offers, points malls, coupons for consumption and other activities, which can provide a better shopping experience.
**3\. Membership**
Each retail merchant can recommend the merchant's online store to the customer through links or QR code. Customers scan the QR code to register and become a member of the merchant. The staff can use the terminal to recharge the balance. The member's balance can be used at checkout. Members can receive coupons for consumption, which can be deducted when making purchases.
**4\. Payment**
Retail APP support cash, bank cards, membership cards, membership coupons and other payment methods.
**5\. Points**
Merchants can configure points redemption activities in the merchant portal, such as 100 points redeeming a bottle of Coke, 200 points redeeming a pack of snacks, etc. The waiter uses terminal to scan the customer's redemption code and redeem the product for the customer.
**6\. Chain stores**
If a merchant has multiple stores, it supports the chain store function. Customers can register as a member at any store under the merchant. The membership balance can be used across all stores. The membership coupons obtained through consumption can also be used at any store.
[hashtag](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/smart-retail/retail-smart-ecr-user-guide#toc143680710)
2\. Login
------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
Enter the merchant number, user name, and password and click Login to enter the homepage.
[hashtag](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/smart-retail/retail-smart-ecr-user-guide#toc143680711)
3\. Home
-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
The home page is the home page of the cashier, with a function bar at the top and various functions displayed on the left side of the function bar, such as selecting members, clearing the entire order, pending orders, and online store orders. On the right side are the product search function and operation panel (function aggregation bar), which displays all retail functions.
On this page, the cashier can use a scanner to scan the barcode of the product package and add the product to the product list. He or she can also select the product classification menu on the left to select the product to add to the product list. Of course, it also supports product search and purchase.
[hashtag](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/smart-retail/retail-smart-ecr-user-guide#toc143680712)
4\. Pending Order
--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
The cashier can temporarily suspend the items that are already in the pending order list, which is convenient for some customers who want to postpone the checkout, so that next customers can checkout first, and then select unchecked orders from the pending order list to perform checkout operations.
Click on the pending order to place the item on hold.
Click the left and right arrows under Actions to add items to your shopping cart and check out.
[hashtag](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/smart-retail/retail-smart-ecr-user-guide#toc143680713)
5\. Checkout
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
Click Checkout in the lower right corner to enter the checkout page. The payment amount, taxes, discounts and other payment information are displayed on the left side of the page. The right side is the payment method. Customers can choose different methods to pay, such as cash, bank card, membership card, etc.
On the home page, customers have several ways to identify themselves as members. First, customers can show their membership code QR code to the cashier, and the cashier can scan the QR code presented by the customer for identification. In addition, if necessary, the cashier can also manually enter the customer's membership code for binding. Once the binding is successful, the customer's membership information will be displayed in the upper left corner of the top.
At checkout, the system will display a membership card button, and customers can use their membership card balance to pay. In addition, the checkout function also supports the combination of different payment methods to pay multiple amounts, and coupons can also be used for deductions.
[hashtag](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/smart-retail/retail-smart-ecr-user-guide#toc143680714)
6\. Online Orders
--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
Click the online store order above the checkout counter to enter the online store order page. You can view orders to be shipped, shipped, pending payment, completed, and canceled. Orders are divided into door-to-door delivery and self-pickup. You can enter for order details. For self-pickup orders, customers can show the delivery code and then scan the code to quickly locate the order and proceed with delivery. For shipped orders, you can view details and print the order receipt repeatedly.
[hashtag](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/smart-retail/retail-smart-ecr-user-guide#toc143680715)
7\. Membership
-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
Click Member Query on the operation panel, enter the membership id or scan the membership QR code for member identification.
After the member is identified, enter the member management page. On this page, you can view the member's detailed information and recharge for the customer. In addition, members’ recharge records and consumption records can also be viewed on the page at any time.
Click Recharge, enter the recharge amount, and select the payment method to complete the recharge operation.
Open the recharge record to query the member's recharge record.
Open the consumption record to query the member's consumption record.
[hashtag](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/smart-retail/retail-smart-ecr-user-guide#toc143680716)
8\. Goods Management
-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
Click the Product and Category button in the operation panel to enter the product management page. Click the category to select its product, and the product information will be displayed on the right. Click the lower right corner to modify or delete the product. You can also add new products under this category.
[hashtag](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/smart-retail/retail-smart-ecr-user-guide#toc143680717)
9\. Sales Order
------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
Click on the sales order in the operation panel to view the sales orders of all transactions. Click on one of the orders to view the order details and support refund operations. If the customer pays in cash, the merchant will refund the cash. If the customer pays with a membership card, the payment amount will be Automatically returned to the customer's membership card.
[hashtag](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/smart-retail/retail-smart-ecr-user-guide#toc143680718)
10\. Stock-in and Stock-out
------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
Click Stock-in and Stock-out in the operation panel to enter the merchandise inbound and outbound page. The page has functions such as warehousing, warehousing, warehousing records, and warehousing records.
Click on the category of the product and select the product. You can fill in the quantity of the product on the right side. Click on the lower right corner to enter the warehouse. If the warehouse is successfully entered, click on the outbound warehouse to complete the outbound operation. You can also view the incoming and outgoing records.
[hashtag](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/smart-retail/retail-smart-ecr-user-guide#toc143680719)
11\. Inventory
-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
Click the inventory button in the operation panel to open the inventory page. Fill in the counted quantity according to the product, and display the profit and loss status.
[hashtag](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/smart-retail/retail-smart-ecr-user-guide#toc143680720)
12\. Business Report
-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
The business report can view the total sales amount of the day, full discounts and other information.
[hashtag](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/smart-retail/retail-smart-ecr-user-guide#toc143680721)
13\. Stock Query
-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
Inventory inquiry can check the current quantity of goods in stock.
[hashtag](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/smart-retail/retail-smart-ecr-user-guide#toc143680722)
14\. Points
--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
The points page displays the member's points redemption details, as well as the currently redeemed and pending items. The waiter can use the scanner function to scan the customer's point redemption QR code to redeem the items.
[hashtag](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/smart-retail/retail-smart-ecr-user-guide#toc143680723)
15\. Settings
----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
In the parameter setting page, you can configure printer parameters. Such as printer IP , print size, whether printing is enabled, etc.
[PreviousRetail Online Store User Guidechevron-left](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/smart-retail/retail-online-store-user-guide)
[NextManagementchevron-right](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/management)
Last updated 2 years ago
* [1\. Function overview](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/smart-retail/retail-smart-ecr-user-guide#toc22979)
* [2\. Login](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/smart-retail/retail-smart-ecr-user-guide#toc143680710)
* [3\. Home](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/smart-retail/retail-smart-ecr-user-guide#toc143680711)
* [4\. Pending Order](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/smart-retail/retail-smart-ecr-user-guide#toc143680712)
* [5\. Checkout](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/smart-retail/retail-smart-ecr-user-guide#toc143680713)
* [6\. Online Orders](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/smart-retail/retail-smart-ecr-user-guide#toc143680714)
* [7\. Membership](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/smart-retail/retail-smart-ecr-user-guide#toc143680715)
* [8\. Goods Management](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/smart-retail/retail-smart-ecr-user-guide#toc143680716)
* [9\. Sales Order](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/smart-retail/retail-smart-ecr-user-guide#toc143680717)
* [10\. Stock-in and Stock-out](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/smart-retail/retail-smart-ecr-user-guide#toc143680718)
* [11\. Inventory](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/smart-retail/retail-smart-ecr-user-guide#toc143680719)
* [12\. Business Report](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/smart-retail/retail-smart-ecr-user-guide#toc143680720)
* [13\. Stock Query](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/smart-retail/retail-smart-ecr-user-guide#toc143680721)
* [14\. Points](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/smart-retail/retail-smart-ecr-user-guide#toc143680722)
* [15\. Settings](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/smart-retail/retail-smart-ecr-user-guide#toc143680723)
---
# Manual for Maintenance Management Portal | WizarPOS Catering & Retail Soloution User Guide
[hashtag](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/management/manual-for-maintenance-management-portal#id-1-service-provider-portal)
**1** Service Provider Portal
-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
###
[hashtag](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/management/manual-for-maintenance-management-portal#toc26390)
1.1 Function Overview
Wizarpos service provider portal, mainly provides functions for service providers to manage merchants. It allows adding and modifying one or more merchants under this service provider. The merchant types supported are retail and catering. It is possible to view the transaction records of each merchant, as well as the terminal information and quantity bound to each merchant.
###
[hashtag](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/management/manual-for-maintenance-management-portal#toc5715)
1.2 Login
Enter the account password to log in to the backend. Before logging in, you can choose the language
###
[hashtag](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/management/manual-for-maintenance-management-portal#toc16686)
1.3 Merchant Management - Settlement Records
Click on Settlement Results to access the settlement records, where you can view the transaction data of all merchants under this service provider, including member transactions and bank card transactions
###
[hashtag](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/management/manual-for-maintenance-management-portal#toc24981)
###
[hashtag](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/management/manual-for-maintenance-management-portal#id-1.4-merchant-management-merchant-information-management)
1.4 Merchant Management - Merchant Information Management
Click on MerchantList to enter the merchant list, where you can add new merchants (retail or catering), search and edit merchant information, configure payment methods, set payment parameters, resend emails, view bound terminals, enable merchants, disable merchants, etc
Click "Add Merchant" to add a new merchant. After filling in the merchant information, complete the account opening process. The merchant will receive an account opening email and can log in to the merchant portal using the initial account and password to perform operations
Clicking on "more" allows you to configure payments, edit merchants, and manage terminals
Terminal Management Click on Payment Setting to configure the existing payment methods, whether to enable or disable online and offline
Clicking on Payment Setting allows you to configure payment parameters according to the actual payment integration needs. After configuration, you can proceed with actual payment transactions
You can make actual payments and transactions. Click "Add" to set up payment methods, transaction fees, and maximum transaction fees
Click on "Resend Email" to resend the email. If the customer forgets their password, clicking on "Resend Email" will send the new password to the email address provided during registration
Click to resend emai
Will send the new password to the email address filled in during registration. Click on "Terminal Manage" to view the terminal information bound to the merchant, and you can edit the terminal type and delete the terminal
###
[hashtag](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/management/manual-for-maintenance-management-portal#toc32108)
1.5 Merchant Management - Terminal Management
Clicking on Terminal Manage allows you to view terminal information for all merchants, and perform actions such as adding, editing, and deleting
Can edit terminal information
Clicking on "Add" allows you to add a new terminal for a specific merchant. The terminal can only be logged in and used after it is bound to the merchant
###
[hashtag](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/management/manual-for-maintenance-management-portal#id-1.6-agent-management)
1.6 Agent Management
Clicking on the Agent Manage page displays agents. Agents are subordinates of service providers and can onboard merchants
Click Add to add an agent, fill in the information, click the confirm button, and the agent will be created. The initial password will be sent to the entered email
Clicking on Payment Setting allows you to configure payment settings
You can configure the payment methods and commission rates for agents, with a maximum commission cap
###
[hashtag](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/management/manual-for-maintenance-management-portal#id-1.7-payment-methods)
1.7 Payment methods
Click on Payment Method to view and create payment methods
Click on Edit to view detailed configuration methods
Clicking on Add allows you to create a payment method
###
[hashtag](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/management/manual-for-maintenance-management-portal#id-1.8-service-fee)
1.8 Service Fee
Clicking on Handing Fee Details will allow you to view a summary of the fees
###
[hashtag](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/management/manual-for-maintenance-management-portal#id-1.9-service-fee-summary)
1.9 Service Fee Summary
Click Service Fee Summary
###
[hashtag](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/management/manual-for-maintenance-management-portal#toc21239)
1.10 System Settings - Role Settings
Click on Role Manage to enter and view the currently available roles. Currently, there is only one type of role, which is the employee role, and it allows for menu authorization
You can authorize the menu. Click on "Role resources" to edit the menu authorization. The checked menus will only be visible when logging into the system
###
[hashtag](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/management/manual-for-maintenance-management-portal#toc13971)
1.11 System Settings - User Management
Click on "User Manage" to enter user management. You can view all current account information, add new users, edit existing users, enable/disable accounts, and reset passwords
Click Add to create a new user
Click Edit to edit the user
Click Disable or Enable to activate or deactivate the user
Click on "Reset Password" to reset the user's login password
###
[hashtag](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/management/manual-for-maintenance-management-portal#id-1.12-merchant-onboarding-announcement)
**1.12** Merchant Onboarding Announcement
Click on "Merchant entry notice" to view the merchant entry announcement. This page displays the information that users need to know when applying for the free version of the POS machine
###
[hashtag](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/management/manual-for-maintenance-management-portal#id-1.13-parameter-setting)
**1.13** Parameter Setting
Clicking on Parameter Setting allows you to replace the icon in the top left corner of the portal
[hashtag](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/management/manual-for-maintenance-management-portal#toc183)
2 Operation and Maintenance Management Portal
-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
###
[hashtag](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/management/manual-for-maintenance-management-portal#toc7757)
2.1 Overview
Wizarpos operation and maintenance management portal is a backend system used by operation and maintenance personnel. It is mainly used to open service providers and then view all merchants under the service providers, as well as generated transaction data, order data, and member recharge and consumption data
###
[hashtag](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/management/manual-for-maintenance-management-portal#toc182)
2.2 Login
Enter your username and password on the login page, select the language, and log in to the system
###
[hashtag](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/management/manual-for-maintenance-management-portal#toc23150)
2.3 Data Overview
Login System After logging in, you will first enter the Dashboard page. Here, the data overview is displayed, showing the current number of merchants, number of members, daily transaction amount, and transaction amount chart data
You can view transaction data for merchants in the food and retail industry
###
[hashtag](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/management/manual-for-maintenance-management-portal#toc29471)
2.4 Service Provider Management
Click on Service Provider to enter the service provider list, where you can add, search, and modify service providers
Clicking on "Add" allows you to create a new service provider. After filling in the information, the service provider will be created. The email sent to the merchant when creating an account will be sent using the email provided by the service provider
###
[hashtag](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/management/manual-for-maintenance-management-portal#toc32113)
2.5 Role Management
Click on Role Manage to enter role management, which displays the current list of all roles. You can create and edit service providers, and authorize menus for service providers
Clicking on Add allows you to create roles. There are three types of roles here, corresponding to different menu permissions.
PTL-ADMIN is the merchant type, corresponding to the menu permissions of the retail and catering portals. Operations are used to set up retail and catering merchants, and determine which menus they can see
OPS-ADMIN is a service provider type, used for setting up which menus the service provider can see
SAAS-ADMIN is an operations and maintenance type used to set up which menus the operations and maintenance backend login account can see
###
[hashtag](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/management/manual-for-maintenance-management-portal#toc20347)
2.6 Transaction Records
Click on Trans List, operations and maintenance administrators can view the transaction records of all merchants
###
[hashtag](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/management/manual-for-maintenance-management-portal#toc31697)
2.7 Order Report
Clicking on "Order Report", the operations and maintenance administrator can view the number and amount of online and offline transactions generated by all merchants each day
###
[hashtag](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/management/manual-for-maintenance-management-portal#toc28449)
2.8 Membership Report
Clicking on the Membership Report, the operations and maintenance administrator can query all the members under all merchants, as well as the generated records of member recharge and consumption
Click on Sales Report to view member consumption records
[hashtag](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/management/manual-for-maintenance-management-portal#id-3-agent-portal)
3 Agent Portal
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
###
[hashtag](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/management/manual-for-maintenance-management-portal#id-3.1-overview)
3.1 Overview
Wizarpos agent portal, mainly provides functions for agents to manage merchants. It allows agents to add and modify merchants under their agency. The merchant types supported are retail and catering. Agents can view transaction records of each merchant, as well as the terminal information and quantity bound to each merchant
###
[hashtag](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/management/manual-for-maintenance-management-portal#id-3.2-login)
3.2 Login
Enter the account password to log in to the backend. Before logging in, you can choose the language
###
[hashtag](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/management/manual-for-maintenance-management-portal#id-3.3-merchant-management-settlement-records)
3.3 Merchant Management - Settlement Records
Click on Settlement Results to access the settlement records, where you can view all transaction data of merchant members and bank card transactions under this agent
###
[hashtag](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/management/manual-for-maintenance-management-portal#id-3.4-merchant-management-merchant-information-management)
3.4 Merchant Management - Merchant Information Management
Click on MerchantList to enter the merchant list, click on Add to add a new merchant (retail or catering), search and edit merchant information, resend emails, view bound terminals, enable/disable merchants, etc.
Click on Add to fill in the merchant information and complete the account opening. The merchant will receive an account opening email and can log in to the merchant portal with the initial account and password to perform operations
Click on "Resend Email" to resend the email. If the customer forgets their password, clicking on "Resend Email" will send the new password to the email address provided during registration
Clicking on Terminal Manage allows you to view the terminal information bound to the merchant, and you can edit the terminal type and delete the terminal
Click Disable to disable the merchant, click Enable to enable the merchant
###
[hashtag](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/management/manual-for-maintenance-management-portal#id-3.5-merchant-management-terminal-management)
3.5 Merchant Management - Terminal Management
Clicking on "Add" allows you to add a new terminal for a specific merchant. The terminal can only be logged in and used after it is bound to the merchant
###
[hashtag](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/management/manual-for-maintenance-management-portal#id-3.6-system-settings-user-management)
3.6 System Settings - User Management
Click on "User Manage" to enter user management. You can view all current account information, add new users, edit existing users, enable/disable accounts, and reset passwords
Click Add to add a new user
Click Disable or Enable to activate or deactivate the user
Click on Reset Password to reset the user's login password
[PreviousManagementchevron-left](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/management)
[NextManual for Catering Portalchevron-right](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/management/manual-for-catering-portal)
Last updated 9 months ago
* [1 Service Provider Portal](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/management/manual-for-maintenance-management-portal#id-1-service-provider-portal)
* [1.1 Function Overview](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/management/manual-for-maintenance-management-portal#toc26390)
* [1.2 Login](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/management/manual-for-maintenance-management-portal#toc5715)
* [1.3 Merchant Management - Settlement Records](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/management/manual-for-maintenance-management-portal#toc16686)
* [](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/management/manual-for-maintenance-management-portal#toc24981)
* [1.4 Merchant Management - Merchant Information Management](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/management/manual-for-maintenance-management-portal#id-1.4-merchant-management-merchant-information-management)
* [1.5 Merchant Management - Terminal Management](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/management/manual-for-maintenance-management-portal#toc32108)
* [1.6 Agent Management](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/management/manual-for-maintenance-management-portal#id-1.6-agent-management)
* [1.7 Payment methods](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/management/manual-for-maintenance-management-portal#id-1.7-payment-methods)
* [1.8 Service Fee](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/management/manual-for-maintenance-management-portal#id-1.8-service-fee)
* [1.9 Service Fee Summary](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/management/manual-for-maintenance-management-portal#id-1.9-service-fee-summary)
* [1.10 System Settings - Role Settings](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/management/manual-for-maintenance-management-portal#toc21239)
* [1.11 System Settings - User Management](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/management/manual-for-maintenance-management-portal#toc13971)
* [1.12 Merchant Onboarding Announcement](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/management/manual-for-maintenance-management-portal#id-1.12-merchant-onboarding-announcement)
* [1.13 Parameter Setting](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/management/manual-for-maintenance-management-portal#id-1.13-parameter-setting)
* [2 Operation and Maintenance Management Portal](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/management/manual-for-maintenance-management-portal#toc183)
* [2.1 Overview](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/management/manual-for-maintenance-management-portal#toc7757)
* [2.2 Login](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/management/manual-for-maintenance-management-portal#toc182)
* [2.3 Data Overview](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/management/manual-for-maintenance-management-portal#toc23150)
* [2.4 Service Provider Management](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/management/manual-for-maintenance-management-portal#toc29471)
* [2.5 Role Management](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/management/manual-for-maintenance-management-portal#toc32113)
* [2.6 Transaction Records](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/management/manual-for-maintenance-management-portal#toc20347)
* [2.7 Order Report](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/management/manual-for-maintenance-management-portal#toc31697)
* [2.8 Membership Report](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/management/manual-for-maintenance-management-portal#toc28449)
* [3 Agent Portal](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/management/manual-for-maintenance-management-portal#id-3-agent-portal)
* [3.1 Overview](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/management/manual-for-maintenance-management-portal#id-3.1-overview)
* [3.2 Login](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/management/manual-for-maintenance-management-portal#id-3.2-login)
* [3.3 Merchant Management - Settlement Records](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/management/manual-for-maintenance-management-portal#id-3.3-merchant-management-settlement-records)
* [3.4 Merchant Management - Merchant Information Management](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/management/manual-for-maintenance-management-portal#id-3.4-merchant-management-merchant-information-management)
* [3.5 Merchant Management - Terminal Management](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/management/manual-for-maintenance-management-portal#id-3.5-merchant-management-terminal-management)
* [3.6 System Settings - User Management](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/management/manual-for-maintenance-management-portal#id-3.6-system-settings-user-management)
---
# Manual for Catering Portal | WizarPOS Catering & Retail Soloution User Guide
[hashtag](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/management/manual-for-catering-portal#id-1-overview-of-functions)
1\. Overview of Functions
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
The Wizarpos Catering Portal is a web-based backend management system. Restaurant businesses use this system for various editing and settings related to dishes, membership, and marketing, as well as viewing sales data. The system provides the following main functions:
###
[hashtag](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/management/manual-for-catering-portal#id-1-dish-management)
1\. Dish Management
Merchants upload various types of dishes in the backend, such as hot dishes, cold dishes, Western cuisine, dim sum, and snacks. Dishes are customized by specifications, taste, preparation method, and additional ingredients to meet different customer ordering needs. Both waitstaff and customers can see the corresponding dishes when using the ordering system.
###
[hashtag](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/management/manual-for-catering-portal#id-2-marketing-activities)
2\. Marketing Activities
Merchants can set up various online and offline marketing activities through the backend, such as discounts, full reductions, special prices, point malls, and consumption vouchers, providing diners with diverse dining experiences.
###
[hashtag](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/management/manual-for-catering-portal#id-3-table-management)
3\. Table Management
Merchants can create various table categories in the backend, such as hall or private room, and then create various tables under these categories.
###
[hashtag](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/management/manual-for-catering-portal#id-4-sales-management)
4\. Sales Management
Merchants can view various business reports, sales documents, consumption statistics, refund statistics, and tip statistics in the backend.
###
[hashtag](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/management/manual-for-catering-portal#id-5-points-mall)
5\. Points Mall
Merchants can configure activities for exchanging goods with points, such as exchanging 100 points for a bottle of cola or 500 points for a dish, increasing user consumption enthusiasm and interest. Waitstaff use handheld devices to scan customer redemption codes to exchange goods for customers.
###
[hashtag](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/management/manual-for-catering-portal#id-6-chain-stores)
6\. Chain Stores
If a merchant has multiple stores, the system supports chain store functionality. Customers can register as members at any store, and the member balance is universally applicable across stores. Coupons obtained from consumption can also be used at any store.
[hashtag](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/management/manual-for-catering-portal#id-2-login)
2\. Login
-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
Open the merchant catering management backend (hereinafter referred to as the backend). For the first login, merchants must use the initial account and password provided by the system to log in. The system supports multi-language login, which can be switched independently.
The system is divided into official and trial versions. Users can click Demo Tour to enter the trial version interface without logging in. In the trial version, merchants cannot perform add, delete, or modify operations, only view data. After logging into the trial version, the top right of the interface displays the current status as Demo merchants.
Note: Unless otherwise stated, this document defaults to the official version interface.
The official version interface is as follows:
2.1 Homepage
After successfully logging in, users are redirected to the homepage. The homepage displays the store's operating data, such as the number and amount of orders for the current week and month. Below, line or bar charts display data for the week's order count, dish sales, and monthly order count and dish sales.
Password modification and logout: Users can click the account in the top right corner to change the password or log out.
The process is as follows: Enter the old password and the new password twice, click confirm, and the account modification is complete.
[hashtag](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/management/manual-for-catering-portal#id-3-transaction-records)
3\. Transaction Records
-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
###
[hashtag](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/management/manual-for-catering-portal#id-3-1-transaction-records)
3.1 Transaction Records
By clicking the Trans List menu, users can view all transaction records of the merchant, searchable by time range, payment type, payment method, etc.
Transaction records include comprehensive and detailed payment information, including device terminal, table number, payment type, and payment amount.
###
[hashtag](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/management/manual-for-catering-portal#id-3-2-transaction-summary)
3.2 Transaction Summary
By clicking the Trans Report menu, users can view the merchant's transaction data summary, searchable by time range.
The transaction summary includes online and offline orders, payment methods, order payment count, and payment amount.
Based on the time range, users can query the transaction amount summary for various payment methods within the period.
###
[hashtag](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/management/manual-for-catering-portal#id-3-3-settlement-records)
3.3 Settlement Records
By clicking the Billing Records menu, users can view the merchant's settlement records.
Merchant settlement refers to the fees the merchant needs to pay to the payment channel providers. The actual settlement amount is displayed based on the connected payment channel and is usually settled to the merchant through a T+1 method.
[hashtag](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/management/manual-for-catering-portal#id-4-dish-management)
4\. Dish Management
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
###
[hashtag](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/management/manual-for-catering-portal#id-4-1-dish-categories)
4.1 Dish Categories
By clicking Dishes Category, users enter the dish category menu, where merchants can create dish categories, supporting up to two levels.
By clicking Add, merchants can input category names and codes, supporting enabling and disabling categories for in-store ordering (POS) and H5 ordering (consumer end).
###
[hashtag](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/management/manual-for-catering-portal#id-4-2-dish-details)
4.2 Dish Details
By clicking Dishes Details, users enter the dish details menu, where all dishes are created.
Dishes support image uploads, visible to both merchants and customers. Additionally, merchants can set dish specifications, tastes, additional ingredients, and preparation methods. All dishes can be exported as an xls document.
Exported dish tables are as follows:
Creating a dish: Click Add, input the dish name, select category, unit, and choose dish specifications and other parameters to create a dish.
Select specifications, taste, additional ingredients, preparation methods, and other methods to create a complete dish. The specific selected parameters need to be created in the dish properties menu in advance.
###
[hashtag](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/management/manual-for-catering-portal#id-4-3-dish-properties)
4.3 Dish Properties
By clicking Food Properties, users enter the dish properties menu, where merchants can create basic properties of dishes.
These include settings for dish specifications, tastes, additional ingredients, and preparation methods, which merchants can create independently.
In the "spec" attribute, merchants can set the portion size, such as large, medium, small, or other specifications. Different specifications correspond to different dish prices.
By clicking the Taste attribute, merchants can set the dish taste.
By clicking Add, enter the taste name, and merchants will cater according to the selected taste, which does not involve dish pricing.
Add-on allows users to view and add additional ingredients or side dishes, which can be priced separately. For example, if a customer orders a steak and chooses side dishes like eggs and ham, these are the side dishes, which support multiple selections.
By clicking Add, create side dish names and prices.
By clicking Cooking Method, merchants can create preparation methods for dishes, such as steaming, frying, boiling, etc., which do not affect dish prices.
By clicking Add Method, create a method name for dishes.
###
[hashtag](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/management/manual-for-catering-portal#id-4-4-combo-meals)
4.4 Combo Meals
By clicking Combo Meal, users enter the combo meal page. Combo meals are a sales method for combining dishes.
By clicking Add, create a combo meal by entering the dish name, selecting category and description.
Choose different dishes, enter quantity, price, packaging fee, support image upload, click confirm button, and the combo is created.
[hashtag](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/management/manual-for-catering-portal#id-5-sales-management)
5\. Sales Management
-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
###
[hashtag](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/management/manual-for-catering-portal#id-5-1-business-reports)
5.1 Business Reports
By clicking Total Report, users can query transaction data summaries for the merchant within a specific time period, querying total member recharge, total discounts, and full refunds.
###
[hashtag](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/management/manual-for-catering-portal#id-5-2-sales-documents)
5.2 Sales Documents
By clicking Sales Report, users can view the merchant's sales documents. Merchants can query based on sales orders, types, and time ranges, supporting report export operations.
###
[hashtag](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/management/manual-for-catering-portal#id-5-3-order-source)
5.3 Order Source
By clicking Order Report, users can view the source statistics of the merchant's sales documents. Sources are divided into dine-in and online ordering, showing transaction amounts, quantities, and transaction methods.
###
[hashtag](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/management/manual-for-catering-portal#id-5-4-sales-statistics)
5.4 Sales Statistics
By clicking Dish Report, users enter the sales statistics menu, displaying the sales quantity and sales amount summary of dishes.
###
[hashtag](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/management/manual-for-catering-portal#id-5-5-refund-statistics)
5.5 Refund Statistics
By clicking Refund Report, users enter the refund statistics menu. Merchants can statistically analyze by time range, refund name, quantity, and amount.
###
[hashtag](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/management/manual-for-catering-portal#id-5-6-tip-statistics)
5.6 Tip Statistics
By clicking Tip Report, users enter the tip statistics menu. Merchants can query the total amount of tips and details for waitstaff based on the time range.
By clicking Details, query tip amount details and associated sales order numbers.
[hashtag](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/management/manual-for-catering-portal#id-6-table-management)
6\. Table Management
-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
By clicking Table Manager, users enter the table management menu, allowing merchants to create all tables in the store. If tables are categorized, such as hall or private room, categories can also be created.
Tables can be bound to a waiter, and table QR codes can be exported. Users scan the table QR code to order when they arrive.
By clicking Table QR Code, download the table QR code, supporting bulk export of all table QR codes.
[hashtag](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/management/manual-for-catering-portal#id-7-membership-management)
7\. Membership Management
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
###
[hashtag](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/management/manual-for-catering-portal#id-7-1-member-information)
7.1 Member Information
By clicking Membership, users can query all registered member information under the merchant (member registration requires users to scan the merchant or table QR code). Members' email, balance, details, etc., can be viewed, and merchants can freeze or unfreeze members.
By clicking Detail, view detailed member information.
###
[hashtag](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/management/manual-for-catering-portal#id-7-2-member-transaction-records)
7.2 Member Transaction Records
By clicking Member Trans, merchants can view members' recharge records, consumption records, and points records.
By clicking Sales Report, view member consumption records.
By clicking Points Report, view member points records.
[hashtag](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/management/manual-for-catering-portal#id-8-marketing-center)
8\. Marketing Center
-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
###
[hashtag](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/management/manual-for-catering-portal#id-8-1-marketing-activities)
8.1 Marketing Activities
By clicking Promotion, merchants can create different marketing activities. The same marketing activity cannot be created twice simultaneously.
By clicking Details, view the details of marketing activities.
By clicking Create Marketing Activity, create activities such as full reductions, special offers, discounts, points mall, consumption coupons, combo meals, earn points for consumption, member recharge, and member registration activities.
By clicking Full Discount, create full reduction activities.
By clicking Special Offer, create special price activities, selecting one or more products for settings.
After selecting the products for special pricing, enter the special price amount to complete the setup.
By clicking Discount, create discount activities, applying discounts according to the set amount. For example, if spending 100 earns a 10% discount, then it's a 90% price.
By clicking Points Mall, create points mall activities, allowing points to be exchanged for goods.
Select products available for exchange, enter the points required for exchange, the total number of products available, and the limit per user.
By clicking Member Consumption Coupon, create consumption coupon activities.
Enter the specific amount, select the coupon specification template to be given, and click confirm to complete the setup.
By clicking Earn points for members spending, create activities where members earn points for consumption. Enter a name, description, select time, and set the specified amount to earn specified points. Customers can exchange products in the points mall.
Member recharge activities can be created by date, offering coupons, balance, and points.
Member registration activities allow first-time registered members to receive points and membership coupons.
###
[hashtag](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/management/manual-for-catering-portal#id-8-2-full-reduction-and-discount-statistics)
8.2 Full Reduction and Discount Statistics
By clicking Promotion Report, view marketing activity statistics. Merchants can view full reduction and discount statistics.
###
[hashtag](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/management/manual-for-catering-portal#id-8-3-create-coupon-templates)
8.3 Create Coupon Templates
By clicking Tickets, merchants can create coupon templates. The coupons given in member consumption coupon activities are created here.
By clicking Add, create a new coupon template. After completing the required information, click confirm to complete the new template.
By clicking Detail, view the coupon template details, and click Delete to remove.
[hashtag](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/management/manual-for-catering-portal#id-9-system-settings)
9\. System Settings
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
###
[hashtag](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/management/manual-for-catering-portal#id-9-1-store-information)
9.1 Store Information
By clicking Merchant Info, view detailed information about the merchant.
By clicking Edit, support editing merchant information.
###
[hashtag](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/management/manual-for-catering-portal#id-9-2-account-management)
9.2 Account Management
By clicking Account Manage, view and create operators and managers for the merchant. The manager is mainly for backend management, while operators mainly operate handheld POS terminals but can also log into the backend to view data. Permissions can be authorized by the administrator.
By clicking Edit, view and modify account information.
Administrators can also click Terminal Setting in the top right corner of the page to set a security password, which is used for secure verification during refund transactions at store terminals.
###
[hashtag](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/management/manual-for-catering-portal#id-9-3-authorization-management)
9.3 Authorization Management
By clicking Role Manage, enter authorization management. Administrators can set role authorizations for managers and operators.
Based on the selected menus, set menus as visible or not.
###
[hashtag](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/management/manual-for-catering-portal#id-9-4-parameter-configuration)
9.4 Parameter Configuration
By clicking Parameter Setting, configure the H5 ordering program's page settings, advertisement carousel, merchant icon and homepage image, recommended dishes, large screen carousel, and custom order status.
By clicking Network print settings, configure the kitchen slip printer used in the restaurant. When a waiter or user places an order, the dish slip will be notified to the kitchen printer via the network, and the printer will print the kitchen slip, allowing chefs to prepare dishes according to it.
By clicking Other pay setting, create other payment methods used during POS checkout.
By clicking Large screen rotating image settings, create carousel images for the large screen machine. The large screen is a device used in stores for user ordering, allowing users to place orders on the large screen.
Large screen carousel, set the D22 large screen terminal, carousel images.
Custom order status allows custom takeaway order statuses.
###
[hashtag](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/management/manual-for-catering-portal#id-9-5-delivery-settings)
9.5 Delivery Settings
By clicking Pickup Setting, set the merchant's takeaway pickup point. Users can order through the H5 merchant store and choose in-store pickup.
Merchants can create pickup point information, filling in the pickup point name and address information, etc.
[PreviousManual for Maintenance Management Portalchevron-left](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/management/manual-for-maintenance-management-portal)
Last updated 9 months ago
* [1\. Overview of Functions](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/management/manual-for-catering-portal#id-1-overview-of-functions)
* [1\. Dish Management](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/management/manual-for-catering-portal#id-1-dish-management)
* [2\. Marketing Activities](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/management/manual-for-catering-portal#id-2-marketing-activities)
* [3\. Table Management](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/management/manual-for-catering-portal#id-3-table-management)
* [4\. Sales Management](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/management/manual-for-catering-portal#id-4-sales-management)
* [5\. Points Mall](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/management/manual-for-catering-portal#id-5-points-mall)
* [6\. Chain Stores](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/management/manual-for-catering-portal#id-6-chain-stores)
* [2\. Login](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/management/manual-for-catering-portal#id-2-login)
* [3\. Transaction Records](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/management/manual-for-catering-portal#id-3-transaction-records)
* [3.1 Transaction Records](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/management/manual-for-catering-portal#id-3-1-transaction-records)
* [3.2 Transaction Summary](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/management/manual-for-catering-portal#id-3-2-transaction-summary)
* [3.3 Settlement Records](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/management/manual-for-catering-portal#id-3-3-settlement-records)
* [4\. Dish Management](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/management/manual-for-catering-portal#id-4-dish-management)
* [4.1 Dish Categories](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/management/manual-for-catering-portal#id-4-1-dish-categories)
* [4.2 Dish Details](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/management/manual-for-catering-portal#id-4-2-dish-details)
* [4.3 Dish Properties](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/management/manual-for-catering-portal#id-4-3-dish-properties)
* [4.4 Combo Meals](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/management/manual-for-catering-portal#id-4-4-combo-meals)
* [5\. Sales Management](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/management/manual-for-catering-portal#id-5-sales-management)
* [5.1 Business Reports](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/management/manual-for-catering-portal#id-5-1-business-reports)
* [5.2 Sales Documents](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/management/manual-for-catering-portal#id-5-2-sales-documents)
* [5.3 Order Source](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/management/manual-for-catering-portal#id-5-3-order-source)
* [5.4 Sales Statistics](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/management/manual-for-catering-portal#id-5-4-sales-statistics)
* [5.5 Refund Statistics](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/management/manual-for-catering-portal#id-5-5-refund-statistics)
* [5.6 Tip Statistics](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/management/manual-for-catering-portal#id-5-6-tip-statistics)
* [6\. Table Management](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/management/manual-for-catering-portal#id-6-table-management)
* [7\. Membership Management](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/management/manual-for-catering-portal#id-7-membership-management)
* [7.1 Member Information](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/management/manual-for-catering-portal#id-7-1-member-information)
* [7.2 Member Transaction Records](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/management/manual-for-catering-portal#id-7-2-member-transaction-records)
* [8\. Marketing Center](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/management/manual-for-catering-portal#id-8-marketing-center)
* [8.1 Marketing Activities](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/management/manual-for-catering-portal#id-8-1-marketing-activities)
* [8.2 Full Reduction and Discount Statistics](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/management/manual-for-catering-portal#id-8-2-full-reduction-and-discount-statistics)
* [8.3 Create Coupon Templates](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/management/manual-for-catering-portal#id-8-3-create-coupon-templates)
* [9\. System Settings](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/management/manual-for-catering-portal#id-9-system-settings)
* [9.1 Store Information](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/management/manual-for-catering-portal#id-9-1-store-information)
* [9.2 Account Management](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/management/manual-for-catering-portal#id-9-2-account-management)
* [9.3 Authorization Management](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/management/manual-for-catering-portal#id-9-3-authorization-management)
* [9.4 Parameter Configuration](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/management/manual-for-catering-portal#id-9-4-parameter-configuration)
* [9.5 Delivery Settings](https://smartpossdk.gitbook.io/wizarpos-catering-and-retail-soloution-user-guide/product-user-guides/management/manual-for-catering-portal#id-9-5-delivery-settings)
---
# MDB Communication Protocal | CloudPOS SDK
###
[hashtag](https://smartpossdk.gitbook.io/cloudpossdk/cloudpos-sdk/mdb-communication-protocal#introduction)
Introduction
This manual describes the serial communication protocol between Q3 Pos and MDB Interface Board, which will be short as “MIB” in follow content.
The basic baud rate of serial port is set as 115200
As the Q3 POS could be receive command from MIB as a slave, and also could send command to MIB as a master (e.g., send “begin session” command to inform the MDB VMC it’s ready for pay), a mode byte was added in serial frame to show if a command is slave response or a master request.
The request command always anticipates a response command except the checksum is wrong, or the incorrect serial format, in another word, the slave will use silence as a NAK. **Please refer to the** [**documentation** arrow-up-right](https://ftp.wizarpos.com/advanceSDK/MDB_interface_board_serial_protocol_20241226.pdf)
**for specific commands and details.**
###
[hashtag](https://smartpossdk.gitbook.io/cloudpossdk/cloudpos-sdk/mdb-communication-protocal#serial-protocol-packet-definition)
Serial Protocol Packet Definition
####
[hashtag](https://smartpossdk.gitbook.io/cloudpossdk/cloudpos-sdk/mdb-communication-protocal#serial-port-parameters)
Serial Port Parameters
* Baud rate: 115200
* Data format: 8 bits, 1 stop bit, no parity
####
[hashtag](https://smartpossdk.gitbook.io/cloudpossdk/cloudpos-sdk/mdb-communication-protocal#packet-format)
Packet Format
* Start code: size 1 byte, always be 0x09
* Length: size 1 byte, the number bytes of mode, data, and checksum.
* Mode: size 1 byte, 0x00 means a request packet, 0x01 means a response packet, other value is prohibited.
* Data: size n bytes, The data could be raw MDB commands, such as SETUP, VEND. Or the MIB control commands, such as GET VERSION, SET PARAMETER.
* Checksum: size 1 byte, using LRC algorithm, input data were "mode, data"
* End code: size 1 byte, always be 0x0D.
###
[hashtag](https://smartpossdk.gitbook.io/cloudpossdk/cloudpos-sdk/mdb-communication-protocal#specifics)
Specifics
####
[hashtag](https://smartpossdk.gitbook.io/cloudpossdk/cloudpos-sdk/mdb-communication-protocal#mdb-forwarding-mechanism)
MDB Forwarding Mechanism
When the MIB receive the VMC request, it removes the MDB mode bit, fill into serial packet data area, and transmit to serial port. In the opposite direction, the MIB receive the response, it unwraps the packet, and adding mode bit to the tail bytes, sending to the VMC, wait for the acknowledge.MIB will forward all the MDB cashless device commands (MDB spec section 7), except VMC request Poll.
Example: RESET
1. _VMC -> MIB:_ 0x110 0x10
2. _MIB -> Q3V:_ 0x09 0x04 0x00 0x10 0x10 0xE0 0x0D
3. Q3V _-> MIB:_ 0x09 0x04 0x01 0x00 0x00 0xFF 0x0D
4. _MIB -> VMC:_ 0x00 0x100
5. _VMC -> MIB : 0x00_
####
[hashtag](https://smartpossdk.gitbook.io/cloudpossdk/cloudpos-sdk/mdb-communication-protocal#application-notes)
Application Notes
* Focus on steps 2 and 3 in the MDB Forwarding Mechanism.
* The application handles all cashless commands except POLL.
* The cashless reader initiates a begin session command to notify the VMC when ready for a transaction.
* MDB raw data includes its checksum byte, distinct from the serial frame checksum.
###
[hashtag](https://smartpossdk.gitbook.io/cloudpossdk/cloudpos-sdk/mdb-communication-protocal#a-typical-mdb-transaction-flow)
A Typical MDB Transaction Flow
###
[hashtag](https://smartpossdk.gitbook.io/cloudpossdk/cloudpos-sdk/mdb-communication-protocal#protocol-command-definition)
Protocol Command Definition
circle-info
Please refer to the [documentation arrow-up-right](https://ftp.wizarpos.com/advanceSDK/MDB_interface_board_serial_protocol_20241226.pdf)
for specific commands and details.
####
[hashtag](https://smartpossdk.gitbook.io/cloudpossdk/cloudpos-sdk/mdb-communication-protocal#common-mdb-forwarding-command)
Common MDB Forwarding Command
This command forwards raw MDB commands (including MDB CHK), with the MDB mode bit removed.
Request Packet:
Mode
Data
Request 00H
VMC Request Command
(Reset,Setup,Reader,Expansion,Vend)
Response Packet:
Mode
Data
Response 01H
Peripheral Response
Example: MIB -> Q3V 09 04 00 10 10 E0 0D
Q3V -> MIB 09 04 01 00 00 FF 0D.
####
[hashtag](https://smartpossdk.gitbook.io/cloudpossdk/cloudpos-sdk/mdb-communication-protocal#begin-session-command)
Begin Session Command
When the application is ready for a transaction, it issues a begin session command to inform the VMC master. This marks the beginning of a transaction. Balance amount is 2 bytes; if balance does not exist, fill with 0xFF. This command follows MDB spec definition but is initiated by the app.
Request Packet:
Mode
Data
Request 00H
Begin Session (03H) + Funds Available + MDB Checksum
Response Packet:
Mode
Data
Response 01H
ACK 00H
Example: Q3V -> MIB 09 06 00 03 00 64 67 32 0d
MIB -> Q3V 09 03 01 00 ff 0d
####
[hashtag](https://smartpossdk.gitbook.io/cloudpossdk/cloudpos-sdk/mdb-communication-protocal#session-cancel-request-0x04)
Session Cancel Request(0x04)
The application can end a payment session by issuing a session cancel request command. The POS acts as the master during this command.
Request Packet:
Mode
Data
Request 00H
Cancel Session Req(04H) + Funds Available + Checksum
Response Packet:
Mode
Data
Response 01H
ACK 00H
###
[hashtag](https://smartpossdk.gitbook.io/cloudpossdk/cloudpos-sdk/mdb-communication-protocal#demo)
Demo
[Source Code for Terminal Apparrow-up-right](https://github.com/SmartPOSSamples/MDBTest.git)
[APKarrow-up-right](https://ftp.wizarpos.com/advanceSDK/MDBTransaction-3.2.9-release.apk)
###
[hashtag](https://smartpossdk.gitbook.io/cloudpossdk/cloudpos-sdk/mdb-communication-protocal#testing)
Testing
####
[hashtag](https://smartpossdk.gitbook.io/cloudpossdk/cloudpos-sdk/mdb-communication-protocal#test-between-terminal-and-vmc)
Test between terminal and VMC
* Please get above Demo APK, install it to terminal.
_Click the three horizontal lines icon button in the upper left corner to enter the setting interface. Set the balance(only for level 2), factor, decimal, level(2 or 3), and always aidl(only for level 3). Click the MDB Start button to start the communication test._
* Connect the terminal to VMC through by the MDB port of the terminal.
* Start the testing.
* [Testing Video: Connecting to a PC and Running the MDB Testarrow-up-right](https://ftp.wizarpos.com/techsupport/ticket/mdbtestconnectpc.mp4)
.
* [Testing Video: Connecting to a Coffee Machinearrow-up-right](https://ftp.wizarpos.com/techsupport/ticket/connectcoffemachine.mp4)
.
* [Testing Video: Connecting to an MDB Boardarrow-up-right](https://ftp.wizarpos.com/VideoIntroduce/mdbconnecttoVMCtesting.mp4)
.
####
[hashtag](https://smartpossdk.gitbook.io/cloudpossdk/cloudpos-sdk/mdb-communication-protocal#test-between-pc-simulator-and-terminal)
Test between PC simulator and terminal
There're two types of MDB RS232 box, please confirm which one are you testing:
[Testing Guide for blue MDB232 boxarrow-up-right](https://ftp.wizarpos.com/advanceSDK/mdb/blueboxtestMDB.zip)
* [MDB for coffee demo APKarrow-up-right](https://ftp.wizarpos.com/advanceSDK/mdb/bluebox/MDBForCoffeeDemo-sign-wrf.apk)
* [MDB for coffee demo usagearrow-up-right](https://ftp.wizarpos.com/advanceSDK/mdb/bluebox/MDBForCoffeeDemousage20220725.wps)
* [EXE application in PCarrow-up-right](https://ftp.wizarpos.com/advanceSDK/mdb/bluebox/Q3V-test.exe)
[Testing Guide for black MDB-RS232 boxarrow-up-right](https://ftp.wizarpos.com/advanceSDK/mdb/blackboxtestMDB.zip)
* [APK for testingarrow-up-right](https://ftp.wizarpos.com/advanceSDK/mdb/MDBTest-1.0.30-release-SHA256-v1v2-signed.apk)
* [Usage for testingarrow-up-right](https://ftp.wizarpos.com/advanceSDK/mdb/blackbox/Emulatortestingmethod.docx)
* [Vedio for testingarrow-up-right](https://ftp.wizarpos.com/advanceSDK/mdb/blackbox/df74750f2d06b25b470fa795e8a4fff8.mp4)
* [EXE application in PCarrow-up-right](https://ftp.wizarpos.com/advanceSDK/mdb/blackbox/MDB_RS232_Software.exe)
* [MDB-RS232 Quick Startarrow-up-right](https://ftp.wizarpos.com/advanceSDK/mdb/MDB_RS232_Quick_Start.pdf)
[PreviousError codechevron-left](https://smartpossdk.gitbook.io/cloudpossdk/cloudpos-sdk/error-code)
[NextPOS\_Specschevron-right](https://smartpossdk.gitbook.io/cloudpossdk/pos_specs)
Last updated 7 days ago
* [Introduction](https://smartpossdk.gitbook.io/cloudpossdk/cloudpos-sdk/mdb-communication-protocal#introduction)
* [Serial Protocol Packet Definition](https://smartpossdk.gitbook.io/cloudpossdk/cloudpos-sdk/mdb-communication-protocal#serial-protocol-packet-definition)
* [Specifics](https://smartpossdk.gitbook.io/cloudpossdk/cloudpos-sdk/mdb-communication-protocal#specifics)
* [A Typical MDB Transaction Flow](https://smartpossdk.gitbook.io/cloudpossdk/cloudpos-sdk/mdb-communication-protocal#a-typical-mdb-transaction-flow)
* [Protocol Command Definition](https://smartpossdk.gitbook.io/cloudpossdk/cloudpos-sdk/mdb-communication-protocal#protocol-command-definition)
* [Demo](https://smartpossdk.gitbook.io/cloudpossdk/cloudpos-sdk/mdb-communication-protocal#demo)
* [Testing](https://smartpossdk.gitbook.io/cloudpossdk/cloudpos-sdk/mdb-communication-protocal#testing)
---
# CloudPOS SDK AAR | CloudPOS SDK
###
[hashtag](https://smartpossdk.gitbook.io/cloudpossdk/cloudpos-sdk/cloudpos-sdk-aar#overview)
Overview
Welcome to the CloudPOS SDK AAR documentation! This guide provides information on the CloudPOS SDK AAR (Android Archive) for developers for the SmartPOS. The SDK enables seamless integration of CloudPOS functionalities into your Android application.
###
[hashtag](https://smartpossdk.gitbook.io/cloudpossdk/cloudpos-sdk/cloudpos-sdk-aar#getting-started)
Getting Started
To ensure optimal performance and compatibility, it is essential to use the latest CloudPOS SDK AAR version. The table below lists recent releases, including download links and release dates:
Version
Download
Release Time
1.7.7.18
[CloudPOS SDK AARarrow-up-right](https://ftp.wizarpos.com/device/java/cloudpossdkV1.7.7.18_Standard.aar)
2026-01-12
1.7.7.13
[CloudPOS SDK AARarrow-up-right](https://ftp.wizarpos.com/device/java/cloudpossdkV1.7.7.13_Standard.aar)
2025-12-23
1.7.7.7
[CloudPOS SDK AARarrow-up-right](https://ftp.wizarpos.com/device/java/cloudpossdkV1.7.7.7_Standard.aar)
2025-11-19
1.7.6.9
[CloudPOS SDK AARarrow-up-right](https://ftp.wizarpos.com/device/java/cloudpossdkV1.7.6.9_Standard.aar)
2025-10-21
1.7.6.6
[CloudPOS SDK AAR arrow-up-right](https://ftp.wizarpos.com/device/java/cloudpossdkV1.7.6.6_Standard.aar)
2025-09-29
1.7.5.1
[CloudPOS SDK AARarrow-up-right](https://ftp.wizarpos.com/device/java/cloudpossdkV1.7.5.1_Standard.aar)
2025-08-07
1.7.4.16
[CloudPOS SDK AARarrow-up-right](https://ftp.wizarpos.com/device/java/cloudpossdkV1.7.4.16_Standard.aar)
2025-07-28
1.7.4.7
[CloudPOS SDK AAR arrow-up-right](https://ftp.wizarpos.com/device/java/cloudpossdkV1.7.4.7_Standard.aar)
2025-06-26
1.7.4.2
[CloudPOS SDK AARarrow-up-right](https://ftp.wizarpos.com/device/java/cloudpossdkV1.7.4.2_Standard.aar)
2025-05-19
1.7.3.9
[CloudPOS SDK AARarrow-up-right](https://ftp.wizarpos.com/device/java/cloudpossdkV1.7.3.9_Standard.aar)
2025-05-15
1.7.2.2
[CloudPOS SDK AARarrow-up-right](https://ftp.wizarpos.com/device/java/cloudpossdkV1.7.2.2_Standard.aar)
2025-03-24
1.7.1.5
[CloudPOS SDK AARarrow-up-right](https://ftp.wizarpos.com/device/java/cloudpossdkV1.7.1.5_Standard.aar)
2025-02-26
1.6.5.0
[CloudPOS SDK AARarrow-up-right](https://ftp.wizarpos.com/device/java/cloudpossdkV1.6.5.0_Standard.aar)
2024-11-18
1.6.4.4
[CloudPOS SDK AARarrow-up-right](https://ftp.wizarpos.com/device/java/cloudpossdkV1.6.4.4_Standard.aar)
2024-09-29
1.6.4.2
[CloudPOS SDK AARarrow-up-right](https://ftp.wizarpos.com/device/java/cloudpossdkV1.6.4.2_Standard.aar)
2024-09-09
1.6.3.9
[CloudPOS SDK AARarrow-up-right](https://ftp.wizarpos.com/device/java/cloudpossdkV1.6.3.9_Standard.aar)
2024-08-22
1.6.3.7
[CloudPOS SDK AARarrow-up-right](https://ftp.wizarpos.com/device/java/cloudpossdkV1.6.3.7_Standard.aar)
2024-08-12
1.6.3.6
[CloudPOS SDK AARarrow-up-right](https://ftp.wizarpos.com/device/java/cloudpossdkV1.6.3.6_Standard.aar)
2024-07-22
1.6.3.4
[CloudPOS SDK AAR arrow-up-right](https://ftp.wizarpos.com/device/java/cloudpossdkV1.6.3.4_Standard.aar)
2024-07-09
1.6.3.1
[CloudPOS SDK AARarrow-up-right](https://ftp.wizarpos.com/device/java/cloudpossdkV1.6.3.1_Standard.aar)
2024-06-27
1.6.2.9
[CloudPOS SDK AARarrow-up-right](https://ftp.wizarpos.com/device/java/cloudpossdkV1.6.2.9_Standard.aar)
2024-06-06
1.6.2.8
[CloudPOS SDK AARarrow-up-right](https://ftp.wizarpos.com/device/java/cloudpossdkV1.6.2.8_Standard.aar)
2024-05-14
1.6.2.7
[CloudPOS SDK AARarrow-up-right](https://ftp.wizarpos.com/device/java/cloudpossdkV1.6.2.7_Standard.aar)
2024-04-26
1.6.2.1
[CloudPOS SDK AARarrow-up-right](https://ftp.wizarpos.com/device/java/cloudpossdkV1.6.2.1_Standard.aar)
2024-02-29
1.6.1.5
[CloudPOS SDK AARarrow-up-right](https://ftp.wizarpos.com/device/java/cloudpossdkV1.6.1.5_Standard.aar)
2024-01-26
1.5.4.93
[CloudPOS SDK AARarrow-up-right](https://ftp.wizarpos.com/device/java/cloudpossdkV1.5.4.93_Standard.aar)
2023-12-28
1.5.4.84
[CloudPOS SDK AARarrow-up-right](https://ftp.wizarpos.com/device/java/cloudpossdkV1.5.4.84_Standard.aar)
2023-11-17
1.5.4.82
[CloudPOS SDK AARarrow-up-right](https://ftp.wizarpos.com/device/java/cloudpossdkV1.5.4.82_Standard.aar)
2023-10-27
1.5.4.80
[CloudPOS SDK AARarrow-up-right](https://ftp.wizarpos.com/device/java/cloudpossdkV1.5.4.80_Standard.aar)
2023-09-25
1.5.4.76
[CloudPOS SDK AARarrow-up-right](https://ftp.wizarpos.com/device/java/cloudpossdkV1.5.4.76_Standard.aar)
2023-08-21
1.5.4.74
[CloudPOS SDK AARarrow-up-right](https://ftp.wizarpos.com/device/java/cloudpossdkV1.5.4.74_Standard.aar)
2023-07-14
1.5.4.73
[CloudPOS SDK AARarrow-up-right](https://ftp.wizarpos.com/device/java/cloudpossdkV1.5.4.73_Standard.aar)
2023-05-10
1.5.4.72
[CloudPOS SDK AARarrow-up-right](https://ftp.wizarpos.com/device/java/cloudpossdkV1.5.4.72_Standard.aar)
2023-04-23
1.5.4.66
[CloudPOS SDK AARarrow-up-right](https://ftp.wizarpos.com/device/java/cloudpossdkV1.5.4.66_Standard.aar)
2023-03-24
1.5.4.60
[CloudPOS SDK AARarrow-up-right](https://ftp.wizarpos.com/device/java/cloudpossdkV1.5.4.60_Standard.aar)
2023-02-15
1.5.4.52
[CloudPOS SDK AARarrow-up-right](https://ftp.wizarpos.com/device/java/cloudpossdkV1.5.4.52_Standard.aar)
2023-01-31
Note: For older versions, please contact WizarPOS. [Her is the latest Javadocarrow-up-right](https://ftp.wizarpos.com/device/java/java_doc_all_cloudpossdkV1.7.7.18.zip)
.
###
[hashtag](https://smartpossdk.gitbook.io/cloudpossdk/cloudpos-sdk/cloudpos-sdk-aar#versioning)
Versioning
The CloudPOS SDK AAR version number follows the format: Major.Minor.Stage.Build. The main version is updated for architectural changes, the minor version annually, the stage version monthly, and the build version for feature additions or bug fixes.
###
[hashtag](https://smartpossdk.gitbook.io/cloudpossdk/cloudpos-sdk/cloudpos-sdk-aar#change-history)
Change History
**1.7.7.18**
* **Add API for switching between external and internal SIM antennas.**
* **Update EMV-related so files.**
* **Add interfaces for MSR swipe, SmartCard attach, RFCard attach, and the last usage time of Printer write.**
**1.7.7.13**
* **Removed the libraries related to sdk\_secondarydisplaylib .**
* **Modified the CustomerDisplayDevice and the corresponding JavaDoc description. The original interface would scale the image to 320\*240 size, but now the size restriction has been removed and images of any size can be passed.**
* **Changed the AbstracAdvancetDevice method to protected.**
* **Fix the error that does not allow the AES algorithm.**
* **Add an API to stop the application.**
* **Adapt HSM to RSA4096 keys.**
* **Provide an interface for the customer display device to obtain the size.**
* **Add an application interface to obtain the last access time of the terminal card - getDeviceLastAccessTime. The terminal's TMSAgent version should be greater than or equal to 5.4.41.**
* **Add paper status detection to the print HTML interface. If an out of paper is detected during printing, return PRINT\_ERROR.**
**1.7.7.7**
* **Fix the bug of isDeviceExist-customerdisplay .**
* **Delete the unimplemented setAccessibilityService and getAccessibilityService methods in the ISystemDevice interface.**
* **Add the method for setting a static IP for Wi-Fi.**
* **Add skipRATS(), calling it before card search can avoid entering 14443-4.**
* **Fix bug of waitForCardAbsent.**
* **Add support for PSAM card slots 5 and 6.**
* **Add Admin/user login/logout interfaces.**
* **Optimize the judgment of whether MSR exists.**
**1.7.6.9**
* **Added LEDGroupDevice to turn on LEDs simultaneously.**
* **JavaSDK minimum Android SDK version upgraded to 23.**
* **Pinpad added the updateUserKeyByX9\_143 interface.**
* **Optimized contactless card type detection.**
* **Fixed the issue of SDK failing to open the RJ45-to-USB serial interface.**
* **Added methods to read/write raw MDB data in ExtBoardDevice.**
**1.7.6.6**
* **When testing the serial port using the new SDK, open failures may occur.**
* **Added functionality for setting Wi-Fi certificates.**
* **Fixed a bug when calling the decreaseValue method.**
* **Added ExtBoard library functionality for manipulating the DigitIO port.**
* **Added a keepImageOnSleep(boolean) method to CustomerDisplayDevice.**
* **Added independent control for enabling/disabling the three navigation bar buttons.**
* **Set the terminal's reverse display state in the accessibility service.**
* **Added interfaces for obtaining Wi-Fi MAC, Ethernet MAC, imei, and simCardSn.**
* **Added an interface for setting setBatteryPercentEnabled.**
* **Supported checking for the presence of a customer display.**
* **Changed the serial port name from SERIAL\_VENDOR to SERIAL\_EXT2. Added a corresponding ID for external calls: ID\_SERIAL\_EXT2.**
* **Add screenshot interfaces.**
**1.7.5.1**
* **Add the "enableStaticIp" method to implement it.**
* **Modify the implementation of the APN addByAllArgs interface.**
* **Modify the implementation of the getLevel method.**
* **Fix the issue where the printBitmap method in Android 14 has a slow printing speed of images.**
* **Fix the issue with the SDK scanning API.**
* **Add the screen-off interface "lockNow", enabling continuous work even when the screen is off.**
**1.7.4.16**
* **Disabled obfuscation for the** `**sdk_pdfboxlib**` **library.**
* **Added cash drawer open method for D3 devices.**
* **Enabled buffer overflow protection in GCC/CLang for the SO files.**
* **Integrated Java SDK for Q1K secondary display.**
* **Removed SDK logs containing the 'q2p' character sequence.**
* **Fix the issue where the RF card ID retrieval method sometimes returns all zeros.**
* **Add API to set the text when locking the screen.**
* **Add an API to set the privacy options in the lock screen settings, including whether to show or not show notifications.**
**1.7.4.7**
* **New Feature:** Add screen rotation system method for Q3AU: setSystemOrientation
* **New Feature:** Support Dex serial port, Port ID: SerialPortDevice.ID\_SERIAL\_VENDOR
* **New Feature:** Add method to initiates the WiFi Access Point (AP)
* **New Feature:** Add CashDrawer implement for D3
* **Fix bug:** Print crash in D3
* **Fix bug:** If the width of the picture printed by the automatic grayscale method is not a multiple of 8, a black vertical line will appear on the far right.
1.7.4.2
* **Fix bug:** Added adaptation for the `isDeviceExist` method on Q2 and Q3 series devices.
1.7.3.9
* **Fix bug:** `printBitmapAutoGrayscale()` is now compatible with Android 12 and later.
* **Fix bug**: Optimized the code for the D3 USB printer.
* **New Feature**: Added three interfaces in the SDK's PINPad module to update the transfer key and master key using the TR31 format.
* **Fix bug**: Updated the EMV implementation to support Android NFC.
1.7.2.2
* Add charset to ensure proper text encoding in print output.
1.7.1.5
* Optimization of EMV implementation.
* Fixed the default printing image effect.
* Fixed issues with getModel, getManufacturer, and getModuleVersion.
* Added an advanced SDK: ISystemDevice，IScannerDevice，IPINPadDevice.
1.6.5.0
* Optimization of EMV implementation.
* Add isPrintingDone method, now only Q2Premium supports it.
1.6.4.4
* Relolved an issue, when the back button is disabled, go to print html. At the moment start converting html, click the back button, occasionally print a blank page.
* Add new setLogLevel(int level) method.
1.6.4.2
* Add new setGlobalGUIConfiguration() method.
* Resolved an issue with the `checkIntRange()` function when invoking `selectPinblockFormat()`.
1.6.3.9
* Optimization of EMV implementation.
1.6.3.7
* When using the `printhtml` method, there is an occasional issue where the `onFinish` callback is triggered twice.
* Optimization of EMV implementation.
1.6.3.6
* Fixed heigh=0 issue in printHTML method.
* Optimization of EMV implementation.
1.6.3.4
* Add new calculateMac method, which support CMAC MAC algorithm(Supported model: Q3A7).
* Support DUKPT AES algorithm(Suppported model: Q3 Android 7/Q2Premium).
* When SDK open the printer, check the power level, and stop working when the power level is 0% .
* Reduce the printing of SDK serial ports and PINPAD logs
* Optimization of EMV implementation.
* Fixed bug in HSM isKeyExist API.
1.6.3.1
* Upgrade the Cipher algorithm used for PDF printing.
1.6.2.9
* Adapt to print with the new Chengdong HD15p and HD25p models.
* Fixed the issue of the entire MSR failing after a specific track failure.
* Modify the comments for `SelectPinblockFormat()` and restrict the input parameters.
1.6.2.8
* Fixed bug in SmartCard API: IC Card implement has not detect card when inserted PSAM Card.
1.6.2.7
* Fixed bug in RFCard API: Modify the timeout from 200ms to 300ms when detecting whether a RFCard is removed
* Fixed bug in SerialPort API: Return LEVEL\_3\_HALTED when cable disconnect.
* Add Extended Serial Port power on/off API.
* Optimization of EMV implementation.
* Fixed bug in Smartcard API: Reset the isConnected status in the card removal callback.
* Supports SAM 1 for Q2Premium
1.6.2.1
* Optimization of EMV implementation.
* Supports decryption with DUKPT 2009 Data Key.
1.6.1.5
* Completely remove printStackTrace statements from the SDK.
* Optimization of EMV implementation.
* Added logging in the HSM JNI getrandom method to print the length of the input buffer parameter.
* Enhanced RF reader Capabilities: Added methods to enables/disables low power card detection mode.
* EMV Implementation Updates: The PINPad keyboard is closed when the emv\_stop\_process function is executed.
* Polish javadoc.
1.5.4.93
* New USB Printer Support: Introduced a new USB type specifically for USB printers, enhancing connectivity and compatibility.
* Enhanced Printing Capabilities: Added a method to print PDFs or bitmaps with varying brightness levels, allowing for more flexible printing options.
* Bug Fix in convertHTML2image: Resolved a bug in the convertHTML2image function. Implemented a default timeout of 30 seconds to prevent blocking within the method, enhancing reliability and performance.
* EMV Implementation Updates: The EMV (Europay, MasterCard, and Visa) implementation has been updated for improved functionality and security.
* Rupay Service Parameter API: Added an API specifically for Rupay Service Parameter
* Reboot Time Setting Method: Introduced a method to set the reboot time. This is available in the com.wizarpos.wizarviewagentassistant.aidl ISystemManagerService, which is included in the SDK and does not require separate addition.
* New PINPAD Layout Support: Added support for a new PINPAD layout, which includes function buttons at the bottom of the keyboard, enhancing usability and user experience.
1.5.4.84
* Fixed a bug in PrinterDevice.convertHTML2image(\*).
* Fixed a bug in SmartCardReaderDevice.open(int logicalID, int cardEmvMode).
* Updated EMV implementation.
1.5.4.80
* Updated EMV implementation, added emv\_set\_log\_level (default is 0: no log output).
1.5.4.76
* Added support for ESP mode to calculate pin block.
* Added support for getting the current PIN length when using default PINPAD UI.
1.5.4.74
* Added support for calculating MAC response for DUKPT.
1.5.4.73
* Fixed bug for enableEmvAuthOption.
1.5.4.72
* Updated EMV implementation.
* Added support for PSAM card slots 0 and 2 in Q2 Android 12.
* Added serial ID: ID\_USB\_GPRINTER.
1.5.4.66
* Updated EMV implementation.
* Added API for updating master by old master key.
1.5.4.60
* Updated EMV implementation.
* Added API for Mastercard signal.
* Modified arm64-v8a.
1.5.4.52
* Added another update user key method, set user key type, no check value.
* Added arm64-v8a.
Removed old version change log (20231201).
For any inquiries or assistance, please contact our support team.
Thank you for choosing CloudPOS SDK AAR!
[PreviousScanning Service Usagechevron-left](https://smartpossdk.gitbook.io/cloudpossdk/cloudpos-sdk/scanning-service-usage)
[NextJava API Sampleschevron-right](https://smartpossdk.gitbook.io/cloudpossdk/cloudpos-sdk/java-api-samples)
Last updated 9 days ago
* [Overview](https://smartpossdk.gitbook.io/cloudpossdk/cloudpos-sdk/cloudpos-sdk-aar#overview)
* [Getting Started](https://smartpossdk.gitbook.io/cloudpossdk/cloudpos-sdk/cloudpos-sdk-aar#getting-started)
* [Versioning](https://smartpossdk.gitbook.io/cloudpossdk/cloudpos-sdk/cloudpos-sdk-aar#versioning)
* [Change History](https://smartpossdk.gitbook.io/cloudpossdk/cloudpos-sdk/cloudpos-sdk-aar#change-history)
---
# Contactless Card | CloudPOS SDK
[PreviousPINPADchevron-left](https://smartpossdk.gitbook.io/cloudpossdk/faq/sdk-error-collection/pinpad)
[NextIC Cardchevron-right](https://smartpossdk.gitbook.io/cloudpossdk/faq/sdk-error-collection/ic-card)
---
# SDK Error Collection | CloudPOS SDK
[Printerchevron-right](https://smartpossdk.gitbook.io/cloudpossdk/faq/sdk-error-collection/printer)
[PINPADchevron-right](https://smartpossdk.gitbook.io/cloudpossdk/faq/sdk-error-collection/pinpad)
[Contactless Cardchevron-right](https://smartpossdk.gitbook.io/cloudpossdk/faq/sdk-error-collection/contactless-card)
[IC Cardchevron-right](https://smartpossdk.gitbook.io/cloudpossdk/faq/sdk-error-collection/ic-card)
[MSR Cardchevron-right](https://smartpossdk.gitbook.io/cloudpossdk/faq/sdk-error-collection/msr-card)
[PreviousFAQchevron-left](https://smartpossdk.gitbook.io/cloudpossdk/faq)
[NextPrinterchevron-right](https://smartpossdk.gitbook.io/cloudpossdk/faq/sdk-error-collection/printer)
---
# IC Card | CloudPOS SDK
[PreviousContactless Cardchevron-left](https://smartpossdk.gitbook.io/cloudpossdk/faq/sdk-error-collection/contactless-card)
[NextMSR Cardchevron-right](https://smartpossdk.gitbook.io/cloudpossdk/faq/sdk-error-collection/msr-card)
---
# PINPAD | CloudPOS SDK
* **Input PIN specification**
If no input is entered, it will timeout after 1 minute, and the interval for each PIN input is 10s after the input begins
* **\-97536(0x17d00) means operation is canceled**
Logs are like:
`######Hooker::HOOKER_CTRL_EVENT_Cancel`
`HAL_Pinpad : Operation canceled`
* **Encrypt specification**
Plain date should be multiple of 8.
* \-76800 means break rules about data sensitivity
For master key/transport key, can not inject same key with the current existed key in the slot.
For user key(session key), under the protection of a master key, the injected userkey cannot be the same as the existed userkeys.
Please notice, for every bytes of the key, if only the last bit of the byte is different, that is same too.
[PreviousPrinterchevron-left](https://smartpossdk.gitbook.io/cloudpossdk/faq/sdk-error-collection/printer)
[NextContactless Cardchevron-right](https://smartpossdk.gitbook.io/cloudpossdk/faq/sdk-error-collection/contactless-card)
Last updated 4 months ago
---
# MSR Card | CloudPOS SDK
[PreviousIC Cardchevron-left](https://smartpossdk.gitbook.io/cloudpossdk/faq/sdk-error-collection/ic-card)
[NextHardware/Repairchevron-right](https://smartpossdk.gitbook.io/cloudpossdk/faq/hardware-repair)
---
# Hardware/Repair | CloudPOS SDK
[Recover a Tampered Terminalchevron-right](https://smartpossdk.gitbook.io/cloudpossdk/faq/hardware-repair/recover-a-tampered-terminal)
[Learning Tampered Eventschevron-right](https://smartpossdk.gitbook.io/cloudpossdk/faq/hardware-repair/learning-tampered-events)
[Remotely Reactivate from Tamperchevron-right](https://smartpossdk.gitbook.io/cloudpossdk/faq/hardware-repair/remotely-reactivate-from-tamper)
[TF (Micro SD) Card Suggestionchevron-right](https://smartpossdk.gitbook.io/cloudpossdk/faq/hardware-repair/tf-micro-sd-card-suggestion)
[Understand Tamper Reasonchevron-right](https://smartpossdk.gitbook.io/cloudpossdk/faq/hardware-repair/understand-tamper-reason)
[PreviousMSR Cardchevron-left](https://smartpossdk.gitbook.io/cloudpossdk/faq/sdk-error-collection/msr-card)
[NextRecover a Tampered Terminalchevron-right](https://smartpossdk.gitbook.io/cloudpossdk/faq/hardware-repair/recover-a-tampered-terminal)
---
# Choose Your Best Practice | Paywizard Integration
**We offer three integration methods:**
[hashtag](https://smartpossdk.gitbook.io/paywizard-open-api/choose-your-best-practice#id-1.-cloud-api)
**1\. Cloud API:**
------------------------------------------------------------------------------------------------------------------------------
[playQuick Start - Cloud APIchevron-right](https://smartpossdk.gitbook.io/paywizard-open-api/cloud-api/quick-start-cloud-api)
The Point of Sale (POS) system and the payment terminal are connected indirectly via a cloud API, with no direct physical link or requirement for the same network segment. This enables flexible integration and secure data transmission.
**Advantages:**
1. **Flexibility and Scalability:** Easily add or remove terminals and POS systems to accommodate business growth. Cloud-based solutions scale seamlessly, minimizing hardware upgrade needs.
2. **Centralized Data Management:** Transaction data is stored centrally, simplifying report generation, sales trend analysis, and inventory management for efficient decision-making.
3. **Location Independence:** Supports multi-location deployments, making it ideal for businesses with multiple branches, while maintaining a unified system without local configurations.
4. **Reduced Physical Dependency:** Eliminates reliance on cables and local wiring, lowering maintenance costs and enhancing system reliability.
[hashtag](https://smartpossdk.gitbook.io/paywizard-open-api/choose-your-best-practice#id-2.-local-integration)
**2\. Local Integration:**
----------------------------------------------------------------------------------------------------------------------------------------------
[Payment App Integration Protocolchevron-right](https://smartpossdk.gitbook.io/paywizard-open-api/semi-integration/local-integration/payment-app-integration-protocol)
The Point of Sale (POS) system and the payment terminal are connected directly via USB, WIFI, Bluetooth, or a wired network to initiate transactions quickly and reliably.
**Advantages:**
1. **Faster Transaction Speeds:** Direct local connections enable quicker processing, outperforming cloud-based options in areas with unstable internet.
2. **Enhanced Security:** Data is transmitted locally, reducing exposure to online threats, but requires strong security measures (e.g., encryption) to address potential local vulnerabilities.
[hashtag](https://smartpossdk.gitbook.io/paywizard-open-api/choose-your-best-practice#id-3.-internal-integration)
**3\. Internal Integration:**
----------------------------------------------------------------------------------------------------------------------------------------------------
[Payment App AIDL Integration Protocolchevron-right](https://smartpossdk.gitbook.io/paywizard-open-api/semi-integration/internal-integration/payment-app-aidl-integration-protocol)
In the payment terminal, the business application directly invokes the AIDL interface provided by the OPC to process transactions internally on the same device, eliminating the need for external connections.
**Advantages:**
1. **Ultra-Fast Processing:** Internal calls reduce latency, enabling near-instant transaction handling without network delays.
2. **Efficient Resource Use:** Leverages local device resources, minimizing overhead and optimizing battery life and performance.
3. **Heightened Security:** Limits data exposure by keeping operations within the device, reducing risks associated with external data transmission.
4. **Simplified Development:** Streamlines integration for developers, as AIDL facilitates easy inter-app communication without complex setups.
###
[hashtag](https://smartpossdk.gitbook.io/paywizard-open-api/choose-your-best-practice#in-summary)
**In summary:**
1. **Local Network Connection**
* **Pros:**
* Faster transaction speeds due to direct communication, ideal for environments with unstable internet.
* Enhanced security by keeping data local, reducing exposure to external threats.
* **Cons:**
* Relies on stable local hardware (e.g., WIFI or Bluetooth signals), which can fail in interference-prone areas.
* Potential security vulnerabilities if local connections aren't properly encrypted or managed.
2. **Internal Invocation (via AIDL)**
* **Pros:**
* Ultra-fast processing with minimal latency, as everything happens on-device.
* Efficient resource use, improving battery life and performance while maintaining high security through localized operations.
* Simplified development and integration for teams.
* **Cons:**
* Limited to a single device, making it inflexible for multi-device or scalable setups.
* Requires advanced technical expertise to implement and troubleshoot.
3. **Cloud-Based API**
* **Pros:**
* Highly scalable and accessible, allowing remote management, real-time updates, and integration across multiple locations.
* Easier to maintain and update software centrally.
* **Cons:**
* Slower processing times in areas with poor internet, potentially disrupting transactions.
* Higher security risks due to data transmission over the internet, increasing exposure to breaches.
circle-info
**Notice:**
If you use WizarPOS ECR or self-service machine, we provide an more easy way to integrate
**Embedded Integration (WizarPOS D22/D3)** is ideal for businesses seeking a compact, all-in-one solution with a streamlined user experience.
[Accessory Agent Service D22/Q3chevron-right](https://smartpossdk.gitbook.io/cloudpossdk/faq/usb-serial-port/accessory-agent-service-d22-q3)
[PreviousOverviewchevron-left](https://smartpossdk.gitbook.io/paywizard-open-api)
[NextIntegration & Go-Live Guidechevron-right](https://smartpossdk.gitbook.io/paywizard-open-api/integration-and-go-live-guide)
Last updated 1 month ago
* [1\. Cloud API:](https://smartpossdk.gitbook.io/paywizard-open-api/choose-your-best-practice#id-1.-cloud-api)
* [2\. Local Integration:](https://smartpossdk.gitbook.io/paywizard-open-api/choose-your-best-practice#id-2.-local-integration)
* [3\. Internal Integration:](https://smartpossdk.gitbook.io/paywizard-open-api/choose-your-best-practice#id-3.-internal-integration)
* [In summary:](https://smartpossdk.gitbook.io/paywizard-open-api/choose-your-best-practice#in-summary)
sun-brightdesktopmoon
sun-brightdesktopmoon
---
# Integration & Go-Live Guide | Paywizard Integration
* * *
1
[hashtag](https://smartpossdk.gitbook.io/paywizard-open-api/integration-and-go-live-guide#milestone-0-project-kick-off)
MILESTONE 0: PROJECT KICK OFF
----------------------------------------------------------------------------------------------------------------------------------------------------------
Before writing any code, we must ensure all administrative and logistical prerequisites are met to ensure a smooth integration journey.
###
[hashtag](https://smartpossdk.gitbook.io/paywizard-open-api/integration-and-go-live-guide#id-1.-administrative-and-logistics)
**1\. Administrative & Logistics**
* **In-take Form:** Complete and sign the project In-take form to register your project scope.
* **Device Shipping:** We will ship the test terminals to your designated office.
* **Resource Allocation:** A dedicated **Test Analyst** will be assigned to your account to guide you through the testing phases.
###
[hashtag](https://smartpossdk.gitbook.io/paywizard-open-api/integration-and-go-live-guide#id-2.-obtain-credentials-and-setup)
**2\. Obtain Credentials & Setup**
The preparation depends on your integration method:
####
[hashtag](https://smartpossdk.gitbook.io/paywizard-open-api/integration-and-go-live-guide#id-2.1-for-cloud-api-integrators)
**2.1 For Cloud API Integrators:**
* System will send you **3 separate emails**. Please check your inbox (including the spam folder) for the following:
1. **Developer Account**: Contains your unique **Developer ID** and **Secret**.
2. **Test Merchant Token**: The authentication token required for API calls.
3. **Portal Credentials**: Login details for the Test Merchant Portal to view sandbox transaction details.
####
[hashtag](https://smartpossdk.gitbook.io/paywizard-open-api/integration-and-go-live-guide#id-2.2-for-semi-integration-integrators)
**2.2 For Semi-Integration Integrators:**
* Once you have set up your physical test environment, you can begin testing immediately.
* \* **Optional Portal Access:** If you wish to view real-time data for your test transactions, we can provision a **Test Merchant Account** for you upon request. This will allow you to log in to the dashboard and analyze your testing results.
> 🔗 **Refernce:** [**https://smartpossdk.gitbook.io/paywizard-open-api/cloud-api/integration-best-practices**arrow-up-right](https://smartpossdk.gitbook.io/paywizard-open-api/cloud-api/integration-best-practices)
> ✅ **Milestone Goal:** You have the hardware, the accounts, and the contact person ready to start.
2
[hashtag](https://smartpossdk.gitbook.io/paywizard-open-api/integration-and-go-live-guide#milestone-1-sandbox-integration)
MILESTONE 1: SANDBOX INTEGRATION
----------------------------------------------------------------------------------------------------------------------------------------------------------------
With the environment ready, you enter the development phase. Your goal is to connect your system to ours and pass the standard functional tests in a risk-free environment.
###
[hashtag](https://smartpossdk.gitbook.io/paywizard-open-api/integration-and-go-live-guide#id-1.-setup-and-development)
**1\. Setup & Development**
* **Connect Device:** Power on your test terminal and ensure it is connected to the internet.
* **Testing APP:**
* **Paywizard Middleware:** Ensure the middleware service is running on the device.
* **Paywizard Test Payment App:** Open the simulator payment app which processes transactions **without charging real money**.
###
[hashtag](https://smartpossdk.gitbook.io/paywizard-open-api/integration-and-go-live-guide#id-2.-integration-and-verification)
**2\. Integration & Verification**
Perform the coding or configuration required for your integration method (Cloud API or Semi-integration).Before moving to the next phase, you must validate your integration against a complete set of test cases to ensure the **robustness** of your system:
* **Standard Transactions:** Develop and verify all required transaction types (Sale, Void, Refund, Pre-auth).
* **Exception Handling:** Simulate edge cases (e.g., Network Timeout, Card Decline) using the Test Payment App's simulation features.
* **Test Case Submission:** Run the full suite of **Standard Test Cases** provided by your Test Analyst and submit the results for review.
circle-info
**Note:** All transactions in this phase are simulated. You can safely test edge cases (e.g., network errors) without using a real credit card.
circle-info
**Ready for Next Step?** Once your test cases are reviewed and approved by your Test Analyst, you will be cleared to move to **Milestone 2: Pre-Production Pilot**.
3
[hashtag](https://smartpossdk.gitbook.io/paywizard-open-api/integration-and-go-live-guide#milestone-2-pre-production-pilot)
MILESTONE 2: PRE-PRODUCTION PILOT
------------------------------------------------------------------------------------------------------------------------------------------------------------------
Upon completing Sandbox verification, you will migrate to the Production Environment. In this phase, you will use **real Production Parameters** and the **actual Processor Payment App** to verify the system before deploying to live merchants.
###
[hashtag](https://smartpossdk.gitbook.io/paywizard-open-api/integration-and-go-live-guide#id-1.-obtain-production-parameters)
**1\. Obtain Production Parameters**
Paywizard will provision a new set of credentials specifically for the live environment. Please ensure you update your system with the following:
* **Production Developer Credentials:** A new **Developer ID** and **Secret** specific to the production environment.
* **Production Portal Access:** Access to the Production Merchant Portal for viewing live transaction data.
* **Production Merchant Parameters:** Configuration data linked to the **real Processor/Acquirer MID** that you provided.
> ⚠️ **Action Required:** Update your Machine/Terminal Application or Server-side Application to use these new production endpoints and credentials.
###
[hashtag](https://smartpossdk.gitbook.io/paywizard-open-api/integration-and-go-live-guide#id-2.-device-and-application-reconfiguration)
**2\. Device & Application Reconfiguration**
You must transition the physical WizarPOS terminal from "Debug Mode" to "Live Mode" by following these steps:
####
[hashtag](https://smartpossdk.gitbook.io/paywizard-open-api/integration-and-go-live-guide#id-2.1-reconfigure-middleware)
**2.1 Reconfigure Middleware:**
Update the **Paywizard Middleware** settings on the device to point to the Production Environment parameters.
####
[hashtag](https://smartpossdk.gitbook.io/paywizard-open-api/integration-and-go-live-guide#id-2.2-swap-payment-applications)
**2.2 Swap Payment Applications:**
* 🛑 **Uninstall:** Remove the _Paywizard Test Payment App_ (it is no longer used).
* ✅ **Install:** Install the specific **Processor/Acquirer Payment App** required for your region/bank.
####
[hashtag](https://smartpossdk.gitbook.io/paywizard-open-api/integration-and-go-live-guide#id-2.3-apply-varsheet-configuration)
**2.3 Apply Varsheet Configuration:**
Configure the newly installed Processor Payment App using the **Production Varsheet** provided by the acquirer/processor.
###
[hashtag](https://smartpossdk.gitbook.io/paywizard-open-api/integration-and-go-live-guide#id-3.-production-verification-round)
**3\. Production Verification Round**
Before deploying to any real merchant store, you must perform a final "Pilot Test" using the production setup:
* **Full Regression Test:** Repeat the full suite of test cases (all transaction types: Sale, Refund, Void, etc.) that you performed in the Sandbox.
* **Exception Handling:** Re-verify common exception scenarios (e.g., user cancellation, card decline) to ensure the production app behaves as expected.
triangle-exclamation
**Critical:** You may only proceed to **Step 3 (Go Live)** and deploy to real merchants after **successfully passing** this full round of production testing.
4
[hashtag](https://smartpossdk.gitbook.io/paywizard-open-api/integration-and-go-live-guide#milestone-3-go-live)
MILESTONE 3: GO LIVE!
-----------------------------------------------------------------------------------------------------------------------------------------
Congratulations! Having successfully passed the production pilot test, you are now ready to deploy the fully configured solution to actual merchant locations.
###
[hashtag](https://smartpossdk.gitbook.io/paywizard-open-api/integration-and-go-live-guide#id-1.-merchant-deployment)
**1\. Merchant Deployment**
Deploy the system to your real merchants using the **validated production configuration** from Step 2.
* Ensure the WizarPOS terminal and your application are retaining the correct **Production MID** and **Varsheet parameters**.
* No further configuration changes should be made at this stage without prior testing.
###
[hashtag](https://smartpossdk.gitbook.io/paywizard-open-api/integration-and-go-live-guide#id-2.-live-processing)
**2\. Live Processing**
You may now begin processing real transactions with actual customers.
* **Monitoring:** We recommend closely monitoring the first batch of live transactions via the Production Portal to ensure stability.
* **Support:** If any issues arise during the initial launch, please contact our support team immediately.
circle-check
**Launch Successful!**
Your integration is now complete. We appreciate your partnership and cooperation throughout this process.
**We wish you a prosperous business and great success!**
[PreviousChoose Your Best Practicechevron-left](https://smartpossdk.gitbook.io/paywizard-open-api/choose-your-best-practice)
[NextQuick Start - Cloud APIchevron-right](https://smartpossdk.gitbook.io/paywizard-open-api/cloud-api/quick-start-cloud-api)
Last updated 1 month ago
* [MILESTONE 0: PROJECT KICK OFF](https://smartpossdk.gitbook.io/paywizard-open-api/integration-and-go-live-guide#milestone-0-project-kick-off)
* [1\. Administrative & Logistics](https://smartpossdk.gitbook.io/paywizard-open-api/integration-and-go-live-guide#id-1.-administrative-and-logistics)
* [2\. Obtain Credentials & Setup](https://smartpossdk.gitbook.io/paywizard-open-api/integration-and-go-live-guide#id-2.-obtain-credentials-and-setup)
* [MILESTONE 1: SANDBOX INTEGRATION](https://smartpossdk.gitbook.io/paywizard-open-api/integration-and-go-live-guide#milestone-1-sandbox-integration)
* [1\. Setup & Development](https://smartpossdk.gitbook.io/paywizard-open-api/integration-and-go-live-guide#id-1.-setup-and-development)
* [2\. Integration & Verification](https://smartpossdk.gitbook.io/paywizard-open-api/integration-and-go-live-guide#id-2.-integration-and-verification)
* [MILESTONE 2: PRE-PRODUCTION PILOT](https://smartpossdk.gitbook.io/paywizard-open-api/integration-and-go-live-guide#milestone-2-pre-production-pilot)
* [1\. Obtain Production Parameters](https://smartpossdk.gitbook.io/paywizard-open-api/integration-and-go-live-guide#id-1.-obtain-production-parameters)
* [2\. Device & Application Reconfiguration](https://smartpossdk.gitbook.io/paywizard-open-api/integration-and-go-live-guide#id-2.-device-and-application-reconfiguration)
* [3\. Production Verification Round](https://smartpossdk.gitbook.io/paywizard-open-api/integration-and-go-live-guide#id-3.-production-verification-round)
* [MILESTONE 3: GO LIVE!](https://smartpossdk.gitbook.io/paywizard-open-api/integration-and-go-live-guide#milestone-3-go-live)
* [1\. Merchant Deployment](https://smartpossdk.gitbook.io/paywizard-open-api/integration-and-go-live-guide#id-1.-merchant-deployment)
* [2\. Live Processing](https://smartpossdk.gitbook.io/paywizard-open-api/integration-and-go-live-guide#id-2.-live-processing)
sun-brightdesktopmoon
sun-brightdesktopmoon
---
# PayWizard Open Platform API Signature Guide V3 | Paywizard Integration
This document details the process for generating and verifying signatures for PayWizard Open Platform API requests using version 3 of our signature scheme. This process ensures the integrity and authenticity of API requests.
API request messages are signed using a **SHA256-HMAC** algorithm with your unique **developer secret key**.
###
[hashtag](https://smartpossdk.gitbook.io/paywizard-open-api/cloud-api/paywizard-open-platform-api-signature-guide-v3#signature-generation-steps)
Signature Generation Steps:
The general procedure for generating the `signValue` is as follows:
1
###
[hashtag](https://smartpossdk.gitbook.io/paywizard-open-api/cloud-api/paywizard-open-platform-api-signature-guide-v3#obtain-request-body-stringa)
**Obtain Request Body (**`**stringA**`**)**:
The raw JSON string from the request body constitutes `stringA`. Ensure no whitespace or reordering of keys is introduced if the original JSON string is obtained directly from the request.
Copy
{
"clientId": "client12345",
"merchantId": "10800000003",
"posId": "D31231234567890",
"terminalId": "12345678",
"terminalSn": "WP123987987897"
}
2
###
[hashtag](https://smartpossdk.gitbook.io/paywizard-open-api/cloud-api/paywizard-open-platform-api-signature-guide-v3#construct-signature-string-stringsigntemp)
**Construct Signature String (**`**stringSignTemp**`**)**:
Concatenate the following string `&clientId={clientId}&clientSecret={clientSecret}` to the end of `stringA`. The resulting string is `stringSignTemp`.
Copy
{"clientId":"client12345","merchantId":"10800000003","posId":"D31231234567890","terminalId":"12345678","terminalSn":"WP123987987897"}&clientId=client12345&clientSecret=9fb645400aabaa33ee0e423405d8c676
3
###
[hashtag](https://smartpossdk.gitbook.io/paywizard-open-api/cloud-api/paywizard-open-platform-api-signature-guide-v3#apply-hmac-sha256-hashing)
**Apply HMAC-SHA256 Hashing**
Perform an **HMAC-SHA256 hash calculation** on `stringSignTemp` using your designated **developer secret key**. The hexadecimal representation of the resulting hash value is the `signValue`.
circle-info
The `clientId` and `clientSecret` used in `stringSignTemp` are your unique API credentials provided by PayWizard for signature generation.
4
###
[hashtag](https://smartpossdk.gitbook.io/paywizard-open-api/cloud-api/paywizard-open-platform-api-signature-guide-v3#include-signature-in-request-header)
**Include Signature in Request Header**
The calculated `signValue` must be included in the request header under the parameter name `sign`.
###
[hashtag](https://smartpossdk.gitbook.io/paywizard-open-api/cloud-api/paywizard-open-platform-api-signature-guide-v3#example-request)
Example Request:
Below is an illustrative `curl` command demonstrating a signed API request:
Copy
curl --location --request POST 'https://uat.paywizard.biz/ovstrade/openVarSheet/queryStatus' \
--header 'jwt-token: BIKE195JVXTN7WA5DXZISQ11GPEUYI7A' \
--header 'Content-Type: application/json' \
--header 'sign: 57ba54072ed2aaa4b2905c41e7c91fd1395ef8f6f76e6e7cdbefe7a88437de6c' \
--data-raw '{
"clientId": "825420368247390208",
"pushId":"942783670425616384"
}'
* * *
###
[hashtag](https://smartpossdk.gitbook.io/paywizard-open-api/cloud-api/paywizard-open-platform-api-signature-guide-v3#sample-code-for-encrypt)
Sample Code for Encrypt:
[PreviousIntegration Best Practiceschevron-left](https://smartpossdk.gitbook.io/paywizard-open-api/cloud-api/integration-best-practices)
[NextPOS & Payment Terminal Binding Processchevron-right](https://smartpossdk.gitbook.io/paywizard-open-api/cloud-api/pos-and-payment-terminal-binding-process)
Last updated 4 months ago
* [Signature Generation Steps:](https://smartpossdk.gitbook.io/paywizard-open-api/cloud-api/paywizard-open-platform-api-signature-guide-v3#signature-generation-steps)
* [Obtain Request Body (stringA):](https://smartpossdk.gitbook.io/paywizard-open-api/cloud-api/paywizard-open-platform-api-signature-guide-v3#obtain-request-body-stringa)
* [Construct Signature String (stringSignTemp):](https://smartpossdk.gitbook.io/paywizard-open-api/cloud-api/paywizard-open-platform-api-signature-guide-v3#construct-signature-string-stringsigntemp)
* [Apply HMAC-SHA256 Hashing](https://smartpossdk.gitbook.io/paywizard-open-api/cloud-api/paywizard-open-platform-api-signature-guide-v3#apply-hmac-sha256-hashing)
* [Include Signature in Request Header](https://smartpossdk.gitbook.io/paywizard-open-api/cloud-api/paywizard-open-platform-api-signature-guide-v3#include-signature-in-request-header)
* [Example Request:](https://smartpossdk.gitbook.io/paywizard-open-api/cloud-api/paywizard-open-platform-api-signature-guide-v3#example-request)
* [Sample Code for Encrypt:](https://smartpossdk.gitbook.io/paywizard-open-api/cloud-api/paywizard-open-platform-api-signature-guide-v3#sample-code-for-encrypt)
sun-brightdesktopmoon
Copy
/**
* Encrypts data using HmacSHA256.
* @param data The string to be encrypted.
* @param key The secret key.
* @return java.lang.String The encrypted string in hexadecimal format.
**/
public static String sha256Hmac(String data, String key) {
String cipher = "";
try {
byte[] byteList = key.getBytes(StandardCharsets.UTF_8);
// Construct a secret key from the given byte array for a specified algorithm name,
// in this case, generating a key specific to HmacSHA256.
SecretKey secretKey = new SecretKeySpec(byteList, "HmacSHA256");
// Get a Mac object for a specified MAC algorithm.
Mac mac = Mac.getInstance("HmacSHA256");
// Initialize the Mac object with the given secret key.
mac.init(secretKey);
byte[] text = data.getBytes(StandardCharsets.UTF_8);
byte[] encryptByte = mac.doFinal(text);
cipher = bytesToHexStr(encryptByte);
} catch (NoSuchAlgorithmException | InvalidKeyException e) {
e.printStackTrace();
}
return cipher;
}
/**
* Converts a byte array to a hexadecimal string.
* @param bytes The byte array to convert.
* @return java.lang.String The resulting hexadecimal string.
**/
public static String bytesToHexStr(byte[] bytes) {
StringBuilder hexStr = new StringBuilder();
for (byte b : bytes) {
String hex = Integer.toHexString(b & 0xFF);
if (hex.length() == 1) {
hex = '0' + hex;
}
hexStr.append(hex);
}
return hexStr.toString();
}
/**
* Generates a signature.
* @param paramsStr The data to be sent.
* @param clientId The developer ID.
* @param clientSecret The developer secret key.
* @return java.lang.String The generated signature.
**/
public static String generateSign(String paramsStr, String clientId, String clientSecret) {
String str = StrUtil.format("{}&clientId={}&clientSecret={}", paramsStr, clientId, clientSecret);
log.info("paramsStr:{}", str);
return sha256Hmac(str, clientSecret);
}
public static void main(String[] args) {
JSONObject params = new JSONObject();
params.put("clientId", "825429536610058240");
params.put("merchantId", "10800000003");
params.put("posId", "D31231234567890");
String str = JSON.toJSONString(params);
System.out.println(generateSign(str, "825429536610058240", "K8VZMX99LTVHZW9IJZXE3BIIWU3QJZD2"));
}
sun-brightdesktopmoon
---
# Integration Best Practices | Paywizard Integration
Welcome to the Wizarpos PayWizard Cloud API! To ensure a smooth and secure integration process, please follow these best practices when connecting your services to our platform.
[hashtag](https://smartpossdk.gitbook.io/paywizard-open-api/cloud-api/integration-best-practices#id-1.-getting-started-developer-account-application)
1\. Getting Started: Developer Account Application
-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
Before you begin the integration process, the first step is to apply for a developer account. Please contact our support team to submit your application.
[hashtag](https://smartpossdk.gitbook.io/paywizard-open-api/cloud-api/integration-best-practices#id-2.-sandbox-environment-for-development-and-testing)
2\. Sandbox Environment for Development and Testing
----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
Once your developer account application is approved, we will provide you with credentials for our sandbox environment. This includes:
* **An Email with Sandbox Developer Account**: This account gives you access to the testing environment.
* **An Email with Test Merchant Parameters**: Credentials for a test merchant portal login.
* **An Email with Test Merchant API Token**: A unique token specifically for your dev id and test merchant.
Use these credentials to develop and test your integration thoroughly. The sandbox environment is designed to mimic the functionality of the production environment without affecting live data.
[hashtag](https://smartpossdk.gitbook.io/paywizard-open-api/cloud-api/integration-best-practices#id-3.-integrating-with-the-api)
3\. Integrating with the API
------------------------------------------------------------------------------------------------------------------------------------------------------------------
During the integration phase, please use the provided sandbox developer account and test merchant parameters. This will allow you to test all API endpoints and webhooks to ensure your application is working correctly before going live.
[hashtag](https://smartpossdk.gitbook.io/paywizard-open-api/cloud-api/integration-best-practices#id-4.-transitioning-to-the-production-environment)
4\. Transitioning to the Production Environment
--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
After you have successfully completed your integration and testing in the sandbox, you will be ready to move to the production environment. For this step, you will need to:
* Request Production Credentials: Contact us to receive your production developer account and production merchant parameters.
* Replace Sandbox Credentials: It is crucial to replace all sandbox credentials in your application with the new production credentials. This includes the developer account details, merchant parameters, and the API token.
[hashtag](https://smartpossdk.gitbook.io/paywizard-open-api/cloud-api/integration-best-practices#important-note-on-api-tokens)
Important Note on API Tokens:
-----------------------------------------------------------------------------------------------------------------------------------------------------------------
Please be aware that each merchant has its own unique API token. The token you use in the sandbox environment is for testing purposes only and will not work in the production environment. Similarly, each of your live merchants in the production environment will have a distinct token that must be used for all API requests associated with that merchant.
By following these best practices, you can ensure a successful and secure integration with our Cloud API. If you have any questions, please refer to our API documentation or contact our developer support team.
[PreviousQuick Start - Cloud APIchevron-left](https://smartpossdk.gitbook.io/paywizard-open-api/cloud-api/quick-start-cloud-api)
[NextPayWizard Open Platform API Signature Guide V3chevron-right](https://smartpossdk.gitbook.io/paywizard-open-api/cloud-api/paywizard-open-platform-api-signature-guide-v3)
Last updated 1 month ago
* [1\. Getting Started: Developer Account Application](https://smartpossdk.gitbook.io/paywizard-open-api/cloud-api/integration-best-practices#id-1.-getting-started-developer-account-application)
* [2\. Sandbox Environment for Development and Testing](https://smartpossdk.gitbook.io/paywizard-open-api/cloud-api/integration-best-practices#id-2.-sandbox-environment-for-development-and-testing)
* [3\. Integrating with the API](https://smartpossdk.gitbook.io/paywizard-open-api/cloud-api/integration-best-practices#id-3.-integrating-with-the-api)
* [4\. Transitioning to the Production Environment](https://smartpossdk.gitbook.io/paywizard-open-api/cloud-api/integration-best-practices#id-4.-transitioning-to-the-production-environment)
* [Important Note on API Tokens:](https://smartpossdk.gitbook.io/paywizard-open-api/cloud-api/integration-best-practices#important-note-on-api-tokens)
sun-brightdesktopmoon
sun-brightdesktopmoon
---
# Quick Start - Cloud API | Paywizard Integration
[hashtag](https://smartpossdk.gitbook.io/paywizard-open-api/cloud-api/quick-start-cloud-api#step-1.-register-as-a-platform-developer)
Step 1. Register as a platform developer
-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
[hashtag](https://smartpossdk.gitbook.io/paywizard-open-api/cloud-api/quick-start-cloud-api#step-2.-get-your-access-token)
Step 2. Get your Access Token
-------------------------------------------------------------------------------------------------------------------------------------------------------------
For merchants in the production environment, we will also provide a semi-permanent token to be used for transactions.
triangle-exclamation
Please note that this API endpoint has been deprecated. Once you are onboarded as one of our developers, we will provide you with a semi-permanent token for testing. For merchants in the production environment, we will also provide a semi-permanent token to be used for transactions.
[1Get Access Tokenschevron-right](https://smartpossdk.gitbook.io/paywizard-open-api/cloud-api/pos-and-payment-terminal-binding-process/get-access-tokens)
[hashtag](https://smartpossdk.gitbook.io/paywizard-open-api/cloud-api/quick-start-cloud-api#step-3.-begin-api-integration)
Step 3. Begin API integration
-------------------------------------------------------------------------------------------------------------------------------------------------------------
circle-info
**A valid token is needed when calling the APIs**
[hashtag](https://smartpossdk.gitbook.io/paywizard-open-api/cloud-api/quick-start-cloud-api#step-4.-bind-pos-and-payment-terminal)
Step 4. Bind POS & Payment Terminal
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------
[2API: Bind POS & Payment Terminalchevron-right](https://smartpossdk.gitbook.io/paywizard-open-api/cloud-api/pos-and-payment-terminal-binding-process/api-bind-pos-and-payment-terminal)
[hashtag](https://smartpossdk.gitbook.io/paywizard-open-api/cloud-api/quick-start-cloud-api#step-5.-do-transaction)
Step 5. Do Transaction
-----------------------------------------------------------------------------------------------------------------------------------------------
[3API: POS Initiate Transactionchevron-right](https://smartpossdk.gitbook.io/paywizard-open-api/cloud-api/do-transactions/api-pos-initiate-transaction)
[PreviousIntegration & Go-Live Guidechevron-left](https://smartpossdk.gitbook.io/paywizard-open-api/integration-and-go-live-guide)
[NextIntegration Best Practiceschevron-right](https://smartpossdk.gitbook.io/paywizard-open-api/cloud-api/integration-best-practices)
Last updated 9 months ago
* [Step 1. Register as a platform developer](https://smartpossdk.gitbook.io/paywizard-open-api/cloud-api/quick-start-cloud-api#step-1.-register-as-a-platform-developer)
* [Step 2. Get your Access Token](https://smartpossdk.gitbook.io/paywizard-open-api/cloud-api/quick-start-cloud-api#step-2.-get-your-access-token)
* [Step 3. Begin API integration](https://smartpossdk.gitbook.io/paywizard-open-api/cloud-api/quick-start-cloud-api#step-3.-begin-api-integration)
* [Step 4. Bind POS & Payment Terminal](https://smartpossdk.gitbook.io/paywizard-open-api/cloud-api/quick-start-cloud-api#step-4.-bind-pos-and-payment-terminal)
* [Step 5. Do Transaction](https://smartpossdk.gitbook.io/paywizard-open-api/cloud-api/quick-start-cloud-api#step-5.-do-transaction)
sun-brightdesktopmoon
sun-brightdesktopmoon
---
# Overview | Paywizard Integration
[](https://smartpossdk.gitbook.io/paywizard-open-api/choose-your-best-practice)
**Intro - Choose Your Best Practice**
If you're confused by the multitude of optional integration methods, please click the Intro page to find the best practice that's right for you.
[](https://smartpossdk.gitbook.io/paywizard-open-api/semi-integration/quick-start-semi-integration)
**Terminal Semi-integraiton**
The Point of Sale (POS) system and the payment terminal are connected directly via USB, WIFI, Bluetooth, or a wired network to initiate transactions quickly and reliably.
[](https://smartpossdk.gitbook.io/paywizard-open-api/cloud-api/quick-start-cloud-api)
**Cloud API**
The Point of Sale (POS) system and the payment terminal are connected indirectly via a cloud API
[](https://smartpossdk.gitbook.io/paywizard-open-api/cloud-api/e-receipt-intro)
**E-Receipt**
After your payment application completes a payment, you can choose to upload the desensitized transaction information to the backend.
[NextChoose Your Best Practicechevron-right](https://smartpossdk.gitbook.io/paywizard-open-api/choose-your-best-practice)
Last updated 16 days ago
sun-brightdesktopmoon
sun-brightdesktopmoon
---
# POS & Payment Terminal Binding Process | Paywizard Integration
[2API: Bind POS & Payment Terminalchevron-right](https://smartpossdk.gitbook.io/paywizard-open-api/cloud-api/pos-and-payment-terminal-binding-process/api-bind-pos-and-payment-terminal)
[brackets-curlyAPI: Get POS & Terminal Binding Listchevron-right](https://smartpossdk.gitbook.io/paywizard-open-api/cloud-api/pos-and-payment-terminal-binding-process/api-get-pos-and-terminal-binding-list)
[PreviousPayWizard Open Platform API Signature Guide V3chevron-left](https://smartpossdk.gitbook.io/paywizard-open-api/cloud-api/paywizard-open-platform-api-signature-guide-v3)
[NextGet Access Tokenschevron-right](https://smartpossdk.gitbook.io/paywizard-open-api/cloud-api/pos-and-payment-terminal-binding-process/get-access-tokens)
Last updated 1 year ago
sun-brightdesktopmoon
sun-brightdesktopmoon
---
# Do Transactions | Paywizard Integration
[hashtag](https://smartpossdk.gitbook.io/paywizard-open-api/cloud-api/do-transactions#transaction-flow-of-the-system)
Transaction Flow of the system
---------------------------------------------------------------------------------------------------------------------------------------------------------
[PreviousAPI: Unbind Terminal with POSchevron-left](https://smartpossdk.gitbook.io/paywizard-open-api/cloud-api/pos-and-payment-terminal-binding-process/api-unbind-terminal-with-pos)
[NextAPI: POS Initiate Transactionchevron-right](https://smartpossdk.gitbook.io/paywizard-open-api/cloud-api/do-transactions/api-pos-initiate-transaction)
Last updated 1 year ago
sun-brightdesktopmoon
sun-brightdesktopmoon
---
# Close Order | Paywizard Integration
[hashtag](https://smartpossdk.gitbook.io/paywizard-open-api/apm-qr-wallet/close-order#overview)
Overview
-------------------------------------------------------------------------------------------------------------
This endpoint is used to close an order that has been created but has not yet been paid. This action prevents the customer from completing the payment for the specified transaction.
[hashtag](https://smartpossdk.gitbook.io/paywizard-open-api/apm-qr-wallet/close-order#environments)
Environments
---------------------------------------------------------------------------------------------------------------------
Environment
Protocol
HTTP Method
URL
Sandbox
HTTPS
`POST`
`https://uat.paywizard.biz/ovstrade/openPay/closeOrder`
Production
HTTPS
`POST`
`https://portal.paywizard.biz/ovstrade/openPay/closeOrder`
[hashtag](https://smartpossdk.gitbook.io/paywizard-open-api/apm-qr-wallet/close-order#headers)
**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 Guidearrow-up-right](https://oversea.hs1c.cn/showdoc/web/#/671575440/155776446)
.
[hashtag](https://smartpossdk.gitbook.io/paywizard-open-api/apm-qr-wallet/close-order#request-body-parameters)
**Request Body Parameters**
-----------------------------------------------------------------------------------------------------------------------------------------------
Parameter
Type
Required
Description
`clientId`
String
Yes
Your unique developer ID.
`checkoutId`
String
No
The unique transaction ID generated by the payment platform.
`transIndexCode`
String
No
The unique order ID that was generated by your system.
circle-exclamation
_Note: At least one of_ `_checkoutId_` _or_ `_transIndexCode_` _must be provided. If both are sent,_ `_checkoutId_` _will take precedence._
[hashtag](https://smartpossdk.gitbook.io/paywizard-open-api/apm-qr-wallet/close-order#request-example)
**Request Example**
-------------------------------------------------------------------------------------------------------------------------------
* * *
[hashtag](https://smartpossdk.gitbook.io/paywizard-open-api/apm-qr-wallet/close-order#response-body)
**Response Body**
---------------------------------------------------------------------------------------------------------------------------
The response acknowledges that the request to close the transaction has been received and processed.
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`.
[hashtag](https://smartpossdk.gitbook.io/paywizard-open-api/apm-qr-wallet/close-order#success-response-example)
**Success Response Example**
-------------------------------------------------------------------------------------------------------------------------------------------------
[PreviousVOIDchevron-left](https://smartpossdk.gitbook.io/paywizard-open-api/apm-qr-wallet/void)
[NextQuick Start - Loyalty APIchevron-right](https://smartpossdk.gitbook.io/paywizard-open-api/loyalty/quick-start-loyalty-api)
Last updated 4 months ago
* [Overview](https://smartpossdk.gitbook.io/paywizard-open-api/apm-qr-wallet/close-order#overview)
* [Environments](https://smartpossdk.gitbook.io/paywizard-open-api/apm-qr-wallet/close-order#environments)
* [Headers](https://smartpossdk.gitbook.io/paywizard-open-api/apm-qr-wallet/close-order#headers)
* [Request Body Parameters](https://smartpossdk.gitbook.io/paywizard-open-api/apm-qr-wallet/close-order#request-body-parameters)
* [Request Example](https://smartpossdk.gitbook.io/paywizard-open-api/apm-qr-wallet/close-order#request-example)
* [Response Body](https://smartpossdk.gitbook.io/paywizard-open-api/apm-qr-wallet/close-order#response-body)
* [Success Response Example](https://smartpossdk.gitbook.io/paywizard-open-api/apm-qr-wallet/close-order#success-response-example)
sun-brightdesktopmoon
Copy
{
"clientId": "825429536610058240",
"checkoutId": "202504011341223232135",
"transIndexCode": "20250401123534801"
}
Copy
{
"code": 200,
"msg": "success",
"timestamp": "2024-08-12 14:45:54"
}
sun-brightdesktopmoon
---
# Quick Start: QR Payment API Integration | Paywizard Integration
This guide provides a quick overview of integrating the QR payment APIs to enable both Merchant-Presented Mode (MPM) and Customer-Presented Mode (CPM) transactions, along with essential post-payment operations like querying, refunding, and voiding transactions.
[hashtag](https://smartpossdk.gitbook.io/paywizard-open-api/apm-qr-wallet/quick-start-qr-payment-api-integration#i.-introduction-to-qr-payments)
I. Introduction to QR Payments
------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
QR code payments offer a convenient way for merchants to accept payments, primarily through two modes:
* **Merchant-Presented Mode (MPM)**: The merchant generates and displays a QR code, which the customer scans using their mobile wallet to complete the payment.
* **Customer-Presented Mode (CPM) / Quick Pay**: The customer generates a QR code on their mobile wallet app and presents it to the merchant for scanning to initiate the payment.
[hashtag](https://smartpossdk.gitbook.io/paywizard-open-api/apm-qr-wallet/quick-start-qr-payment-api-integration#ii.-prerequisites)
II. Prerequisites
----------------------------------------------------------------------------------------------------------------------------------------------------------
Before you begin, ensure you have:
* **API Client/SDK**: Install a suitable API library for your programming language (e.g., Java SDK).
* **Authentication Credentials**: Obtain your `CLIENT_ID` to initialize the API client.
[hashtag](https://smartpossdk.gitbook.io/paywizard-open-api/apm-qr-wallet/quick-start-qr-payment-api-integration#iii.-payment-initiation-flows)
III. Payment Initiation Flows
----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
###
[hashtag](https://smartpossdk.gitbook.io/paywizard-open-api/apm-qr-wallet/quick-start-qr-payment-api-integration#a.-merchant-presented-mode-mpm-generate-qr-code-customer-scan)
**A. Merchant Presented Mode (MPM): Generate QR Code (Customer Scan)**
This flow is suitable when the merchant displays a QR code for the customer to scan (`generate-qr-code-customer-scan`).
**Steps:**
1
**Initiate Payment Request (Server-side)**:
* Your merchant system submits an order payment request including details like `paymentRequestId` (unique ID from merchant), `paymentAmount` (currency and value), `order` information, `productCode` (e.g., `CASHIER_PAYMENT`), `paymentNotifyUrl`, and `paymentRedirectUrl`.
* Call the `generate-qr-code-customer-scan` API (or `pay` API) with these parameters.
2
**Receive Payment Response (Server-side)**:
The API returns a response containing the QR code data, often as a `normalUrl` or `codeValue`. This URL typically leads to a checkout page or an image of the QR code.
3
**Display QR Code (Client-side)**:
Pass the `normalUrl` or `codeValue` to your client-side application. The merchant system displays the generated QR code to the customer.
4
**Customer Scans and Pays**:
The customer uses their mobile wallet app to scan the displayed QR code and authorize the payment.
5
**Receive Payment Result Notification (Server-side)**:
Antom (or the payment service) sends an asynchronous notification (`notifyPayment`) to your specified `paymentNotifyUrl` once the payment is completed or fails. This notification contains the `paymentRequestId`, `paymentId`, `paymentAmount`, and `result` status (e.g., `SUCCESS`, `FAIL`, `PROCESSING`). You should verify the notification's signature.
6
**Display Payment Results (Client-side)**:
After the payment, the customer might be redirected to your `paymentRedirectUrl` to show transaction results. Note that client redirection alone should not be the sole basis for determining payment success.
###
[hashtag](https://smartpossdk.gitbook.io/paywizard-open-api/apm-qr-wallet/quick-start-qr-payment-api-integration#b.-customer-presented-mode-cpm-quick-pay-merchant-scan)
**B. Customer Presented Mode (CPM): Quick Pay (Merchant Scan)**
This flow is used when the customer presents a QR code for the merchant to scan (`quick-pay-merchant-scan`).
**Steps:**
1
###
[hashtag](https://smartpossdk.gitbook.io/paywizard-open-api/apm-qr-wallet/quick-start-qr-payment-api-integration#customer-presents-qr-code)
**Customer Presents QR Code**:
The customer generates and presents a QR code (often referred to as a "payment code" or "barcode") via their mobile wallet app.
2
###
[hashtag](https://smartpossdk.gitbook.io/paywizard-open-api/apm-qr-wallet/quick-start-qr-payment-api-integration#merchant-scans-qr-code)
**Merchant Scans QR Code**:
The merchant's POS system or reader scans the customer's presented QR code. This scan typically obtains a customer payment token (e.g., `authCode`).
3
###
[hashtag](https://smartpossdk.gitbook.io/paywizard-open-api/apm-qr-wallet/quick-start-qr-payment-api-integration#submit-payment-request-server-side)
**Submit Payment Request (Server-side)**:
* Your merchant system submits a payment request to the API, including the `paymentRequestId`, `paymentAmount`, `order` information, and the `authCode` obtained from scanning the customer's QR code.
* Call the `quick-pay-merchant-scan` API with these details.
4
###
[hashtag](https://smartpossdk.gitbook.io/paywizard-open-api/apm-qr-wallet/quick-start-qr-payment-api-integration#receive-payment-result-notification-server-side)
**Receive Payment Result Notification (Server-side)**:
The payment service processes the request and sends an asynchronous notification (`notifyPayment`) to your specified `paymentNotifyUrl` with the `paymentId` and ultimate transaction `result`.
5
###
[hashtag](https://smartpossdk.gitbook.io/paywizard-open-api/apm-qr-wallet/quick-start-qr-payment-api-integration#confirm-payment-merchant-side)
**Confirm Payment (Merchant-side)**:
Update the order status in your system based on the notification. Confirm the payment to the customer.
[hashtag](https://smartpossdk.gitbook.io/paywizard-open-api/apm-qr-wallet/quick-start-qr-payment-api-integration#iv.-post-payment-operations)
IV. Post-Payment Operations
------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
###
[hashtag](https://smartpossdk.gitbook.io/paywizard-open-api/apm-qr-wallet/quick-start-qr-payment-api-integration#a.-query-transaction-status-query-transaction-status)
**A. Query Transaction Status (**`**query-transaction-status**`**)**
To check the status of a specific transaction:
1. **Create Query Request (Server-side)**:
* Initiate a query request using the merchant's `paymentRequestId` or the `paymentId` received from the payment system.
2. **Retrieve Response**:
* The response will contain the `paymentStatus` (e.g., `SUCCESS`, `FAIL`, `PROCESSING`) and other transaction details.
3. **Best Practice**: It is recommended to perform a round-robin query at intervals (e.g., every 2 seconds) until a final status (SUCCESS/FAIL) or an asynchronous notification is received.
###
[hashtag](https://smartpossdk.gitbook.io/paywizard-open-api/apm-qr-wallet/quick-start-qr-payment-api-integration#b.-refund-refund)
**B. Refund (**`**refund**`**)**
To issue a refund for a successful transaction:
1. **Initiate Refund Request**:
* Send a refund request including the `paymentId` of the original transaction, the `refundAmount`, and a `refundRequestId`.
* Call the `refund` API.
2. **Process Refund Response**:
* Handle the response, which will indicate whether the refund was initiated successfully.
* (Optional) You can query refund progress using a refund inquiry API if the refund is not immediate.
###
[hashtag](https://smartpossdk.gitbook.io/paywizard-open-api/apm-qr-wallet/quick-start-qr-payment-api-integration#c.-void-void)
**C. Void (**`**void**`**)**
To cancel a pending payment or pre-authorized transaction before settlement:
1. **Initiate Void Request**:
* Send a void request, typically using the `paymentRequestId` or `paymentId` of the transaction you wish to cancel.
* Call the `void` API.
2. **Process Void Response**:
* The response confirms if the void operation was successful.
###
[hashtag](https://smartpossdk.gitbook.io/paywizard-open-api/apm-qr-wallet/quick-start-qr-payment-api-integration#d.-close-order-close-order)
**D. Close Order (**`**close-order**`**)**
To explicitly close an order, often when a payment has timed out or is no longer expected to be completed:
1. **Initiate Close Order Request**:
* Send a request to close the order, using the `paymentRequestId` or a similar order identifier.
* Call the `close-order` API.
2. **Process Close Order Response**:
* The response confirms the order has been marked as closed on the payment system's side.
[PreviousClient SDK APIchevron-left](https://smartpossdk.gitbook.io/paywizard-open-api/online-card-payment/client-sdk-api)
[NextAPM (QR/WALLET) APIchevron-right](https://smartpossdk.gitbook.io/paywizard-open-api/apm-qr-wallet/quick-start-qr-payment-api-integration/apm-qr-wallet-api)
Last updated 1 month ago
* [I. Introduction to QR Payments](https://smartpossdk.gitbook.io/paywizard-open-api/apm-qr-wallet/quick-start-qr-payment-api-integration#i.-introduction-to-qr-payments)
* [II. Prerequisites](https://smartpossdk.gitbook.io/paywizard-open-api/apm-qr-wallet/quick-start-qr-payment-api-integration#ii.-prerequisites)
* [III. Payment Initiation Flows](https://smartpossdk.gitbook.io/paywizard-open-api/apm-qr-wallet/quick-start-qr-payment-api-integration#iii.-payment-initiation-flows)
* [A. Merchant Presented Mode (MPM): Generate QR Code (Customer Scan)](https://smartpossdk.gitbook.io/paywizard-open-api/apm-qr-wallet/quick-start-qr-payment-api-integration#a.-merchant-presented-mode-mpm-generate-qr-code-customer-scan)
* [B. Customer Presented Mode (CPM): Quick Pay (Merchant Scan)](https://smartpossdk.gitbook.io/paywizard-open-api/apm-qr-wallet/quick-start-qr-payment-api-integration#b.-customer-presented-mode-cpm-quick-pay-merchant-scan)
* [Customer Presents QR Code:](https://smartpossdk.gitbook.io/paywizard-open-api/apm-qr-wallet/quick-start-qr-payment-api-integration#customer-presents-qr-code)
* [Merchant Scans QR Code:](https://smartpossdk.gitbook.io/paywizard-open-api/apm-qr-wallet/quick-start-qr-payment-api-integration#merchant-scans-qr-code)
* [Submit Payment Request (Server-side):](https://smartpossdk.gitbook.io/paywizard-open-api/apm-qr-wallet/quick-start-qr-payment-api-integration#submit-payment-request-server-side)
* [Receive Payment Result Notification (Server-side):](https://smartpossdk.gitbook.io/paywizard-open-api/apm-qr-wallet/quick-start-qr-payment-api-integration#receive-payment-result-notification-server-side)
* [Confirm Payment (Merchant-side):](https://smartpossdk.gitbook.io/paywizard-open-api/apm-qr-wallet/quick-start-qr-payment-api-integration#confirm-payment-merchant-side)
* [IV. Post-Payment Operations](https://smartpossdk.gitbook.io/paywizard-open-api/apm-qr-wallet/quick-start-qr-payment-api-integration#iv.-post-payment-operations)
* [A. Query Transaction Status (query-transaction-status)](https://smartpossdk.gitbook.io/paywizard-open-api/apm-qr-wallet/quick-start-qr-payment-api-integration#a.-query-transaction-status-query-transaction-status)
* [B. Refund (refund)](https://smartpossdk.gitbook.io/paywizard-open-api/apm-qr-wallet/quick-start-qr-payment-api-integration#b.-refund-refund)
* [C. Void (void)](https://smartpossdk.gitbook.io/paywizard-open-api/apm-qr-wallet/quick-start-qr-payment-api-integration#c.-void-void)
* [D. Close Order (close-order)](https://smartpossdk.gitbook.io/paywizard-open-api/apm-qr-wallet/quick-start-qr-payment-api-integration#d.-close-order-close-order)
sun-brightdesktopmoon
sun-brightdesktopmoon
---
# Quick Start - Payment Parameter Push | Paywizard Integration
This API series establishes a robust and automated channel for the secure and efficient transmission of critical terminal parameters, ensuring that payment terminals are correctly configured based on data retrieved from the processor by the customer's system.
###
[hashtag](https://smartpossdk.gitbook.io/paywizard-open-api/payment-parameter-varsheet-api/quick-start-payment-parameter-push#id-1.-your-system-initiates-parameter-retrieval)
1\. Your System Initiates Parameter Retrieval:
**Get Varsheet from Processor:** Your system first obtains the "varsheet" from a payment processor. **Log the parameters into the system:** Once received, these parameters are then logged and stored within your system.
###
[hashtag](https://smartpossdk.gitbook.io/paywizard-open-api/payment-parameter-varsheet-api/quick-start-payment-parameter-push#id-2.-paywizard-processes-and-routes-parameters)
2\. PAYwizard Processes and Routes Parameters:
**Payment Para API:** Your system utilizes a "Payment Para API" to transmit the logged parameters to the PAYwizard platform. This API acts as a dedicated channel for this purpose. **Get varsheet para and create xml:** Upon receiving the parameters via the API, PAYwizard processes them and generates an XML file containing the necessary "varsheet" information. **Push to TMS:** PAYwizard then pushes this processed XML data to the TMS (Terminal Management System).
###
[hashtag](https://smartpossdk.gitbook.io/paywizard-open-api/payment-parameter-varsheet-api/quick-start-payment-parameter-push#id-3.-tms-wizarview-delivers-to-terminal)
3\. TMS (Wizarview) Delivers to Terminal:
**Push to Terminal:** The TMS (Wizarview) is responsible for pushing the parameters it received from PAYwizard directly to the target payment terminal.
###
[hashtag](https://smartpossdk.gitbook.io/paywizard-open-api/payment-parameter-varsheet-api/quick-start-payment-parameter-push#id-4.-payment-terminal-applies-parameters)
4\. Payment Terminal Applies Parameters:
**Get Para and Apply:** Finally, the payment terminal receives these parameters and applies them.
[PreviousAIDL Integration Best Practicechevron-left](https://smartpossdk.gitbook.io/paywizard-open-api/semi-integration/internal-integration/aidl-integration-best-practice)
[NextTSYS Transit Parameter Pushchevron-right](https://smartpossdk.gitbook.io/paywizard-open-api/payment-parameter-varsheet-api/tsys-transit-parameter-push)
Last updated 5 months ago
* [1\. Your System Initiates Parameter Retrieval:](https://smartpossdk.gitbook.io/paywizard-open-api/payment-parameter-varsheet-api/quick-start-payment-parameter-push#id-1.-your-system-initiates-parameter-retrieval)
* [2\. PAYwizard Processes and Routes Parameters:](https://smartpossdk.gitbook.io/paywizard-open-api/payment-parameter-varsheet-api/quick-start-payment-parameter-push#id-2.-paywizard-processes-and-routes-parameters)
* [3\. TMS (Wizarview) Delivers to Terminal:](https://smartpossdk.gitbook.io/paywizard-open-api/payment-parameter-varsheet-api/quick-start-payment-parameter-push#id-3.-tms-wizarview-delivers-to-terminal)
* [4\. Payment Terminal Applies Parameters:](https://smartpossdk.gitbook.io/paywizard-open-api/payment-parameter-varsheet-api/quick-start-payment-parameter-push#id-4.-payment-terminal-applies-parameters)
sun-brightdesktopmoon
sun-brightdesktopmoon
---
# Local Integration | Paywizard Integration
[hashtag](https://smartpossdk.gitbook.io/paywizard-open-api/semi-integration/local-integration#for-serial-socket-connection-you-will-need-to-follow)
For Serial / Socket Connection, you will need to follow
-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
[Payment App Integration Protocolchevron-right](https://smartpossdk.gitbook.io/paywizard-open-api/semi-integration/local-integration/payment-app-integration-protocol)
[hashtag](https://smartpossdk.gitbook.io/paywizard-open-api/semi-integration/local-integration#best-practice)
Best Practice
--------------------------------------------------------------------------------------------------------------------------------
[](https://smartpossdk.gitbook.io/paywizard-open-api/semi-integration/local-integration/serial-connection-best-practice)
`**Serial Connection Best Practice**`
[](https://smartpossdk.gitbook.io/paywizard-open-api/semi-integration/local-integration/socket-connection-best-practice)
`**Socket Connection Best Practice**`
[](https://smartpossdk.gitbook.io/paywizard-open-api/semi-integration/local-integration/mdb-connection-best-practice)
`**MDB Connection Best Practice**`
[PreviousQuick Start - Semi Integrationchevron-left](https://smartpossdk.gitbook.io/paywizard-open-api/semi-integration/quick-start-semi-integration)
[NextPayment App Integration Protocolchevron-right](https://smartpossdk.gitbook.io/paywizard-open-api/semi-integration/local-integration/payment-app-integration-protocol)
Last updated 4 months ago
* [For Serial / Socket Connection, you will need to follow](https://smartpossdk.gitbook.io/paywizard-open-api/semi-integration/local-integration#for-serial-socket-connection-you-will-need-to-follow)
* [Best Practice](https://smartpossdk.gitbook.io/paywizard-open-api/semi-integration/local-integration#best-practice)
sun-brightdesktopmoon
sun-brightdesktopmoon
---
# Get Transaction Result | Paywizard Integration
###
[hashtag](https://smartpossdk.gitbook.io/paywizard-open-api/cloud-api/get-transaction-result#overview)
Overview
1. Third-party SAAS initiates a payment request by interacting with the Paywizard system via API.
2. The Paywizard system forwards the payment transaction to the POS Terminal where it is processed.
3. Once completed, the POS Terminal sends the transaction result back to Paywizard.
4. Paywizard pushes the transaction result notification to the Customer's SAAS via API.
[webhookWebhook: Push Transaction Resultchevron-right](https://smartpossdk.gitbook.io/paywizard-open-api/cloud-api/get-transaction-result/webhook-push-transaction-result)
The Customer's SAAS can query order transaction status via the API interface if didn\`t get result push.
[brackets-curlyAPI: Get Transaction Resultchevron-right](https://smartpossdk.gitbook.io/paywizard-open-api/cloud-api/get-transaction-result/api-get-transaction-result)
[PreviousTerminal API: Subscribe Transaction Resultschevron-left](https://smartpossdk.gitbook.io/paywizard-open-api/cloud-api/do-transactions/terminal-api-subscribe-transaction-results)
[NextWebhook: Push Transaction Resultchevron-right](https://smartpossdk.gitbook.io/paywizard-open-api/cloud-api/get-transaction-result/webhook-push-transaction-result)
Last updated 9 months ago
sun-brightdesktopmoon
sun-brightdesktopmoon
---
# E-Receipt Intro | Paywizard Integration
###
[hashtag](https://smartpossdk.gitbook.io/paywizard-open-api/cloud-api/e-receipt-intro#the-paywizard-system-supports-an-e-receipt-system.-after-your-payment-application-completes-a-paymen)
The Paywizard system supports an e-receipt system. After your payment application completes a payment, you can choose to upload the desensitized transaction information to the backend. The system can then automatically send receipt information to consumers via SMS or email, especially useful for terminals without receipt printers.
Upload Transaction Info API:
[square-terminalTerminal API : Upload Transaction Infochevron-right](https://smartpossdk.gitbook.io/paywizard-open-api/cloud-api/e-receipt-intro/terminal-api-upload-transaction-info)
Upload Settlement Info API：
[square-terminalTerminal API : Upload Settlement Infochevron-right](https://smartpossdk.gitbook.io/paywizard-open-api/cloud-api/e-receipt-intro/terminal-api-upload-settlement-info)
[PreviousWebhook: Push Settlement Informationchevron-left](https://smartpossdk.gitbook.io/paywizard-open-api/cloud-api/get-transaction-result/webhook-push-settlement-information)
[NextTerminal API : Upload Transaction Infochevron-right](https://smartpossdk.gitbook.io/paywizard-open-api/cloud-api/e-receipt-intro/terminal-api-upload-transaction-info)
Last updated 7 months ago
sun-brightdesktopmoon
sun-brightdesktopmoon
---
# Query Push Status | Paywizard Integration
This API is used to check the parameter push status.
ENV
PROTOCOL
METHOD
API URL
UAT
HTTP
POST
https://uat.paywizard.biz/ovstrade/varsheet/queryStatus
PROD
HTTP
POST
https://portal.paywizard.biz/ovstrade/varsheet/queryStatus
###
[hashtag](https://smartpossdk.gitbook.io/paywizard-open-api/payment-parameter-varsheet-api/query-push-status#http-header)
Http Header
Name
Value
Content-Type
`application/json`
jwt-token
Token Provided by Paywizard
sign
[PayWizard Open Platform API Signature Guide V3](https://smartpossdk.gitbook.io/paywizard-open-api/cloud-api/paywizard-open-platform-api-signature-guide-v3)
###
[hashtag](https://smartpossdk.gitbook.io/paywizard-open-api/payment-parameter-varsheet-api/query-push-status#request)
**Request**
VAR
NAME
MANDATORY
TYPE
clientId
Developer ID
check
String
pushId
Push ID
check
String
###
[hashtag](https://smartpossdk.gitbook.io/paywizard-open-api/payment-parameter-varsheet-api/query-push-status#request-sample)
**Request Sample**
Copy
{
"clientId": "client12345",
"pushId": "768206988353077248"
}
###
[hashtag](https://smartpossdk.gitbook.io/paywizard-open-api/payment-parameter-varsheet-api/query-push-status#response)
**Response**
VAR
NAME
MANDATORY
TYPE
EXAMPLE
描述
code
Return Code
check
Int
200
Return code 200 indicates a normal transaction; any code other than 200 indicates an anomaly.
msg
Return Message
check
String
success
data
Return Result
check
Object
\--pushId
Push ID
check
String
\--status
Push Status
check
Integer
0: Parameter push in progress 1: Parameter push successful 2: Parameter push failed
timestamp
Date/Time(UTC)
check
String
2024-07-23 17:57:00
###
[hashtag](https://smartpossdk.gitbook.io/paywizard-open-api/payment-parameter-varsheet-api/query-push-status#response-sample)
**Response Sample:**
[PreviousFiserv Parameter Pushchevron-left](https://smartpossdk.gitbook.io/paywizard-open-api/payment-parameter-varsheet-api/fiserv-parameter-push)
[NextQuick Start - Online Paymentchevron-right](https://smartpossdk.gitbook.io/paywizard-open-api/online-card-payment/quick-start-online-payment)
Last updated 5 months ago
* [Http Header](https://smartpossdk.gitbook.io/paywizard-open-api/payment-parameter-varsheet-api/query-push-status#http-header)
* [Request](https://smartpossdk.gitbook.io/paywizard-open-api/payment-parameter-varsheet-api/query-push-status#request)
* [Request Sample](https://smartpossdk.gitbook.io/paywizard-open-api/payment-parameter-varsheet-api/query-push-status#request-sample)
* [Response](https://smartpossdk.gitbook.io/paywizard-open-api/payment-parameter-varsheet-api/query-push-status#response)
* [Response Sample:](https://smartpossdk.gitbook.io/paywizard-open-api/payment-parameter-varsheet-api/query-push-status#response-sample)
sun-brightdesktopmoon
Copy
{
"code": 200,
"msg": "success",
"data": {
"pushId": "768206988353077248",
"status": 0
},
"timestamp": "2024-08-12 14:45:54"
}
sun-brightdesktopmoon
---
# Fiserv Parameter Push | Paywizard Integration
[hashtag](https://smartpossdk.gitbook.io/paywizard-open-api/payment-parameter-varsheet-api/fiserv-parameter-push#overview)
Overview
----------------------------------------------------------------------------------------------------------------------------------------
This endpoint is used to upload and push Fiserv WizarPOS payment configuration parameters to a specific terminal.
[hashtag](https://smartpossdk.gitbook.io/paywizard-open-api/payment-parameter-varsheet-api/fiserv-parameter-push#environments)
Environments
------------------------------------------------------------------------------------------------------------------------------------------------
Environment
Protocol
HTTP Method
URL
Sandbox
HTTPS
`POST`
`https://uat.paywizard.biz/ovstrade/openVarSheet/fiserv/configuration/push`
Production
HTTPS
`POST`
`https://portal.paywizard.biz/ovstrade/openVarSheet/fiserv/configuration/push`
[hashtag](https://smartpossdk.gitbook.io/paywizard-open-api/payment-parameter-varsheet-api/fiserv-parameter-push#authentication)
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 Guidearrow-up-right](https://oversea.hs1c.cn/showdoc/web/#/671575440/155776446)
.
* * *
####
[hashtag](https://smartpossdk.gitbook.io/paywizard-open-api/payment-parameter-varsheet-api/fiserv-parameter-push#endpoint-push-fiserv-configuration)
Endpoint: Push Fiserv Configuration
`POST /ovstrade/openVarSheet/fiserv/configuration/push`
[hashtag](https://smartpossdk.gitbook.io/paywizard-open-api/payment-parameter-varsheet-api/fiserv-parameter-push#headers)
**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 Guidearrow-up-right](https://oversea.hs1c.cn/showdoc/web/#/671575440/155776446)
.
[hashtag](https://smartpossdk.gitbook.io/paywizard-open-api/payment-parameter-varsheet-api/fiserv-parameter-push#request-body-parameters)
**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 Objectarrow-up-right](https://www.google.com/search?q=%23pushdata-object)
below.
* * *
###
[hashtag](https://smartpossdk.gitbook.io/paywizard-open-api/payment-parameter-varsheet-api/fiserv-parameter-push#pushdata-object)
**PushData Object**
Parameter
Type
Required
Description
`terminalSn`
String
Yes
The serial number of the target terminal.
`fiservMerchantInfo`
Object
No
Merchant-specific information from Fiserv. See [FiservMerchantInfo Objectarrow-up-right](https://www.google.com/search?q=%23fiservmerchantinfo-object)
.
`fiservCommunicationInfo`
Object
No
Communication settings for connecting to Fiserv. See [FiservCommunicationInfo Objectarrow-up-right](https://www.google.com/search?q=%23fiservcommunicationinfo-object)
.
`fiservTerminalConfig`
Object
No
Terminal-specific behavior and settings. See [FiservTerminalConfig Objectarrow-up-right](https://www.google.com/search?q=%23fiservterminalconfig-object)
.
###
[hashtag](https://smartpossdk.gitbook.io/paywizard-open-api/payment-parameter-varsheet-api/fiserv-parameter-push#fiservmerchantinfo-object)
**FiservMerchantInfo Object**
Parameter
Type
Required
Description
`merchantId`
String
No
The merchant ID provided by Fiserv.
`terminalId`
String
No
The terminal ID provided by Fiserv.
`tppId`
String
No
The Third-Party Processor ID.
`groupId`
String
No
The group ID.
`merchantName`
String
No
The name of the merchant.
`merchantAddress`
String
No
The merchant's street address.
`merchantCity`
String
No
The merchant's city.
`merchantState`
String
No
The merchant's state or province.
`merchantZip`
String
No
The merchant's postal code.
`merchantPhone`
String
No
The merchant's phone number.
`merchantEmail`
String
No
The merchant's email address.
`countryCode`
String
No
The country code (e.g., "840" for USA).
`currencyCode`
String
No
The currency code (e.g., "840" for USD).
###
[hashtag](https://smartpossdk.gitbook.io/paywizard-open-api/payment-parameter-varsheet-api/fiserv-parameter-push#fiservcommunicationinfo-object)
**FiservCommunicationInfo Object**
Parameter
Type
Required
Description
`primaryHostName`
String
No
The primary host URL for transactions.
`srsDiscoverHostName`
String
No
The host URL for SRS Discover.
`srsHostName`
String
No
The host URL for SRS.
`communicationTimeout`
String
No
The communication timeout in seconds.
###
[hashtag](https://smartpossdk.gitbook.io/paywizard-open-api/payment-parameter-varsheet-api/fiserv-parameter-push#fiservterminalconfig-object)
**FiservTerminalConfig Object**
This object contains detailed settings for the terminal's payment application.
Parameter
Type
Required
Description
`adminPass`
String
No
The administrator password.
`superPass`
String
No
The supervisor password.
`refundPass`
String
No
The password required for processing refunds.
`reversalPass`
String
No
The password required for processing reversals.
`tmkIndex`
String
No
The Terminal Master Key index.
`manualPan`
String
No
Flag to enable/disable manual card number entry.
`avs`
String
No
Flag to enable/disable Address Verification Service (AVS).
`avsStreetAddress`
String
No
AVS setting for street address.
`avsPostalCode`
String
No
AVS setting for postal code.
`avsCvv2`
String
No
AVS setting for CVV2.
`modifyCompleteAmount`
String
No
Configuration for modifying completion amount.
`modifyReversalAmount`
String
No
Configuration for modifying reversal amount.
`partialAuthCap`
String
No
Flag for partial authorization capability.
`networkAccessIndicator`
String
No
The network access indicator.
`pinlessPosDebit`
String
No
Flag for PIN-less POS debit.
`facilitator`
String
No
Flag for facilitator setting.
`alternateMerchant`
String
No
Flag for alternate merchant setting.
`refundType`
String
No
The type of refund processing.
`cashBack`
String
No
Flag to enable/disable cash back.
`cashDiscount`
String
No
Flag to enable/disable cash discounting.
`floorLimit`
String
No
The transaction floor limit.
`contactlessTranLimit`
String
No
The limit for contactless transactions.
`contactlessFloorLimit`
String
No
The floor limit for contactless transactions.
`cmvRequiredLimit`
String
No
The Cardholder Verification Method (CVM) required limit.
`forceSettle`
String
No
Flag to force settlement.
`closeOfBusinessTime`
String
No
The time for automatic end-of-day settlement.
`batchNumber`
String
No
The current batch number.
`transExpiredDays`
String
No
The number of days after which a transaction expires.
`traceNo`
String
No
The current trace number.
`receipt`
String
No
Receipt printing configuration.
* * *
[hashtag](https://smartpossdk.gitbook.io/paywizard-open-api/payment-parameter-varsheet-api/fiserv-parameter-push#request-example)
**Request Example**
----------------------------------------------------------------------------------------------------------------------------------------------------------
* * *
[hashtag](https://smartpossdk.gitbook.io/paywizard-open-api/payment-parameter-varsheet-api/fiserv-parameter-push#response-body)
**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 Codesarrow-up-right](https://www.google.com/search?q=%23push-status-codes)
below.
###
[hashtag](https://smartpossdk.gitbook.io/paywizard-open-api/payment-parameter-varsheet-api/fiserv-parameter-push#push-status-codes)
**Push Status Codes**
Status Code
Description
`0`
In Progress (Parameters are being pushed)
`1`
Success (Parameters were pushed successfully)
`2`
Failure (Parameter push failed)
[hashtag](https://smartpossdk.gitbook.io/paywizard-open-api/payment-parameter-varsheet-api/fiserv-parameter-push#success-response-example)
**Success Response Example**
----------------------------------------------------------------------------------------------------------------------------------------------------------------------------
[PreviousTSYS Transit Parameter Pushchevron-left](https://smartpossdk.gitbook.io/paywizard-open-api/payment-parameter-varsheet-api/tsys-transit-parameter-push)
[NextQuery Push Statuschevron-right](https://smartpossdk.gitbook.io/paywizard-open-api/payment-parameter-varsheet-api/query-push-status)
Last updated 5 months ago
* [Overview](https://smartpossdk.gitbook.io/paywizard-open-api/payment-parameter-varsheet-api/fiserv-parameter-push#overview)
* [Environments](https://smartpossdk.gitbook.io/paywizard-open-api/payment-parameter-varsheet-api/fiserv-parameter-push#environments)
* [Authentication](https://smartpossdk.gitbook.io/paywizard-open-api/payment-parameter-varsheet-api/fiserv-parameter-push#authentication)
* [Headers](https://smartpossdk.gitbook.io/paywizard-open-api/payment-parameter-varsheet-api/fiserv-parameter-push#headers)
* [Request Body Parameters](https://smartpossdk.gitbook.io/paywizard-open-api/payment-parameter-varsheet-api/fiserv-parameter-push#request-body-parameters)
* [PushData Object](https://smartpossdk.gitbook.io/paywizard-open-api/payment-parameter-varsheet-api/fiserv-parameter-push#pushdata-object)
* [FiservMerchantInfo Object](https://smartpossdk.gitbook.io/paywizard-open-api/payment-parameter-varsheet-api/fiserv-parameter-push#fiservmerchantinfo-object)
* [FiservCommunicationInfo Object](https://smartpossdk.gitbook.io/paywizard-open-api/payment-parameter-varsheet-api/fiserv-parameter-push#fiservcommunicationinfo-object)
* [FiservTerminalConfig Object](https://smartpossdk.gitbook.io/paywizard-open-api/payment-parameter-varsheet-api/fiserv-parameter-push#fiservterminalconfig-object)
* [Request Example](https://smartpossdk.gitbook.io/paywizard-open-api/payment-parameter-varsheet-api/fiserv-parameter-push#request-example)
* [Response Body](https://smartpossdk.gitbook.io/paywizard-open-api/payment-parameter-varsheet-api/fiserv-parameter-push#response-body)
* [Push Status Codes](https://smartpossdk.gitbook.io/paywizard-open-api/payment-parameter-varsheet-api/fiserv-parameter-push#push-status-codes)
* [Success Response Example](https://smartpossdk.gitbook.io/paywizard-open-api/payment-parameter-varsheet-api/fiserv-parameter-push#success-response-example)
sun-brightdesktopmoon
Copy
{
"clientId": "client12345",
"pushData": {
"terminalSn": "YOUR_TERMINAL_SERIAL_NUMBER",
"fiservMerchantInfo": {
"merchantId": "YOUR_FISERV_MERCHANT_ID",
"terminalId": "YOUR_FISERV_TERMINAL_ID",
"tppId": "RWI012",
"groupId": "20001",
"merchantName": "FISERV TEST MERCHANT",
"merchantAddress": "123 MAIN ST",
"merchantCity": "ANYTOWN",
"merchantState": "GA",
"merchantZip": "30346",
"merchantPhone": "1234567890",
"merchantEmail": "test@example.com",
"countryCode": "840",
"currencyCode": "840"
},
"fiservCommunicationInfo": {
"primaryHostName": "https://prod.dw.us.fdcnet.biz/rc/",
"srsDiscoverHostName": "https://prod.dw.us.fdcnet.biz/sd/srsxml.rc/",
"srsHostName": "https://stagingsupport.datawire.net/nocportal/SRS.do",
"communicationTimeout": "40"
},
"fiservTerminalConfig": {
"adminPass": "99999999",
"superPass": "123456",
"refundPass": "123456",
"reversalPass": "123456",
"tmkIndex": "2",
"manualPan": "1",
"avs": "1",
"avsStreetAddress": "0",
"avsPostalCode": "0",
"avsCvv2": "0",
"modifyCompleteAmount": "0",
"modifyReversalAmount": "0",
"partialAuthCap": "0",
"networkAccessIndicator": "0",
"pinlessPosDebit": "0",
"facilitator": "0",
"alternateMerchant": "1",
"refundType": "0",
"cashBack": "0",
"cashDiscount": "0",
"floorLimit": "0",
"contactlessTranLimit": "999900",
"contactlessFloorLimit": "0",
"cmvRequiredLimit": "10000",
"forceSettle": "0",
"closeOfBusinessTime": "15:33:59",
"batchNumber": "1",
"transExpiredDays": "30",
"traceNo": "1",
"receipt": "2"
}
}
}
Copy
{
"code": 200,
"msg": "success",
"timestamp": "2025-08-12 14:45:54",
"data": {
"pushId": "768206988353077248",
"status": 0
}
}
sun-brightdesktopmoon
---
# Internal Integration | Paywizard Integration
[Payment App AIDL Integration Protocolchevron-right](https://smartpossdk.gitbook.io/paywizard-open-api/semi-integration/internal-integration/payment-app-aidl-integration-protocol)
[AIDL Integration Best Practicechevron-right](https://smartpossdk.gitbook.io/paywizard-open-api/semi-integration/internal-integration/aidl-integration-best-practice)
[PreviousMDB Connection Best Practicechevron-left](https://smartpossdk.gitbook.io/paywizard-open-api/semi-integration/local-integration/mdb-connection-best-practice)
[NextPayment App AIDL Integration Protocolchevron-right](https://smartpossdk.gitbook.io/paywizard-open-api/semi-integration/internal-integration/payment-app-aidl-integration-protocol)
sun-brightdesktopmoon
sun-brightdesktopmoon
---
# Quick Start - Semi Integration | Paywizard Integration
[hashtag](https://smartpossdk.gitbook.io/paywizard-open-api/semi-integration/quick-start-semi-integration#id-1.-local-integration)
1**. Local Integration:**
-----------------------------------------------------------------------------------------------------------------------------------------------------------------
[Payment App Integration Protocolchevron-right](https://smartpossdk.gitbook.io/paywizard-open-api/semi-integration/local-integration/payment-app-integration-protocol)
The Point of Sale (POS) system and the payment terminal are connected directly via USB, WIFI, Bluetooth, or a wired network to initiate transactions quickly and reliably.
**Advantages:**
1. **Faster Transaction Speeds:** Direct local connections enable quicker processing, outperforming cloud-based options in areas with unstable internet.
2. **Enhanced Security:** Data is transmitted locally, reducing exposure to online threats, but requires strong security measures (e.g., encryption) to address potential local vulnerabilities.
[hashtag](https://smartpossdk.gitbook.io/paywizard-open-api/semi-integration/quick-start-semi-integration#id-2.-internal-integration)
**2\. Internal Integration:**
------------------------------------------------------------------------------------------------------------------------------------------------------------------------
[Payment App AIDL Integration Protocolchevron-right](https://smartpossdk.gitbook.io/paywizard-open-api/semi-integration/internal-integration/payment-app-aidl-integration-protocol)
In the payment terminal, the business application directly invokes the AIDL interface provided by the OPC to process transactions internally on the same device, eliminating the need for external connections.
**Advantages:**
1. **Ultra-Fast Processing:** Internal calls reduce latency, enabling near-instant transaction handling without network delays.
2. **Efficient Resource Use:** Leverages local device resources, minimizing overhead and optimizing battery life and performance.
3. **Heightened Security:** Limits data exposure by keeping operations within the device, reducing risks associated with external data transmission.
4. **Simplified Development:** Streamlines integration for developers, as AIDL facilitates easy inter-app communication without complex setups.
[hashtag](https://smartpossdk.gitbook.io/paywizard-open-api/semi-integration/quick-start-semi-integration#firstheading)
Payment App Integration Details:
-------------------------------------------------------------------------------------------------------------------------------------------------------------
[https://sdkwiki.wizarpos.com/index.php?title=Payment\_Apparrow-up-right](https://sdkwiki.wizarpos.com/index.php?title=Payment_App)
[PreviousTerminal API : Upload Settlement Infochevron-left](https://smartpossdk.gitbook.io/paywizard-open-api/cloud-api/e-receipt-intro/terminal-api-upload-settlement-info)
[NextLocal Integrationchevron-right](https://smartpossdk.gitbook.io/paywizard-open-api/semi-integration/local-integration)
Last updated 7 months ago
* [1\. Local Integration:](https://smartpossdk.gitbook.io/paywizard-open-api/semi-integration/quick-start-semi-integration#id-1.-local-integration)
* [2\. Internal Integration:](https://smartpossdk.gitbook.io/paywizard-open-api/semi-integration/quick-start-semi-integration#id-2.-internal-integration)
* [Payment App Integration Details:](https://smartpossdk.gitbook.io/paywizard-open-api/semi-integration/quick-start-semi-integration#firstheading)
sun-brightdesktopmoon
sun-brightdesktopmoon
---
# Quick Start - Online Payment | Paywizard Integration
Accept payments online, in person, and around the world with a payments solution built for any business—from scaling startups to global enterprises.
[](https://smartpossdk.gitbook.io/paywizard-open-api/online-card-payment/client-sdk-api)
**Checkout Page**
Prebuilt payment form
[](https://smartpossdk.gitbook.io/paywizard-open-api/online-card-payment/web-element-integration)
**Web Element**
Build your own payment experience
[PreviousQuery Push Statuschevron-left](https://smartpossdk.gitbook.io/paywizard-open-api/payment-parameter-varsheet-api/query-push-status)
[NextWeb Element Integrationchevron-right](https://smartpossdk.gitbook.io/paywizard-open-api/online-card-payment/web-element-integration)
Last updated 5 months ago
sun-brightdesktopmoon
sun-brightdesktopmoon
---
# Web Element Integration | Paywizard Integration
The PayWizard Web Element SDK provides a powerful and secure set of payment processing tools, helping developers easily integrate payment functionalities into web applications and **keep their system out of the PCI DSS scope.**
[hashtag](https://smartpossdk.gitbook.io/paywizard-open-api/online-card-payment/web-element-integration#overview)
Overview
-------------------------------------------------------------------------------------------------------------------------------
The PayWizard Web Element SDK is a secure and flexible payment integration solution that provides a seamless payment experience within your website using iframe technology. The SDK is designed to simplify the payment process while ensuring the highest level of security and compatibility.
###
[hashtag](https://smartpossdk.gitbook.io/paywizard-open-api/online-card-payment/web-element-integration#core-features)
Core Features
* **Secure Payment Interface** - Isolates sensitive information via iframe
* **Multiple Payment Methods** - Supports various payment options including credit cards, debit cards, etc.
* **Flexible Theme Customization** - Adapts to your website's design style
* **Payment Method Storage** - Simplifies payment process for returning customers
* **Multi-language Support** - Provides localized experience for global users
* **Responsive Design** - Offers a consistent experience across various devices
[hashtag](https://smartpossdk.gitbook.io/paywizard-open-api/online-card-payment/web-element-integration#payment-flow-overview)
Payment Flow Overview
---------------------------------------------------------------------------------------------------------------------------------------------------------
[hashtag](https://smartpossdk.gitbook.io/paywizard-open-api/online-card-payment/web-element-integration#installation-and-setup)
Installation and Setup
-----------------------------------------------------------------------------------------------------------------------------------------------------------
####
[hashtag](https://smartpossdk.gitbook.io/paywizard-open-api/online-card-payment/web-element-integration#using-script-tag)
Using Script Tag
Add the following script to the `` section of your HTML page:
####
[hashtag](https://smartpossdk.gitbook.io/paywizard-open-api/online-card-payment/web-element-integration#basic-html-structure)
Basic HTML Structure
[hashtag](https://smartpossdk.gitbook.io/paywizard-open-api/online-card-payment/web-element-integration#core-integration-steps)
Core Integration Steps
-----------------------------------------------------------------------------------------------------------------------------------------------------------
This section details the core steps for integrating the PayWizard SDK, corresponding to the interaction sequence in the Payment Flow Overview.
###
[hashtag](https://smartpossdk.gitbook.io/paywizard-open-api/online-card-payment/web-element-integration#step-1-merchant-system-creation-of-payment-order)
Step 1: Merchant System Creation of Payment Order
The first step in the payment process is to call PayWizard's "Create Online Payment Order" API on your server-side. The purpose of this API is to register a new payment transaction with the PayWizard system and obtain a `checkoutId`. This `checkoutId` is a crucial parameter required for subsequent client-side SDK initialization.
circle-exclamation
**Key Actions**
* Your server sends a request to the PayWizard server, including information such as order amount, transaction type, `redirectUrl` (for synchronous result redirection), and `notifyUrl` (for asynchronous result notification).
* The PayWizard server returns the `checkoutId` and other relevant information (corresponds to Flowchart Step 2).
For detailed API request and response format, please refer to the Create Online Payment Order API details section later in this document.
###
[hashtag](https://smartpossdk.gitbook.io/paywizard-open-api/online-card-payment/web-element-integration#step-2-client-checkout-page-sdk-initialization-and-checkout)
Step 2: Client Checkout Page SDK Initialization and Checkout
After obtaining the `checkoutId`, you need to initialize the PayWizard SDK on the client-side (the user's browser) and create a checkout session. PayWizard will validate the access and order validity and return the result to the client.
For detailed parameters of the `PayWizard()` and `initCheckout()` methods, please refer to the Client-side SDK Method Details.
###
[hashtag](https://smartpossdk.gitbook.io/paywizard-open-api/online-card-payment/web-element-integration#step-3-client-checkout-page-session-configuration-optional)
Step 3: Client Checkout Page Session Configuration (Optional)
If your system supports user accounts and you wish to leverage PayWizard's payment method storage feature (i.e., allowing users to select saved cards for payment), you can configure session parameters in this step, such as the customer identifier (`customer`) and saved payment method identifier (`card`).
If you need to retrieve the user's saved payment methods (`cardToken`), your server-side can call the Retrieve Bank Card Information by UserId API. For detailed information, please refer to the description of the `checkout.session(options)` method.
###
[hashtag](https://smartpossdk.gitbook.io/paywizard-open-api/online-card-payment/web-element-integration#step-4-client-checkout-page-rendering-of-payment-interface)
Step 4: Client Checkout Page Rendering of Payment Interface
After configuration, call the `mount` method to render PayWizard's secure payment form (in the form of an iframe) into the specified DOM element on your page.
For detailed information, please refer to the description of the `checkout.mount(selector)` method.
###
[hashtag](https://smartpossdk.gitbook.io/paywizard-open-api/online-card-payment/web-element-integration#step-5-client-checkout-page-processing-payment-and-retrieving-synchronous-result)
Step 5: Client Checkout Page Processing Payment and Retrieving Synchronous Result
When the user fills in the payment information and clicks the payment button on your page, call the `confirm` method to submit the payment (corresponds to Flowchart Step 5). PayWizard processes the payment (internally interacting with the payment channel, i.e., Flowchart Steps 6 and 7), and then returns the synchronous result to the client, or redirects to the `redirectUrl` you specified when creating the order (corresponds to Flowchart Step 8).
For detailed information, please refer to the description of the `checkout.confirm()` method.
###
[hashtag](https://smartpossdk.gitbook.io/paywizard-open-api/online-card-payment/web-element-integration#step-6-merchant-system-processing-asynchronous-notification)
Step 6: Merchant System Processing Asynchronous Notification
In addition to the synchronous result obtained by the client through the `confirm()` method (or received via `redirectUrl`), the PayWizard server will also send an asynchronous notification to the `notifyUrl` you provided in the "Create Online Payment Order" API. This ensures that your system reliably receives the final payment result even if the user closes the browser or the network is interrupted.
circle-exclamation
Your server-side needs to:
* Provide a publicly accessible `notifyUrl` endpoint.
* Receive the POST request sent by PayWizard (usually in JSON format, please refer to PayWizard's notification specifications for details).
* Verify the signature of the received notification (see PayWizard's signature verification documentation) to ensure security.
* Update the order status in your system based on the notification content (e.g., mark as payment successful, failed, etc.).
* Return a successful response (e.g., HTTP 200) to the PayWizard server, indicating that the notification has been successfully received and processed.
This step corresponds to Step 9 in the flowchart. The `notifyUrl` is set during the Create Online Payment Order API call.
[PreviousQuick Start - Online Paymentchevron-left](https://smartpossdk.gitbook.io/paywizard-open-api/online-card-payment/quick-start-online-payment)
[NextClient SDK APIchevron-right](https://smartpossdk.gitbook.io/paywizard-open-api/online-card-payment/client-sdk-api)
Last updated 5 months ago
* [Overview](https://smartpossdk.gitbook.io/paywizard-open-api/online-card-payment/web-element-integration#overview)
* [Core Features](https://smartpossdk.gitbook.io/paywizard-open-api/online-card-payment/web-element-integration#core-features)
* [Payment Flow Overview](https://smartpossdk.gitbook.io/paywizard-open-api/online-card-payment/web-element-integration#payment-flow-overview)
* [Installation and Setup](https://smartpossdk.gitbook.io/paywizard-open-api/online-card-payment/web-element-integration#installation-and-setup)
* [Core Integration Steps](https://smartpossdk.gitbook.io/paywizard-open-api/online-card-payment/web-element-integration#core-integration-steps)
* [Step 1: Merchant System Creation of Payment Order](https://smartpossdk.gitbook.io/paywizard-open-api/online-card-payment/web-element-integration#step-1-merchant-system-creation-of-payment-order)
* [Step 2: Client Checkout Page SDK Initialization and Checkout](https://smartpossdk.gitbook.io/paywizard-open-api/online-card-payment/web-element-integration#step-2-client-checkout-page-sdk-initialization-and-checkout)
* [Step 3: Client Checkout Page Session Configuration (Optional)](https://smartpossdk.gitbook.io/paywizard-open-api/online-card-payment/web-element-integration#step-3-client-checkout-page-session-configuration-optional)
* [Step 4: Client Checkout Page Rendering of Payment Interface](https://smartpossdk.gitbook.io/paywizard-open-api/online-card-payment/web-element-integration#step-4-client-checkout-page-rendering-of-payment-interface)
* [Step 5: Client Checkout Page Processing Payment and Retrieving Synchronous Result](https://smartpossdk.gitbook.io/paywizard-open-api/online-card-payment/web-element-integration#step-5-client-checkout-page-processing-payment-and-retrieving-synchronous-result)
* [Step 6: Merchant System Processing Asynchronous Notification](https://smartpossdk.gitbook.io/paywizard-open-api/online-card-payment/web-element-integration#step-6-merchant-system-processing-asynchronous-notification)
sun-brightdesktopmoon
Copy
Copy
PayWizard Integration
Copy
// Initialize the SDK with your developer Token
const payWizard = PayWizard("your-client-token");
// Create a checkout session using the checkoutId obtained from the server
async function initializeCheckout(checkoutIdFromServer) {
const checkout = await payWizard.initCheckout({
clientId: "your-client-id",
merchantId: "your-merchant-id",
checkoutId: checkoutIdFromServer, // **IMPORTANT**: Use the checkoutId returned from the server in the previous step
elementsOptions: {
appearance: {
width: "100%", // Control iframe width
theme: "light", // Optional: "light" or "night"
},
},
savePaymentMethods: true, // Enable payment method storage feature
});
// Paywizard-->>Checkout Page: 4. Validate access and order validity result (This is handled internally by initCheckout)
return checkout;
}
// Example call:
const checkout = await initializeCheckout("checkout-id-from-your-server");
Copy
// The checkout object is the instance returned from the initCheckout in the previous step
checkout.session({
customer: "customer-id-from-your-server", // Optional, your system's user ID
card: "saved-card-token-from-your-server", // Optional, Token of the saved payment method
});
Copy
Copy
// The checkout object is the instance returned from the initCheckout in the previous step
await checkout.mount("#checkout-container");
Copy
Copy
// The checkout object is the instance returned from the initCheckout in the previous step
document.getElementById("pay-button").addEventListener("click", async () => {
try {
const result = await checkout.confirm(); // Corresponds to Flowchart Step 5
console.log("Payment successful (synchronous result):", result); // Part of Flowchart Step 8
// The result object contains the transaction result.
// Handle successful payment logic based on the result, such as redirecting to a success page or displaying a success message.
// Note: If redirectUrl was specified during server-side "Create Online Payment Order",
// calling confirm may automatically redirect the page to that redirectUrl (corresponds to Flowchart Step 8).
// In this case, the redirectUrl will include query parameters: checkoutId, result, customerId (optional), cardToken (optional).
// You need to handle these parameters on the page pointed to by redirectUrl.
} catch (error) {
console.error("Payment failed (synchronous result):", error);
// Handle payment failure logic
}
});
sun-brightdesktopmoon
---
# Query Transaction Status | Paywizard Integration
[hashtag](https://smartpossdk.gitbook.io/paywizard-open-api/apm-qr-wallet/query-transaction-status#overview)
Overview
--------------------------------------------------------------------------------------------------------------------------
This endpoint allows you to query the status and details of a specific transaction using either the platform's `checkoutId` or your original `transIndexCode`.
[hashtag](https://smartpossdk.gitbook.io/paywizard-open-api/apm-qr-wallet/query-transaction-status#environments)
Environments
----------------------------------------------------------------------------------------------------------------------------------
Environment
Protocol
HTTP Method
URL
Sandbox
HTTPS
`POST`
`https://uat.paywizard.biz/ovstrade/openPay/queryOrder`
Production
HTTPS
`POST`
`https://portal.paywizard.biz/ovstrade/openPay/queryOrder`
[hashtag](https://smartpossdk.gitbook.io/paywizard-open-api/apm-qr-wallet/query-transaction-status#headers)
**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://smartpossdk.gitbook.io/paywizard-open-api/cloud-api/paywizard-open-platform-api-signature-guide-v3)
.
[hashtag](https://smartpossdk.gitbook.io/paywizard-open-api/apm-qr-wallet/query-transaction-status#request-body-parameters)
**Request Body Parameters**
------------------------------------------------------------------------------------------------------------------------------------------------------------
Parameter
Type
Required
Description
`clientId`
String
Yes
Your unique developer ID.
`checkoutId`
String
No
The unique transaction ID generated by the payment platform.
`transIndexCode`
String
No
The unique order ID that was generated by your system.
circle-exclamation
_Note: At least one of_ `_checkoutId_` _or_ `_transIndexCode_` _must be provided. If both are sent,_ `_checkoutId_` _will take precedence._
[hashtag](https://smartpossdk.gitbook.io/paywizard-open-api/apm-qr-wallet/query-transaction-status#request-example)
**Request Example**
--------------------------------------------------------------------------------------------------------------------------------------------
* * *
[hashtag](https://smartpossdk.gitbook.io/paywizard-open-api/apm-qr-wallet/query-transaction-status#response-body)
**Response Body**
----------------------------------------------------------------------------------------------------------------------------------------
The response object contains the current details of the queried transaction.
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 or if the order is not found.
`data.mid`
String
The merchant ID.
`data.paywizardId`
String
The unique platform ID for the transaction.
`data.checkoutId`
String
The unique transaction ID generated by the payment platform.
`data.transIndexCode`
String
The original third-party order ID from the request.
`data.state`
Integer
An integer code representing the current status of the transaction. See [Transaction Statesarrow-up-right](https://www.google.com/search?q=%23transaction-states)
below.
`data.amount`
String
The transaction amount.
`data.tranTime`
String
The UTC timestamp of when the transaction was successfully completed. Format: `YYYY-MM-DD HH:mm:ss`. Returned only on successful transactions.
**Transaction States**
The `state` field in the response data indicates the current status of the order.
State Code
Description
`1`
Not Paid
`2`
Payment/Operation Complete
`3`
Canceled
`4`
Refunded
`5`
Order Closed
`6`
Partially Refunded
`7`
Pre-authorization Complete
`8`
Pre-authorization Canceled
`9`
Partially Canceled
[hashtag](https://smartpossdk.gitbook.io/paywizard-open-api/apm-qr-wallet/query-transaction-status#success-response-example)
**Success Response Example**
--------------------------------------------------------------------------------------------------------------------------------------------------------------
[PreviousGenerate QR Code - Customer Scanchevron-left](https://smartpossdk.gitbook.io/paywizard-open-api/apm-qr-wallet/generate-qr-code-customer-scan)
[NextRefundchevron-right](https://smartpossdk.gitbook.io/paywizard-open-api/apm-qr-wallet/refund)
Last updated 4 months ago
* [Overview](https://smartpossdk.gitbook.io/paywizard-open-api/apm-qr-wallet/query-transaction-status#overview)
* [Environments](https://smartpossdk.gitbook.io/paywizard-open-api/apm-qr-wallet/query-transaction-status#environments)
* [Headers](https://smartpossdk.gitbook.io/paywizard-open-api/apm-qr-wallet/query-transaction-status#headers)
* [Request Body Parameters](https://smartpossdk.gitbook.io/paywizard-open-api/apm-qr-wallet/query-transaction-status#request-body-parameters)
* [Request Example](https://smartpossdk.gitbook.io/paywizard-open-api/apm-qr-wallet/query-transaction-status#request-example)
* [Response Body](https://smartpossdk.gitbook.io/paywizard-open-api/apm-qr-wallet/query-transaction-status#response-body)
* [Success Response Example](https://smartpossdk.gitbook.io/paywizard-open-api/apm-qr-wallet/query-transaction-status#success-response-example)
sun-brightdesktopmoon
Copy
{
"clientId": "825429536610058240",
"checkoutId": "202504011341223232135",
"transIndexCode": "20250401123534801"
}
Copy
{
"code": 200,
"msg": "success",
"timestamp": "2024-08-12 14:45:54",
"data": {
"mid": "10800000003",
"paywizardId": "1000000011",
"checkoutId": "768878984749514752",
"transIndexCode": "202504011341223232135",
"state": 2,
"amount": "100.21",
"tranTime": "2025-06-04 17:03:21"
}
}
sun-brightdesktopmoon
---
# Quick Pay - Merchant Scan | Paywizard Integration
[hashtag](https://smartpossdk.gitbook.io/paywizard-open-api/apm-qr-wallet/quick-pay-merchant-scan#overview)
Overview
-------------------------------------------------------------------------------------------------------------------------
This endpoint processes a payment using a customer-provided authorization code (often from a QR code or barcode on their device). This is typically used in a "merchant-scan" scenario where the merchant's point-of-sale system scans the customer's payment code.
[hashtag](https://smartpossdk.gitbook.io/paywizard-open-api/apm-qr-wallet/quick-pay-merchant-scan#environments)
Environments
---------------------------------------------------------------------------------------------------------------------------------
Environment
Protocol
HTTP Method
URL
Sandbox
HTTPS
`POST`
`https://uat.paywizard.biz/ovstrade/openPay/microPay`
Production
HTTPS
`POST`
`https://portal.paywizard.biz/ovstrade/openPay/microPay`
* * *
[hashtag](https://smartpossdk.gitbook.io/paywizard-open-api/apm-qr-wallet/quick-pay-merchant-scan#headers)
**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://smartpossdk.gitbook.io/paywizard-open-api/cloud-api/paywizard-open-platform-api-signature-guide-v3)
.
[hashtag](https://smartpossdk.gitbook.io/paywizard-open-api/apm-qr-wallet/quick-pay-merchant-scan#request-body-parameters)
**Request Body Parameters**
-----------------------------------------------------------------------------------------------------------------------------------------------------------
Parameter
Type
Required
Description
`clientId`
String
Yes
Your unique developer ID.
`transIndexCode`
String
Yes
The unique order ID generated by your system.
`scanChannel`
String
Yes
The payment channel associated with the auth code. See [Scan Channelsarrow-up-right](https://oversea.hs1c.cn/showdoc/web/#/671575440/155776416)
for valid values.
`amount`
String
Yes
The total transaction amount. Example: `"10.50"`.
`authCode`
String
Yes
The authorization code scanned from the customer's device.
`tranCurrency`
String
Yes
The 3-letter ISO currency code for the transaction. Example: `"USD"`.
`productDesc`
String
No
A brief description of the product(s) or service(s).
`payerType`
String
Conditionally Required
The type of payer identifier. Valid values: `MSISDN`, `EMAIL`, `PARTY_CODE`. Required when `scanChannel` is `MOMO`.
`notifyUrl`
String
No
The callback URL where you will receive the final transaction result notification.
[hashtag](https://smartpossdk.gitbook.io/paywizard-open-api/apm-qr-wallet/quick-pay-merchant-scan#request-example)
**Request Example**
-------------------------------------------------------------------------------------------------------------------------------------------
* * *
[hashtag](https://smartpossdk.gitbook.io/paywizard-open-api/apm-qr-wallet/quick-pay-merchant-scan#response-body)
**Response Body**
---------------------------------------------------------------------------------------------------------------------------------------
The response object contains the status of the request and the transaction details.
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 unique transaction ID generated by the payment platform.
`data.transIndexCode`
String
The original third-party order ID from the request.
`data.result`
Integer
The status of the transaction. `0`: Success `1`: Failure `2`: Pending
`data.amount`
String
The transaction amount.
[hashtag](https://smartpossdk.gitbook.io/paywizard-open-api/apm-qr-wallet/quick-pay-merchant-scan#success-response-example)
**Success Response Example**
-------------------------------------------------------------------------------------------------------------------------------------------------------------
_Note: The parameter_ `_state_` _in the example below corresponds to_ `_result_` _in the documentation._
[PreviousAPM (QR/WALLET) APIchevron-left](https://smartpossdk.gitbook.io/paywizard-open-api/apm-qr-wallet/quick-start-qr-payment-api-integration/apm-qr-wallet-api)
[NextGenerate QR Code - Customer Scanchevron-right](https://smartpossdk.gitbook.io/paywizard-open-api/apm-qr-wallet/generate-qr-code-customer-scan)
Last updated 4 months ago
* [Overview](https://smartpossdk.gitbook.io/paywizard-open-api/apm-qr-wallet/quick-pay-merchant-scan#overview)
* [Environments](https://smartpossdk.gitbook.io/paywizard-open-api/apm-qr-wallet/quick-pay-merchant-scan#environments)
* [Headers](https://smartpossdk.gitbook.io/paywizard-open-api/apm-qr-wallet/quick-pay-merchant-scan#headers)
* [Request Body Parameters](https://smartpossdk.gitbook.io/paywizard-open-api/apm-qr-wallet/quick-pay-merchant-scan#request-body-parameters)
* [Request Example](https://smartpossdk.gitbook.io/paywizard-open-api/apm-qr-wallet/quick-pay-merchant-scan#request-example)
* [Response Body](https://smartpossdk.gitbook.io/paywizard-open-api/apm-qr-wallet/quick-pay-merchant-scan#response-body)
* [Success Response Example](https://smartpossdk.gitbook.io/paywizard-open-api/apm-qr-wallet/quick-pay-merchant-scan#success-response-example)
sun-brightdesktopmoon
Copy
{
"clientId": "825429536610058240",
"transIndexCode": "20250401123534801",
"scanChannel": "M_PAY",
"amount": "10.50",
"authCode": "awrawfsfegojpenmfkapowngpawngpgrigawfnrtujgpsn",
"tranCurrency": "USD"
}
Copy
{
"code": 200,
"msg": "success",
"timestamp": "2024-08-12 14:45:54",
"data": {
"mid": "10800000003",
"paywizardId": "1000000011",
"checkoutId": "768878984749514752",
"transIndexCode": "202504011341223232135",
"state": 0,
"amount": "100.21"
}
}
sun-brightdesktopmoon
---
# Generate QR Code - Customer Scan | Paywizard Integration
[hashtag](https://smartpossdk.gitbook.io/paywizard-open-api/apm-qr-wallet/generate-qr-code-customer-scan#overview)
Overview
--------------------------------------------------------------------------------------------------------------------------------
This endpoint allows you to generate a QR code for a "customer-scan" payment scenario. The customer scans the generated QR code with their device to complete the payment.
[hashtag](https://smartpossdk.gitbook.io/paywizard-open-api/apm-qr-wallet/generate-qr-code-customer-scan#environments)
Environments
----------------------------------------------------------------------------------------------------------------------------------------
Environment
Protocol
HTTP Method
URL
Sandbox
HTTPS
`POST`
`https://uat.paywizard.biz/ovstrade/openPay/generateQrCode`
Production
HTTPS
`POST`
`https://portal.paywizard.biz/ovstrade/openPay/generateQrCode`
[hashtag](https://smartpossdk.gitbook.io/paywizard-open-api/apm-qr-wallet/generate-qr-code-customer-scan#headers)
**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://smartpossdk.gitbook.io/paywizard-open-api/cloud-api/paywizard-open-platform-api-signature-guide-v3)
.
[hashtag](https://smartpossdk.gitbook.io/paywizard-open-api/apm-qr-wallet/generate-qr-code-customer-scan#request-body-parameters)
**Request Body Parameters**
------------------------------------------------------------------------------------------------------------------------------------------------------------------
Parameter
Type
Required
Description
`clientId`
String
Yes
Your unique developer ID.
`transIndexCode`
String
Yes
The unique order ID generated by your system.
`payChannel`
String
Yes
The payment channel to be used. See [Payment Channelsarrow-up-right](https://oversea.hs1c.cn/showdoc/web/#/671575440/155776416)
for valid values.
`amount`
String
Yes
The total transaction amount. Example: `"10.50"`.
`currency`
String
Yes
The 3-letter ISO currency code for the transaction amount. For PIX transactions, this must be `BRL`.
`exchangeCurrency`
String
Conditionally Required
The currency code for settlement. Valid values: `BRL`, `USD`, `EUR`. Required for PIX transactions. Currently only `BRL` is supported.
`documentNumber`
String
Conditionally Required
The customer's tax identification number (e.g., CPF or CNPJ). Required for PIX transactions.
`socialName`
String
Conditionally Required
The full name of the customer. Required for PIX transactions.
`dynamicPixExpiresAt`
String
No
The expiration timestamp for a dynamic PIX QR code in ISO 8601 format: `YYYY-MM-DDTHH:mm:ssZ`.
`productDesc`
String
No
A brief description of the product(s) or service(s).
`notifyUrl`
String
No
The callback URL where you will receive the transaction result notification.
[hashtag](https://smartpossdk.gitbook.io/paywizard-open-api/apm-qr-wallet/generate-qr-code-customer-scan#request-example)
**Request Example**
--------------------------------------------------------------------------------------------------------------------------------------------------
* * *
[hashtag](https://smartpossdk.gitbook.io/paywizard-open-api/apm-qr-wallet/generate-qr-code-customer-scan#response-body)
**Response Body**
----------------------------------------------------------------------------------------------------------------------------------------------
The response object contains the status of the request and, upon success, the data needed to display the payment QR code.
Parameter
Type
Description
`code`
Integer
The HTTP status code. `200` indicates success. 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 unique transaction ID generated by the payment platform.
`data.transIndexCode`
String
The original third-party order ID from the request.
`data.qrCode`
String
The raw data string for the payment QR code. This should be used to generate the QR code image.
`data.amount`
String
The transaction amount.
[hashtag](https://smartpossdk.gitbook.io/paywizard-open-api/apm-qr-wallet/generate-qr-code-customer-scan#success-response-example)
**Success Response Example**
--------------------------------------------------------------------------------------------------------------------------------------------------------------------
[PreviousQuick Pay - Merchant Scanchevron-left](https://smartpossdk.gitbook.io/paywizard-open-api/apm-qr-wallet/quick-pay-merchant-scan)
[NextQuery Transaction Statuschevron-right](https://smartpossdk.gitbook.io/paywizard-open-api/apm-qr-wallet/query-transaction-status)
Last updated 4 months ago
* [Overview](https://smartpossdk.gitbook.io/paywizard-open-api/apm-qr-wallet/generate-qr-code-customer-scan#overview)
* [Environments](https://smartpossdk.gitbook.io/paywizard-open-api/apm-qr-wallet/generate-qr-code-customer-scan#environments)
* [Headers](https://smartpossdk.gitbook.io/paywizard-open-api/apm-qr-wallet/generate-qr-code-customer-scan#headers)
* [Request Body Parameters](https://smartpossdk.gitbook.io/paywizard-open-api/apm-qr-wallet/generate-qr-code-customer-scan#request-body-parameters)
* [Request Example](https://smartpossdk.gitbook.io/paywizard-open-api/apm-qr-wallet/generate-qr-code-customer-scan#request-example)
* [Response Body](https://smartpossdk.gitbook.io/paywizard-open-api/apm-qr-wallet/generate-qr-code-customer-scan#response-body)
* [Success Response Example](https://smartpossdk.gitbook.io/paywizard-open-api/apm-qr-wallet/generate-qr-code-customer-scan#success-response-example)
sun-brightdesktopmoon
Copy
{
"clientId": "825429536610058240",
"transIndexCode": "12313254654120",
"payChannel": "PIX",
"amount": "0.01",
"currency": "BRL",
"exchangeCurrency": "USD",
"documentNumber": "12345678900",
"socialName": "John Doe",
"dynamicPixExpiresAt": "2025-06-25T16:30:09.845Z",
"notifyUrl": "https://oversea.hs1c.cn/xxx/thirdNotify/callback"
}
Copy
{
"code": 200,
"msg": "success",
"timestamp": "2024-08-12 14:45:54",
"data": {
"mid": "10800000003",
"paywizardId": "1000000011",
"checkoutId": "768878984749514752",
"transIndexCode": "202504011341223232135",
"qrCode": "00020101021226990014br.gov.bcb.pix2577pix.bancogenial.com/qrs1/v2/017si5czJTt4zOys319ukH9l1UD8m94JJ0xnElX3Bc6rMK3ug52040000530398654041.005802BR5923FACILITA PAGAMENTOS S/A6009SAO PAULO62070503***6304B8B8",
"amount": "100.21"
}
}
sun-brightdesktopmoon
---
# TSYS Transit Parameter Push | Paywizard Integration
[hashtag](https://smartpossdk.gitbook.io/paywizard-open-api/payment-parameter-varsheet-api/tsys-transit-parameter-push#overview)
Overview
----------------------------------------------------------------------------------------------------------------------------------------------
This endpoint is used to upload and push TSYS Trasit payment configuration parameters to a specific terminal.
[hashtag](https://smartpossdk.gitbook.io/paywizard-open-api/payment-parameter-varsheet-api/tsys-transit-parameter-push#environments)
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`
####
[hashtag](https://smartpossdk.gitbook.io/paywizard-open-api/payment-parameter-varsheet-api/tsys-transit-parameter-push#authentication)
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 Guidearrow-up-right](https://oversea.hs1c.cn/showdoc/web/#/671575440/155776446)
.
* * *
####
[hashtag](https://smartpossdk.gitbook.io/paywizard-open-api/payment-parameter-varsheet-api/tsys-transit-parameter-push#endpoint-push-tsys-trasit-configuration)
Endpoint: Push TSYS Trasit Configuration
`POST /ovstrade/openVarSheet/tsystrasit/configuration/push`
[hashtag](https://smartpossdk.gitbook.io/paywizard-open-api/payment-parameter-varsheet-api/tsys-transit-parameter-push#headers)
**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 Guidearrow-up-right](https://oversea.hs1c.cn/showdoc/web/#/671575440/155776446)
.
[hashtag](https://smartpossdk.gitbook.io/paywizard-open-api/payment-parameter-varsheet-api/tsys-transit-parameter-push#request-body-parameters)
**Request Body Parameters**
--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
###
[hashtag](https://smartpossdk.gitbook.io/paywizard-open-api/payment-parameter-varsheet-api/tsys-transit-parameter-push#root-parameters)
**Root Parameters**
Name
Type
Description
Mandatory
`clientId`
string
Unique Developer ID.
check
`pushData`
object
The data object to be pushed.
check
`pushData.terminalSn`
string
Terminal Serial Number (SN).
check
`pushData.paymentAppParams`
object
Payment application specific parameters (see details below).
check
**Detailed Configuration Parameters (paymentAppParams Structure)**
For clarity, parameters are categorized by function:
####
[hashtag](https://smartpossdk.gitbook.io/paywizard-open-api/payment-parameter-varsheet-api/tsys-transit-parameter-push#id-1.-password-information-tsyspasswordinformation)
1\. Password Information (tsysPasswordInformation)
Name
Type
Description
Mandatory
adminPass
string
Administrator Password
merchantPass
string
Merchant Password
superPass
string
Super Password
refundPass
string
Refund Password
reversalPass
string
Reversal Password
####
[hashtag](https://smartpossdk.gitbook.io/paywizard-open-api/payment-parameter-varsheet-api/tsys-transit-parameter-push#id-2.-merchant-parameters-tsysmerchantparam)
2\. Merchant Parameters (tsysMerchantParam)
Name
Type
Description
Mandatory
userId
string
Merchant Center User ID
check
userPassword
string
Merchant Center User Password
check
merchantID
string
Merchant ID (MID)
check
deviceId
string
Device ID (TID)
check
legalName
string
Legal Name
dbaName
string
DBA Name (Doing Business As)
check
legalAddr
string
Legal Address
dbaAddr
string
DBA Address
check
merchantCity
string
City
check
merchantState
string
State
check
merchantPostal
string
Postal/Zip Code
check
merchantCountryCode
string
Merchant Country Code (e.g., USA)
check
countryCode
string
Country Code (Numeric, e.g., 840)
check
currencyCode
string
Currency Code (Numeric, e.g., 840)
check
merchantPhone
string
Merchant Phone Number
check
merchantEmail
string
Merchant Email
check
merchantCategoryCode
string
MCC (Merchant Category Code)
check
developerId
string
Developer ID
unattended
string
Unattended Terminal Flag
check
facilitatorId
string
Facilitator ID
acqInterRefNo
string
Acquirer Internal Reference Number
bannerUrls
string
Banner Image URLs
ebtFcsid
string
EBT FCSID
####
[hashtag](https://smartpossdk.gitbook.io/paywizard-open-api/payment-parameter-varsheet-api/tsys-transit-parameter-push#id-3.-merchant-settings-tsysmerchantsetting)
3\. Merchant Settings (tsysMerchantSetting)
Name
Type
Description
Mandatory
autoSettle
string
Auto Settle (1: Enable, 0: Disable)
businessCloseTime
string
Business Close Time (for settlement)
printReceipt
string
Print Receipt
checkPaper
string
Check for Paper
enableTip
string
Enable Tipping
tipDefault
string
Default Tip Amount
restrictMaxTipAmount
string
Restrict Maximum Tip Amount
maxTipAmount
string
Maximum Tip Amount
enableTax
string
Enable Tax
taxDefault
string
Default Tax Rate
surchargeEnable
string
Enable Surcharge
enableCashDiscount
string
Enable Cash Discount
cashDiscountPercentage
string
Cash Discount Percentage
addTipLineOnReceipt
string
Add Tip Line on Receipt
requireSignature
string
Require Signature
hideAllMenu
string
Hide All Menus
####
[hashtag](https://smartpossdk.gitbook.io/paywizard-open-api/payment-parameter-varsheet-api/tsys-transit-parameter-push#id-4.-network-parameters-tsysnetworkparam)
4\. Network Parameters (tsysNetworkParam)
Name
Type
Description
Mandatory
primIp
string
Primary IP/Gateway URL
####
[hashtag](https://smartpossdk.gitbook.io/paywizard-open-api/payment-parameter-varsheet-api/tsys-transit-parameter-push#id-5.-terminal-parameters-tsysterminalparam)
5\. Terminal Parameters (tsysTerminalParam)
Name
Type
Description
Mandatory
tmkIndex
string
TMK Key Index
traceNo
string
Trace Number
batchNumber
string
Batch Number
enableAutoCloseBatch
string
Enable Auto Close Batch
autoCloseBatchTime
string
Auto Close Batch Time
transExpiredDays
string
Transaction Expiration Days
facilitatorEnable
string
Enable Facilitator Mode
isIsLevelTwo
string
Is Level 2 Data Supported
isEstimated
string
Is Estimated
isDefender
string
Is Defender
forceOnlinePin
string
Force Online PIN
qpsAmount
string
QPS Amount Limit
tacDenial
string
TAC Denial Code
tacOnline
string
TAC Online Code
tacDefault
string
TAC Default Code
contactlessLimit
string
Contactless Limit
contactlessCVM
string
Contactless CVM Limit
check
contactlessFloor
string
Contactless Floor Limit
terminalFloor
string
Terminal Floor Limit
riskManageData
string
Risk Management Data
terminalCap
string
Terminal Capabilities
cvmCapNoCvm
string
CVM Capabilities (No CVM)
cvmCapOnCvm
string
CVM Capabilities (On CVM)
kernelConfig
string
Kernel Configuration
extLogData
string
Extended Log Data
containerList
string
Container List
aidHighestPriority
string
AID Highest Priority
supportMsr
string
Support MSR (Magnetic Stripe)
check
quickChip
string
Enable Quick Chip
supportIds
string
Support IDS
supportMaestro
string
Support Maestro
check
supportUSMaestro
string
Support US Maestro
check
supportAmex
string
Support Amex
check
supportUploadReceipt
string
Support Receipt Upload
maxTrans
string
Maximum Transactions per Batch
####
[hashtag](https://smartpossdk.gitbook.io/paywizard-open-api/payment-parameter-varsheet-api/tsys-transit-parameter-push#id-6.-supported-transaction-types-tsyssupportedtrans)
6\. Supported Transaction Types (tsysSupportedTrans)
Fields in this section are typically set to "1" (Supported) or "0" (Not Supported).
Name
Type
Description
Mandatory
creditSale
string
Credit Sale
debitSale
string
Debit Sale
forceAuth
string
Force Auth
creditReturn
string
Credit Return
debitReturn
string
Debit Return
reversalMenu
string
Reversal Menu
printMenu
string
Print Menu
moreFunctionMenu
string
More Functions Menu
authOnly
string
Auth Only
authIncrement
string
Auth Increment
tipAdjust
string
Tip Adjust
capture
string
Capture
closeBatch
string
Close Batch
* * *
[hashtag](https://smartpossdk.gitbook.io/paywizard-open-api/payment-parameter-varsheet-api/tsys-transit-parameter-push#request-example)
**Request Example**
----------------------------------------------------------------------------------------------------------------------------------------------------------------
_Note: The_ `_paymentAppParams_` _object is extensive. This example shows the complete structure._
* * *
[hashtag](https://smartpossdk.gitbook.io/paywizard-open-api/payment-parameter-varsheet-api/tsys-transit-parameter-push#response-body)
**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 Codesarrow-up-right](https://www.google.com/search?q=%23push-status-codes)
below.
###
[hashtag](https://smartpossdk.gitbook.io/paywizard-open-api/payment-parameter-varsheet-api/tsys-transit-parameter-push#push-status-codes)
**Push Status Codes**
Status Code
Description
`0`
In Progress (Parameters are being pushed)
`1`
Success (Parameters were pushed successfully)
`2`
Failure (Parameter push failed)
[hashtag](https://smartpossdk.gitbook.io/paywizard-open-api/payment-parameter-varsheet-api/tsys-transit-parameter-push#success-response-example)
**Success Response Example**
----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
[PreviousQuick Start - Payment Parameter Pushchevron-left](https://smartpossdk.gitbook.io/paywizard-open-api/payment-parameter-varsheet-api/quick-start-payment-parameter-push)
[NextFiserv Parameter Pushchevron-right](https://smartpossdk.gitbook.io/paywizard-open-api/payment-parameter-varsheet-api/fiserv-parameter-push)
Last updated 6 days ago
* [Overview](https://smartpossdk.gitbook.io/paywizard-open-api/payment-parameter-varsheet-api/tsys-transit-parameter-push#overview)
* [Environments](https://smartpossdk.gitbook.io/paywizard-open-api/payment-parameter-varsheet-api/tsys-transit-parameter-push#environments)
* [Headers](https://smartpossdk.gitbook.io/paywizard-open-api/payment-parameter-varsheet-api/tsys-transit-parameter-push#headers)
* [Request Body Parameters](https://smartpossdk.gitbook.io/paywizard-open-api/payment-parameter-varsheet-api/tsys-transit-parameter-push#request-body-parameters)
* [Root Parameters](https://smartpossdk.gitbook.io/paywizard-open-api/payment-parameter-varsheet-api/tsys-transit-parameter-push#root-parameters)
* [Request Example](https://smartpossdk.gitbook.io/paywizard-open-api/payment-parameter-varsheet-api/tsys-transit-parameter-push#request-example)
* [Response Body](https://smartpossdk.gitbook.io/paywizard-open-api/payment-parameter-varsheet-api/tsys-transit-parameter-push#response-body)
* [Push Status Codes](https://smartpossdk.gitbook.io/paywizard-open-api/payment-parameter-varsheet-api/tsys-transit-parameter-push#push-status-codes)
* [Success Response Example](https://smartpossdk.gitbook.io/paywizard-open-api/payment-parameter-varsheet-api/tsys-transit-parameter-push#success-response-example)
sun-brightdesktopmoon
Copy
{
"clientId": "825420368247390000",
"pushData": {
"terminalSn": "WP2310PQ20000000",
"paymentAppParams": {
"tsysPasswordInformation": {
"adminPass": "99999999",
"merchantPass": "1234",
"superPass": "123456",
"refundPass": "5555",
"reversalPass": "5555"
},
"tsysMerchantParam": {
"userId": "",
"userPassword": "",
"merchantID": "",
"deviceId": "",
"legalName": "",
"dbaName": "",
"legalAddr": "",
"dbaAddr": "",
"merchantCity": "",
"merchantState": "",
"merchantPostal": "",
"merchantCountryCode": "USA",
"countryCode": "840",
"currencyCode": "840",
"merchantPhone": "",
"merchantEmail": "",
"merchantCategoryCode": "",
"developerId": "003546G004",
"unattended": "0",
"facilitatorId": "123",
"acqInterRefNo": "",
"bannerUrls": "",
"ebtFcsid": ""
},
"tsysMerchantSetting": {
"autoSettle": "1",
"businessCloseTime": "",
"printReceipt": "0",
"checkPaper": "0",
"enableTip": "0",
"tipDefault": "",
"restrictMaxTipAmount": "0",
"maxTipAmount": "",
"enableTax": "0",
"taxDefault": "",
"surchargeEnable": "0",
"enableCashDiscount": "0",
"cashDiscountPercentage": "",
"addTipLineOnReceipt": "0",
"requireSignature": "0",
"hideAllMenu": "0"
},
"tsysNetworkParam": {
"primIp": "https://gateway.transit-pass.com/servlets/"
},
"tsysTerminalParam": {
"tmkIndex": "7",
"traceNo": "1",
"batchNumber": "1",
"enableAutoCloseBatch": "0",
"autoCloseBatchTime": "00:00",
"transExpiredDays": "30",
"facilitatorEnable": "0",
"isIsLevelTwo": "0",
"isEstimated": "0",
"isDefender": "0",
"forceOnlinePin": "0",
"qpsAmount": "0",
"tacDenial": "0010000000",
"tacOnline": "DE00FC9800",
"tacDefault": "DC50FC9800",
"contactlessLimit": "99999999",
"contactlessCVM": "10000",
"contactlessFloor": "0",
"terminalFloor": "0",
"riskManageData": "4C00800000000000",
"terminalCap": "A008C8",
"cvmCapNoCvm": "08",
"cvmCapOnCvm": "08",
"kernelConfig": "B0",
"extLogData": "FFFFFFFFFFFFFFFF",
"containerList": "000000010000010100000201",
"aidHighestPriority": "1",
"supportMsr": "0",
"quickChip": "1",
"supportIds": "1",
"supportMaestro": "1",
"supportUSMaestro": "1",
"supportAmex": "1",
"supportUploadReceipt": "0",
"maxTrans": "999"
},
"tsysSupportedTrans": {
"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"
}
}
}
}
Copy
{
"code": 200,
"msg": "success",
"timestamp": "2024-08-12 14:45:54",
"data": {
"pushId": "768206988353077248",
"status": 0
}
}
sun-brightdesktopmoon
---
# VOID | Paywizard Integration
[hashtag](https://smartpossdk.gitbook.io/paywizard-open-api/apm-qr-wallet/void#overview)
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.
circle-exclamation
Note: Partial reversals are not supported by all payment channels.
[hashtag](https://smartpossdk.gitbook.io/paywizard-open-api/apm-qr-wallet/void#environments)
Environments
--------------------------------------------------------------------------------------------------------------
Environment
Protocol
HTTP Method
URL
Sandbox
HTTPS
`POST`
`https://uat.paywizard.biz/ovstrade/openPay/reversalOrder`
Production
HTTPS
`POST`
`https://portal.paywizard.biz/ovstrade/openPay/reversalOrder`
[hashtag](https://smartpossdk.gitbook.io/paywizard-open-api/apm-qr-wallet/void#headers)
**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 Guidearrow-up-right](https://oversea.hs1c.cn/showdoc/web/#/671575440/155776446)
.
[hashtag](https://smartpossdk.gitbook.io/paywizard-open-api/apm-qr-wallet/void#request-body-parameters)
**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.
circle-exclamation
_Note: You must provide at least one of the original identifiers (_`_oriCheckoutId_` _or_ `_oriTransIndexCode_`_). If both are sent,_ `_oriCheckoutId_` _will take precedence._
[hashtag](https://smartpossdk.gitbook.io/paywizard-open-api/apm-qr-wallet/void#request-example)
**Request Example**
------------------------------------------------------------------------------------------------------------------------
* * *
[hashtag](https://smartpossdk.gitbook.io/paywizard-open-api/apm-qr-wallet/void#response-body)
**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 Codesarrow-up-right](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.
[hashtag](https://smartpossdk.gitbook.io/paywizard-open-api/apm-qr-wallet/void#reversal-status-codes)
**Reversal Status Codes**
------------------------------------------------------------------------------------------------------------------------------------
The `result` field indicates the immediate outcome of the reversal request. The final status may be delivered via the `notifyUrl`.
Result Code
Description
`0`
Success
`1`
Failure
`2`
Pending / In Progress
[hashtag](https://smartpossdk.gitbook.io/paywizard-open-api/apm-qr-wallet/void#success-response-example)
**Success Response Example**
------------------------------------------------------------------------------------------------------------------------------------------
[PreviousRefundchevron-left](https://smartpossdk.gitbook.io/paywizard-open-api/apm-qr-wallet/refund)
[NextClose Orderchevron-right](https://smartpossdk.gitbook.io/paywizard-open-api/apm-qr-wallet/close-order)
Last updated 4 months ago
* [Overview](https://smartpossdk.gitbook.io/paywizard-open-api/apm-qr-wallet/void#overview)
* [Environments](https://smartpossdk.gitbook.io/paywizard-open-api/apm-qr-wallet/void#environments)
* [Headers](https://smartpossdk.gitbook.io/paywizard-open-api/apm-qr-wallet/void#headers)
* [Request Body Parameters](https://smartpossdk.gitbook.io/paywizard-open-api/apm-qr-wallet/void#request-body-parameters)
* [Request Example](https://smartpossdk.gitbook.io/paywizard-open-api/apm-qr-wallet/void#request-example)
* [Response Body](https://smartpossdk.gitbook.io/paywizard-open-api/apm-qr-wallet/void#response-body)
* [Reversal Status Codes](https://smartpossdk.gitbook.io/paywizard-open-api/apm-qr-wallet/void#reversal-status-codes)
* [Success Response Example](https://smartpossdk.gitbook.io/paywizard-open-api/apm-qr-wallet/void#success-response-example)
sun-brightdesktopmoon
Copy
{
"clientId": "825429536610058240",
"transIndexCode": "202506091432000000013",
"oriCheckoutId": "917121926164512768",
"amount": "0.01"
}
Copy
{
"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"
}
}
sun-brightdesktopmoon
---
# Redeem Points | Paywizard Integration
####
[hashtag](https://smartpossdk.gitbook.io/paywizard-open-api/loyalty/redeem-points#overview)
Overview
This endpoint is used to redeem (or consume) loyalty points from a customer's prepaid card. This is the counterpart to the "Add Points" operation.
####
[hashtag](https://smartpossdk.gitbook.io/paywizard-open-api/loyalty/redeem-points#environments)
Environments
Environment
Protocol
HTTP Method
URL
Sandbox
HTTPS
`POST`
`https://uat.paywizard.biz/ovstrade/openLoyaltyPay/loyaltyRedemption`
Production
HTTPS
`POST`
`https://portal.paywizard.biz/ovstrade/openLoyaltyPay/loyaltyRedemption`
####
[hashtag](https://smartpossdk.gitbook.io/paywizard-open-api/loyalty/redeem-points#authentication)
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 Guidearrow-up-right](https://oversea.hs1c.cn/showdoc/web/#/671575440/155776446)
.
* * *
####
[hashtag](https://smartpossdk.gitbook.io/paywizard-open-api/loyalty/redeem-points#endpoint-redeem-loyalty-points)
Endpoint: Redeem Loyalty Points
`POST /ovstrade/openLoyaltyPay/loyaltyRedemption`
**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 Guidearrow-up-right](https://oversea.hs1c.cn/showdoc/web/#/671575440/155776446)
.
**Request Body Parameters**
Parameter
Type
Required
Description
`clientId`
String
Yes
Your unique developer ID.
`tranOrderNo`
String
Yes
The unique order ID for this points redemption transaction, generated by your system.
`loyaltyChannel`
String
Yes
The prepaid channel provider. See [Prepaid Channelsarrow-up-right](https://oversea.hs1c.cn/showdoc/web/#/671575440/155776425)
for valid values.
`accountId`
String
Yes
The unique identifier for the prepaid card.
`entryType`
String
Yes
The method used to input the `accountId`. See [Entry Type Codesarrow-up-right](https://www.google.com/search?q=%23entry-type-codes)
below.
`amount`
String
Yes
The number of loyalty points to redeem from the card.
**Entry Type Codes**
Code
Description
`B`
Barcode
`K`
Keyed (manually entered)
`M`
Magnetic Stripe
`P`
Proximity (NFC/Contactless)
**Request Example**
JSON
* * *
**Response Body**
The response object contains the status of the points redemption transaction.
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.mid`
String
The merchant ID.
`data.paywizardId`
String
The unique platform ID for the transaction.
`data.checkoutId`
String
The unique transaction ID generated by the payment platform.
`data.transIndexCode`
String
A unique transaction reference code.
`data.amount`
String
The number of points that were redeemed.
`data.result`
Integer
An integer code representing the status of the transaction. See [Transaction Status Codesarrow-up-right](https://www.google.com/search?q=%23transaction-status-codes)
below.
**Transaction Status Codes**
The `result` field indicates the immediate outcome of the points redemption request.
Result Code
Description
`0`
Success
`1`
Failure
`2`
Pending / In Progress
**Success Response Example**
JSON
[PreviousIssue Pointschevron-left](https://smartpossdk.gitbook.io/paywizard-open-api/loyalty/issue-points)
[NextAdd Tipchevron-right](https://smartpossdk.gitbook.io/paywizard-open-api/loyalty/add-tip)
Last updated 5 months ago
sun-brightdesktopmoon
Copy
{
"clientId": "825429536610058240",
"tranOrderNo": "20250401123534801",
"loyaltyChannel": "FACTOR4",
"accountId": "914639258868515",
"entryType": "K",
"amount": "1"
}
Copy
{
"code": 200,
"msg": "success",
"timestamp": "2025-07-24 16:22:29",
"data": {
"mid": "202507081058",
"paywizardId": "10020000080",
"checkoutId": "933442205362814976",
"transIndexCode": "100200000805876553413",
"amount": "10000",
"result": 0
}
}
sun-brightdesktopmoon
---
# Add Tip | Paywizard Integration
####
[hashtag](https://smartpossdk.gitbook.io/paywizard-open-api/loyalty/add-tip#overview)
Overview
This endpoint is used to add a tip to a previously completed prepaid card transaction. This is often used in restaurant or service environments where the tip amount is determined after the initial payment is made.
####
[hashtag](https://smartpossdk.gitbook.io/paywizard-open-api/loyalty/add-tip#environments)
Environments
Environment
Protocol
HTTP Method
URL
Sandbox
HTTPS
`POST`
`https://uat.paywizard.biz/ovstrade/openLoyaltyPay/giftTip`
Production
HTTPS
`POST`
`https://portal.paywizard.biz/ovstrade/openLoyaltyPay/giftTip`
####
[hashtag](https://smartpossdk.gitbook.io/paywizard-open-api/loyalty/add-tip#authentication)
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 Guidearrow-up-right](https://oversea.hs1c.cn/showdoc/web/#/671575440/155776446)
.
* * *
####
[hashtag](https://smartpossdk.gitbook.io/paywizard-open-api/loyalty/add-tip#endpoint-add-tip-to-prepaid-transaction)
Endpoint: Add Tip to Prepaid Transaction
`POST /ovstrade/openLoyaltyPay/giftTip`
**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 Guidearrow-up-right](https://oversea.hs1c.cn/showdoc/web/#/671575440/155776446)
.
**Request Body Parameters**
Parameter
Type
Required
Description
`clientId`
String
Yes
Your unique developer ID.
`tranOrderNo`
String
Yes
A new, unique order ID for this specific tip transaction, generated by your system.
`oriOrderNo`
String
Yes
The `checkoutId` of the original payment transaction to which the tip is being added.
`tranCurrency`
String
Yes
The 3-letter ISO currency code for the tip amount. Example: `"USD"`.
`amount`
String
Yes
The tip amount to be added.
`accountId`
String
Yes
The unique identifier for the prepaid card used in the original transaction.
`entryType`
String
Yes
The method used to input the `accountId`. See [Entry Type Codesarrow-up-right](https://www.google.com/search?q=%23entry-type-codes)
below.
**Entry Type Codes**
Code
Description
`B`
Barcode
`K`
Keyed (manually entered)
`M`
Magnetic Stripe
`P`
Proximity (NFC/Contactless)
**Request Example**
JSON
* * *
**Response Body**
The response object contains the status of the tip adjustment transaction.
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.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 tip adjustment, generated by the payment platform.
`data.transIndexCode`
String
A unique transaction reference code.
`data.amount`
String
The tip amount that was processed.
`data.result`
Integer
An integer code representing the status of the transaction. See [Transaction Status Codesarrow-up-right](https://www.google.com/search?q=%23transaction-status-codes)
below.
**Transaction Status Codes**
The `result` field indicates the immediate outcome of the tip adjustment request.
Result Code
Description
`0`
Success
`1`
Failure
`2`
Pending / In Progress
**Success Response Example**
JSON
[PreviousRedeem Pointschevron-left](https://smartpossdk.gitbook.io/paywizard-open-api/loyalty/redeem-points)
Last updated 5 months ago
sun-brightdesktopmoon
Copy
{
"clientId": "825429536610058240",
"tranOrderNo": "20250401123534801",
"accountId": "914639258868515",
"entryType": "K",
"amount": "2.00",
"tranCurrency": "USD",
"oriOrderNo": "927994263952818176"
}
Copy
{
"code": 200,
"msg": "success",
"timestamp": "2025-07-24 17:09:24",
"data": {
"mid": "202507081058",
"paywizardId": "10020000080",
"checkoutId": "933454027025416192",
"transIndexCode": "100200000800256343351",
"amount": "20000",
"result": 0
}
}
sun-brightdesktopmoon
---
# Void | Paywizard Integration
[hashtag](https://smartpossdk.gitbook.io/paywizard-open-api/loyalty/void#overview)
Overview
------------------------------------------------------------------------------------------------
This endpoint is used to void a prior prepaid card transaction, such as a payment or a reload. A void typically cancels a transaction before it has been settled, effectively reversing the original operation.
[hashtag](https://smartpossdk.gitbook.io/paywizard-open-api/loyalty/void#environments)
Environments
--------------------------------------------------------------------------------------------------------
Environment
Protocol
HTTP Method
URL
Sandbox
HTTPS
`POST`
`https://uat.paywizard.biz/ovstrade/openLoyaltyPay/giftVoid`
Production
HTTPS
`POST`
`https://portal.paywizard.biz/ovstrade/openLoyaltyPay/giftVoid`
[hashtag](https://smartpossdk.gitbook.io/paywizard-open-api/loyalty/void#headers)
**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://smartpossdk.gitbook.io/paywizard-open-api/cloud-api/paywizard-open-platform-api-signature-guide-v3)
.
[hashtag](https://smartpossdk.gitbook.io/paywizard-open-api/loyalty/void#request-body-parameters)
**Request Body Parameters**
----------------------------------------------------------------------------------------------------------------------------------
Parameter
Type
Required
Description
`clientId`
String
Yes
Your unique developer ID.
`tranOrderNo`
String
Yes
A new, unique order ID for this specific void request, generated by your system.
`oriOrderNo`
String
Yes
The `checkoutId` of the original prepaid transaction you want to void.
[hashtag](https://smartpossdk.gitbook.io/paywizard-open-api/loyalty/void#request-example)
**Request Example**
------------------------------------------------------------------------------------------------------------------
* * *
**Response Body**
The response object contains the status of the void transaction request.
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.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 void, generated by the payment platform.
`data.transIndexCode`
String
The unique void order ID that you provided in the request.
`data.oriCheckoutId`
String
The `checkoutId` of the original transaction that was voided.
`data.oriTransIndexCode`
String
The `transIndexCode` of the original transaction that was voided.
`data.result`
Integer
An integer code representing the status of the transaction. See [Transaction Status Codesarrow-up-right](https://www.google.com/search?q=%23transaction-status-codes)
below.
**Transaction Status Codes**
The `result` field indicates the immediate outcome of the void request.
Result Code
Description
`0`
Success
`1`
Failure
`2`
Pending / In Progress
**Success Response Example**
JSON
[PreviousPaychevron-left](https://smartpossdk.gitbook.io/paywizard-open-api/loyalty/pay)
[NextIssue Pointschevron-right](https://smartpossdk.gitbook.io/paywizard-open-api/loyalty/issue-points)
Last updated 5 months ago
* [Overview](https://smartpossdk.gitbook.io/paywizard-open-api/loyalty/void#overview)
* [Environments](https://smartpossdk.gitbook.io/paywizard-open-api/loyalty/void#environments)
* [Headers](https://smartpossdk.gitbook.io/paywizard-open-api/loyalty/void#headers)
* [Request Body Parameters](https://smartpossdk.gitbook.io/paywizard-open-api/loyalty/void#request-body-parameters)
* [Request Example](https://smartpossdk.gitbook.io/paywizard-open-api/loyalty/void#request-example)
sun-brightdesktopmoon
Copy
{
"clientId": "825429536610058240",
"tranOrderNo": "20250401123534801",
"oriOrderNo": "933358163137265664"
}
Copy
{
"code": 200,
"msg": "success",
"timestamp": "2025-07-24 13:07:08",
"data": {
"mid": "202507081058",
"paywizardId": "10020000080",
"checkoutId": "933393048983961600",
"transIndexCode": "100200000802784286495",
"result": 0,
"oriCheckoutId": "933392815902294016",
"oriTransIndexCode": "100200000807293844967"
}
}
sun-brightdesktopmoon
---
# Refund | Paywizard Integration
[hashtag](https://smartpossdk.gitbook.io/paywizard-open-api/apm-qr-wallet/refund#overview)
Overview
--------------------------------------------------------------------------------------------------------
This endpoint is used to issue a full or partial refund for a previously completed transaction.
Note: Partial refunds are not supported by all payment channels. Please check the documentation for your specific channel.
[hashtag](https://smartpossdk.gitbook.io/paywizard-open-api/apm-qr-wallet/refund#environments)
Environments
----------------------------------------------------------------------------------------------------------------
Environment
Protocol
HTTP Method
URL
Sandbox
HTTPS
`POST`
`https://uat.paywizard.biz/ovstrade/openPay/refundOrder`
Production
HTTPS
`POST`
`https://portal.paywizard.biz/ovstrade/openPay/refundOrder`
[hashtag](https://smartpossdk.gitbook.io/paywizard-open-api/apm-qr-wallet/refund#headers)
**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://smartpossdk.gitbook.io/paywizard-open-api/cloud-api/paywizard-open-platform-api-signature-guide-v3)
.
[hashtag](https://smartpossdk.gitbook.io/paywizard-open-api/apm-qr-wallet/refund#request-body-parameters)
**Request Body Parameters**
------------------------------------------------------------------------------------------------------------------------------------------
To identify the transaction to be refunded, 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 refund request, generated by your system.
`oriCheckoutId`
String
Conditionally Required
The original `checkoutId` of the transaction you want to refund.
`oriTransIndexCode`
String
Conditionally Required
The original `transIndexCode` of the transaction you want to refund.
`amount`
String
Yes
The amount to be refunded. Example: `"1.50"`.
`notifyUrl`
String
No
The callback URL where you will receive the final refund result notification.
circle-exclamation
_Note: You must provide at least one of the original identifiers (_`_oriCheckoutId_` _or_ `_oriTransIndexCode_`_). If both are sent,_ `_oriCheckoutId_` _will take precedence._
[hashtag](https://smartpossdk.gitbook.io/paywizard-open-api/apm-qr-wallet/refund#request-example)
**Request Example**
--------------------------------------------------------------------------------------------------------------------------
* * *
**Response Body**
The response object contains the immediate status of the refund 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 refund, generated by the payment platform.
`data.transIndexCode`
String
The unique refund order ID that you provided in the request.
`data.result`
Integer
An integer code representing the status of the refund. See [Refund Status Codesarrow-up-right](https://www.google.com/search?q=%23refund-status-codes)
below.
`data.amount`
String
The refunded amount.
`data.oriCheckoutId`
String
The `checkoutId` of the original transaction that was refunded.
`data.oriTransIndexCode`
String
The `transIndexCode` of the original transaction that was refunded.
**Refund Status Codes**
The `result` field indicates the immediate outcome of the refund request. The final status may be delivered via the `notifyUrl`.
Result Code
Description
`0`
Success
`1`
Failure
`2`
Pending / In Progress
**Success Response Example**
JSON
[PreviousQuery Transaction Statuschevron-left](https://smartpossdk.gitbook.io/paywizard-open-api/apm-qr-wallet/query-transaction-status)
[NextVOIDchevron-right](https://smartpossdk.gitbook.io/paywizard-open-api/apm-qr-wallet/void)
Last updated 4 months ago
* [Overview](https://smartpossdk.gitbook.io/paywizard-open-api/apm-qr-wallet/refund#overview)
* [Environments](https://smartpossdk.gitbook.io/paywizard-open-api/apm-qr-wallet/refund#environments)
* [Headers](https://smartpossdk.gitbook.io/paywizard-open-api/apm-qr-wallet/refund#headers)
* [Request Body Parameters](https://smartpossdk.gitbook.io/paywizard-open-api/apm-qr-wallet/refund#request-body-parameters)
* [Request Example](https://smartpossdk.gitbook.io/paywizard-open-api/apm-qr-wallet/refund#request-example)
sun-brightdesktopmoon
Copy
{
"clientId": "825429536610058240",
"transIndexCode": "202506091432000000013",
"oriCheckoutId": "917121926164512768",
"amount": "0.01"
}
Copy
{
"code": 200,
"msg": "success",
"timestamp": "2025-06-09 15:32:00",
"data": {
"mid": "007889-3-006",
"paywizardId": "10280000002",
"checkoutId": "917122074735149056",
"transIndexCode": "202506091432000000015",
"amount": "0.01",
"result": 0,
"oriCheckoutId": "917121926164512768",
"oriTransIndexCode": "202506091432000000012"
}
}
sun-brightdesktopmoon
---
# Query | Paywizard Integration
[hashtag](https://smartpossdk.gitbook.io/paywizard-open-api/loyalty/query#overview)
Overview
-------------------------------------------------------------------------------------------------
This endpoint is used to query the current balance and associated customer information for a specific prepaid (loyalty/gift) card.
[hashtag](https://smartpossdk.gitbook.io/paywizard-open-api/loyalty/query#environments)
Environments
---------------------------------------------------------------------------------------------------------
Environment
Protocol
HTTP Method
URL
Sandbox
HTTPS
`POST`
`https://uat.paywizard.biz/ovstrade/openLoyaltyPay/giftInquiry`
Production
HTTPS
`POST`
`https://portal.paywizard.biz/ovstrade/openLoyaltyPay/giftInquiry`
* * *
[hashtag](https://smartpossdk.gitbook.io/paywizard-open-api/loyalty/query#headers)
**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://smartpossdk.gitbook.io/paywizard-open-api/cloud-api/paywizard-open-platform-api-signature-guide-v3)
.
[hashtag](https://smartpossdk.gitbook.io/paywizard-open-api/loyalty/query#request-body-parameters)
**Request Body Parameters**
-----------------------------------------------------------------------------------------------------------------------------------
Parameter
Type
Required
Description
`clientId`
String
Yes
Your unique developer ID.
`loyaltyChannel`
String
Yes
The prepaid channel provider. See [Prepaid Channelsarrow-up-right](https://oversea.hs1c.cn/showdoc/web/#/671575440/155776425)
for valid values.
`accountId`
String
Yes
The unique identifier for the prepaid card.
`entryType`
String
Yes
The method used to input the `accountId`. See [Entry Type Codesarrow-up-right](https://www.google.com/search?q=%23entry-type-codes)
below.
###
[hashtag](https://smartpossdk.gitbook.io/paywizard-open-api/loyalty/query#entry-type-codes)
**Entry Type Codes**
Code
Description
`B`
Barcode
`K`
Keyed (manually entered)
`M`
Magnetic Stripe
`P`
Proximity (NFC/Contactless)
###
[hashtag](https://smartpossdk.gitbook.io/paywizard-open-api/loyalty/query#request-example)
**Request Example**
* * *
[hashtag](https://smartpossdk.gitbook.io/paywizard-open-api/loyalty/query#response-body)
**Response Body**
---------------------------------------------------------------------------------------------------------------
The response returns the card's current balance information and any associated customer data.
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.accountId`
String
The unique identifier for the prepaid card.
`data.balances`
Array
An array of [Balances Objectarrow-up-right](https://www.google.com/search?q=%23balances-object)
detailing the card's value.
`data.customerInfo`
Object
The [CustomerInfo Objectarrow-up-right](https://www.google.com/search?q=%23customerinfo-object)
associated with the card.
###
[hashtag](https://smartpossdk.gitbook.io/paywizard-open-api/loyalty/query#customerinfo-object)
**CustomerInfo Object**
Parameter
Type
Description
`customerType`
String
`1`: Primary account holder, `2`: Alternate, `3`: Giver of card.
`firstName`
String
Customer's first name.
`middleName`
String
Customer's middle name.
`lastName`
String
Customer's last name.
`address1`
String
Primary address line.
`address2`
String
Secondary address line.
`city`
String
City name.
`state`
String
State or province.
`postal`
String
Postal code.
`country`
String
2-character ISO 3166-1 country code.
`mailPref`
String
Mail preference. `O`: Opt-out, `I`: Opt-in.
`phone`
String
Phone number in the format `+CCC AAA LLL LLL xEEEE`.
`isMobile`
String
`Y`: Yes, `N`: No.
`phonePref`
String
Phone contact preference. `O`: Opt-out, `I`: Opt-in.
`email`
String
Customer's email address.
`emailPref`
String
Email contact preference. `O`: Opt-out, `I`: Opt-in.
`birthday`
String
Customer's birthday in `YYYYMMDD` format.
`anniversary`
String
Customer's anniversary in `YYYYMMDD` format.
`gender`
String
`M`: Male, `F`: Female.
###
[hashtag](https://smartpossdk.gitbook.io/paywizard-open-api/loyalty/query#balances-object)
**Balances Object**
This object represents a single type of value held on the card, such as currency or points.
Parameter
Type
Description
`valueCode`
String
The currency code (e.g., "USD") or "Points".
`amount`
Decimal
The total amount of the specified `valueCode`.
`difference`
Decimal
The difference in amount from the previous transaction.
[hashtag](https://smartpossdk.gitbook.io/paywizard-open-api/loyalty/query#success-response-example)
**Success Response Example**
-------------------------------------------------------------------------------------------------------------------------------------
[PreviousActivatechevron-left](https://smartpossdk.gitbook.io/paywizard-open-api/loyalty/activate)
[NextTop-upchevron-right](https://smartpossdk.gitbook.io/paywizard-open-api/loyalty/top-up)
Last updated 5 months ago
* [Overview](https://smartpossdk.gitbook.io/paywizard-open-api/loyalty/query#overview)
* [Environments](https://smartpossdk.gitbook.io/paywizard-open-api/loyalty/query#environments)
* [Headers](https://smartpossdk.gitbook.io/paywizard-open-api/loyalty/query#headers)
* [Request Body Parameters](https://smartpossdk.gitbook.io/paywizard-open-api/loyalty/query#request-body-parameters)
* [Entry Type Codes](https://smartpossdk.gitbook.io/paywizard-open-api/loyalty/query#entry-type-codes)
* [Request Example](https://smartpossdk.gitbook.io/paywizard-open-api/loyalty/query#request-example)
* [Response Body](https://smartpossdk.gitbook.io/paywizard-open-api/loyalty/query#response-body)
* [CustomerInfo Object](https://smartpossdk.gitbook.io/paywizard-open-api/loyalty/query#customerinfo-object)
* [Balances Object](https://smartpossdk.gitbook.io/paywizard-open-api/loyalty/query#balances-object)
* [Success Response Example](https://smartpossdk.gitbook.io/paywizard-open-api/loyalty/query#success-response-example)
sun-brightdesktopmoon
Copy
{
"clientId": "825429536610058240",
"loyaltyChannel": "FACTOR4",
"accountId": "914639258868515",
"entryType": "K"
}
Copy
{
"code": 200,
"msg": "success",
"timestamp": "2025-07-24 13:16:29",
"data": {
"accountId": "914639258868515",
"balances": [\
{\
"valueCode": "USD",\
"amount": 1534.10,\
"difference": 0\
},\
{\
"valueCode": "Points",\
"amount": 53.00,\
"difference": 0\
}\
],
"customerInfo": {
"customerType": "1",
"firstName": "Jon1",
"middleName": "Mid2",
"lastName": "Doe3",
"address1": "295R+VM Settat, Morocco",
"address2": "Settat,Morocco",
"city": "Morocco",
"state": "Settat",
"postal": "",
"country": "US",
"mailPref": "O",
"phone": "+8612154154",
"isMobile": "N",
"phonePref": "O",
"email": "Jon@gmail.com",
"emailPref": "O",
"birthday": "20000101",
"anniversary": "",
"gender": ""
}
}
}
sun-brightdesktopmoon
---
# Quick Start - Loyalty API | Paywizard Integration
[hashtag](https://smartpossdk.gitbook.io/paywizard-open-api/loyalty/quick-start-loyalty-api#factor4-loyalty-api-quick-start)
Factor4 Loyalty API Quick Start
-----------------------------------------------------------------------------------------------------------------------------------------------------------------
Welcome to the Factor4 Loyalty API Quick Start Guide! This document provides a rapid introduction to integrating prepaid (loyalty/gift) card management functionalities into your application. The Factor4 Loyalty API allows you to programmatically activate, query, top-up, process payments, and manage loyalty points for customer cards.
###
[hashtag](https://smartpossdk.gitbook.io/paywizard-open-api/loyalty/quick-start-loyalty-api#id-1.-api-series-overview)
1\. API Series Overview
The Factor4 Loyalty API is designed to offer comprehensive management of gift and loyalty cards. It enables merchants and developers to perform essential operations related to prepaid cards, including card activation, balance inquiries, funds top-ups, processing payments using gift cards, and managing loyalty point issuance and redemption. All API requests are processed via HTTPS POST and require a JSON Web Token (JWT) in the request header, along with a signature for robust authentication and request verification.
###
[hashtag](https://smartpossdk.gitbook.io/paywizard-open-api/loyalty/quick-start-loyalty-api#id-2.-key-features-and-endpoints)
2\. Key Features & Endpoints
The Factor4 Loyalty API provides various functionalities to manage prepaid (loyalty/gift) cards, primarily through the following API endpoints:
* **Activate Gift Card**: Used to activate a prepaid card and link it to customer information.
* (Specific URL not provided in all references, but general capability is listed).
* **Query Gift Card**: Used to retrieve the current balance and associated customer details for a specific prepaid card.
* `POST /ovstrade/openLoyaltyPay/giftInquiry`
* **Top-up Gift Card**: Allows adding funds (reloading/topping-up) to an existing prepaid card. This operation can also optionally activate the card or update customer information.
* (Specific URL for Top-up, sometimes referred to as `giftIssuance`, is implied but not explicitly provided for the "Top-up" name across all references).
* **Pay Gift Card**: Used to process payments by using the available balance on a customer's prepaid (loyalty/gift) card.
* (Specific URL not provided in all references, but general capability is listed).
* **Void Gift Card**: This endpoint is used to void a prior prepaid card transaction, such as a payment or a reload. A void typically reverses the original operation before it has been settled.
* `POST /ovstrade/openLoyaltyPay/giftVoid`
* **Issue Points - Gift Card**: This endpoint is used to issue loyalty points to a customer's prepaid card. This specifically adds points, not monetary value.
* `POST /ovstrade/openLoyaltyPay/loyaltyIssuance`
* **Redeem Points - Gift Card**: Utilized to consume or redeem loyalty points from a customer's prepaid card, serving as the inverse of the "Issue Points" operation.
* `POST /ovstrade/openLoyaltyPay/loyaltyRedemption`
* **Add Tip - Gift Card**: For adding a tip to a prepaid card transaction that has already been completed, common in service industries.
* `POST /ovstrade/openLoyaltyPay/giftTip`
###
[hashtag](https://smartpossdk.gitbook.io/paywizard-open-api/loyalty/quick-start-loyalty-api#id-3.-authentication-and-security)
3\. Authentication & Security
All requests to the Factor4 Loyalty API must be secured using a JSON Web Token (JWT) and a signature.
* **Protocol**: HTTPS
* **HTTP Method**: POST
* **Required Headers**:
* `Content-Type`: Must be `application/json`.
* `jwt-token`: Your transaction token, obtained using your developer credentials.
* `sign`: The request signature. Refer to the Signature Generation Guide for detailed instructions on generating this signature.
###
[hashtag](https://smartpossdk.gitbook.io/paywizard-open-api/loyalty/quick-start-loyalty-api#id-4.-environments)
4\. Environments
Factor4 Loyalty API provides a `Sandbox` environment for development and testing purposes.
###
[hashtag](https://smartpossdk.gitbook.io/paywizard-open-api/loyalty/quick-start-loyalty-api#id-5.-getting-started-steps)
5\. Getting Started Steps
To begin utilizing the Factor4 Loyalty API, follow these fundamental steps:
1. **Obtain Developer Credentials**: Secure your `clientId` and any other credentials necessary for generating your `jwt-token` and `sign`.
2. **Generate JWT Token**: Create a valid JWT token using your developer credentials.
3. **Generate Request Signature**: Follow the specific instructions in the Signature Generation Guide to produce the required request signature.
4. **Construct Request Body**: Assemble the JSON formatted request body for your chosen API endpoint, including parameters like `clientId`, `loyaltyChannel`, `accountId`, `tranOrderNo`, and others as required.
5. **Send POST Request**: Transmit your POST request, complete with the correct headers and request body, to the relevant API endpoint in the Sandbox environment.
###
[hashtag](https://smartpossdk.gitbook.io/paywizard-open-api/loyalty/quick-start-loyalty-api#id-6.-common-request-parameters)
6\. Common Request Parameters
Below are some frequently used parameters found in the Loyalty API request bodies:
* `clientId` (String, Required): Your unique developer ID.
* `tranOrderNo` (String, Required): A unique order ID generated by your system for the specific transaction (e.g., for points issuance, redemption, top-up, void, tip).
* `loyaltyChannel` (String, Required): The designated prepaid channel provider.
* `accountId` (String, Required): The unique identifier for the prepaid card.
* `entryType` (String, Required): Specifies the method used to input the `accountId`. Valid codes include: `B` (Barcode), `K` (Keyed/Manual), `M` (Magnetic Stripe), `P` (Proximity/NFC/Contactless).
* `oriOrderNo` (String, Required): The `checkoutId` of the original transaction you want to void (for `giftVoid`) or the original payment transaction ID for adding a tip (for `giftTip`).
* `tranCurrency` (String, Required): The 3-letter ISO currency code for the transaction, e.g., "USD" (used for adding tips).
* `amount` (String): The total transaction amount, e.g., "10.50" (used for top-up, void, tips).
[PreviousClose Orderchevron-left](https://smartpossdk.gitbook.io/paywizard-open-api/apm-qr-wallet/close-order)
[NextLOYALTY APIchevron-right](https://smartpossdk.gitbook.io/paywizard-open-api/loyalty/quick-start-loyalty-api/loyalty-api)
Last updated 5 months ago
* [Factor4 Loyalty API Quick Start](https://smartpossdk.gitbook.io/paywizard-open-api/loyalty/quick-start-loyalty-api#factor4-loyalty-api-quick-start)
* [1\. API Series Overview](https://smartpossdk.gitbook.io/paywizard-open-api/loyalty/quick-start-loyalty-api#id-1.-api-series-overview)
* [2\. Key Features & Endpoints](https://smartpossdk.gitbook.io/paywizard-open-api/loyalty/quick-start-loyalty-api#id-2.-key-features-and-endpoints)
* [3\. Authentication & Security](https://smartpossdk.gitbook.io/paywizard-open-api/loyalty/quick-start-loyalty-api#id-3.-authentication-and-security)
* [4\. Environments](https://smartpossdk.gitbook.io/paywizard-open-api/loyalty/quick-start-loyalty-api#id-4.-environments)
* [5\. Getting Started Steps](https://smartpossdk.gitbook.io/paywizard-open-api/loyalty/quick-start-loyalty-api#id-5.-getting-started-steps)
* [6\. Common Request Parameters](https://smartpossdk.gitbook.io/paywizard-open-api/loyalty/quick-start-loyalty-api#id-6.-common-request-parameters)
sun-brightdesktopmoon
sun-brightdesktopmoon
---
# Activate | Paywizard Integration
[hashtag](https://smartpossdk.gitbook.io/paywizard-open-api/loyalty/activate#overview)
Overview
----------------------------------------------------------------------------------------------------
This endpoint is used to activate a prepaid (loyalty/gift) card and associate it with customer information.
[hashtag](https://smartpossdk.gitbook.io/paywizard-open-api/loyalty/activate#environments)
Environments
------------------------------------------------------------------------------------------------------------
Environment
Protocol
HTTP Method
URL
Sandbox
HTTPS
`POST`
`https://uat.paywizard.biz/ovstrade/openLoyaltyPay/giftActivate`
Production
HTTPS
`POST`
`https://portal.paywizard.biz/ovstrade/openLoyaltyPay/giftActivate`
[hashtag](https://smartpossdk.gitbook.io/paywizard-open-api/loyalty/activate#headers)
**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://smartpossdk.gitbook.io/paywizard-open-api/cloud-api/paywizard-open-platform-api-signature-guide-v3)
.
[hashtag](https://smartpossdk.gitbook.io/paywizard-open-api/loyalty/activate#request-body-parameters)
**Request Body Parameters**
--------------------------------------------------------------------------------------------------------------------------------------
Parameter
Type
Required
Description
`clientId`
String
Yes
Your unique developer ID.
`loyaltyChannel`
String
Yes
The prepaid channel provider. See [Prepaid Channelsarrow-up-right](https://oversea.hs1c.cn/showdoc/web/#/671575440/155776425)
for valid values.
`accountId`
String
Yes
The unique identifier for the prepaid card.
`entryType`
String
Yes
The method used to input the `accountId`. See [Entry Type Codesarrow-up-right](https://www.google.com/search?q=%23entry-type-codes)
below.
`activating`
String
Yes
Set to `"Y"` to activate the card or `"N"` to not activate.
`customerInfo`
Object
Yes
A JSON object containing the customer's details. See [CustomerInfo Objectarrow-up-right](https://www.google.com/search?q=%23customerinfo-object)
structure below.
###
[hashtag](https://smartpossdk.gitbook.io/paywizard-open-api/loyalty/activate#customerinfo-object)
**CustomerInfo Object**
Parameter
Type
Required
Description
`customerType`
String
Yes
`1`: Primary account holder, `2`: Alternate, `3`: Giver of card.
`firstName`
String
Yes
Customer's first name.
`middleName`
String
Yes
Customer's middle name.
`lastName`
String
Yes
Customer's last name.
`address1`
String
Yes
Primary address line.
`address2`
String
Yes
Secondary address line.
`city`
String
Yes
City name.
`state`
String
Yes
State or province.
`postal`
String
Yes
Postal code (must be a valid format for the country).
`country`
String
Yes
2-character ISO 3166-1 country code.
`mailPref`
String
Yes
Mail preference. `O`: Opt-out, `I`: Opt-in.
`phone`
String
Yes
Phone number in the format `+CCC AAA LLL LLL xEEEE`.
`isMobile`
String
Yes
`Y`: Yes, `N`: No.
`phonePref`
String
Yes
Phone contact preference. `O`: Opt-out, `I`: Opt-in.
`email`
String
Yes
Customer's email address.
`emailPref`
String
Yes
Email contact preference. `O`: Opt-out, `I`: Opt-in.
`birthday`
String
Yes
Customer's birthday in `YYYYMMDD` format.
`anniversary`
String
Yes
Customer's anniversary in `YYYYMMDD` format.
`gender`
String
Yes
`M`: Male, `F`: Female.
###
[hashtag](https://smartpossdk.gitbook.io/paywizard-open-api/loyalty/activate#entry-type-codes)
**Entry Type Codes**
Code
Description
`B`
Barcode
`K`
Keyed (manually entered)
`M`
Magnetic Stripe
`P`
Proximity (NFC/Contactless)
[hashtag](https://smartpossdk.gitbook.io/paywizard-open-api/loyalty/activate#request-example)
**Request Example**
----------------------------------------------------------------------------------------------------------------------
* * *
[hashtag](https://smartpossdk.gitbook.io/paywizard-open-api/loyalty/activate#response-body)
**Response Body**
------------------------------------------------------------------------------------------------------------------
The response returns the card's balance information and confirms the customer data that has been stored.
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.accountId`
String
The unique identifier for the prepaid card.
`data.balances`
Array
An array of [Balances Objectarrow-up-right](https://www.google.com/search?q=%23balances-object)
detailing the card's value.
`data.customerInfo`
Object
The [CustomerInfo Objectarrow-up-right](https://www.google.com/search?q=%23customerinfo-object)
that was saved.
###
[hashtag](https://smartpossdk.gitbook.io/paywizard-open-api/loyalty/activate#balances-object)
**Balances Object**
This object represents a single type of value held on the card, such as currency or points.
Parameter
Type
Description
`valueCode`
String
The currency code (e.g., "USD") or "Points".
`amount`
Decimal
The total amount of the specified `valueCode`.
`difference`
Decimal
The difference in amount from the previous transaction.
[hashtag](https://smartpossdk.gitbook.io/paywizard-open-api/loyalty/activate#success-response-example)
**Success Response Example**
----------------------------------------------------------------------------------------------------------------------------------------
[PreviousLOYALTY APIchevron-left](https://smartpossdk.gitbook.io/paywizard-open-api/loyalty/quick-start-loyalty-api/loyalty-api)
[NextQuerychevron-right](https://smartpossdk.gitbook.io/paywizard-open-api/loyalty/query)
Last updated 5 months ago
* [Overview](https://smartpossdk.gitbook.io/paywizard-open-api/loyalty/activate#overview)
* [Environments](https://smartpossdk.gitbook.io/paywizard-open-api/loyalty/activate#environments)
* [Headers](https://smartpossdk.gitbook.io/paywizard-open-api/loyalty/activate#headers)
* [Request Body Parameters](https://smartpossdk.gitbook.io/paywizard-open-api/loyalty/activate#request-body-parameters)
* [CustomerInfo Object](https://smartpossdk.gitbook.io/paywizard-open-api/loyalty/activate#customerinfo-object)
* [Entry Type Codes](https://smartpossdk.gitbook.io/paywizard-open-api/loyalty/activate#entry-type-codes)
* [Request Example](https://smartpossdk.gitbook.io/paywizard-open-api/loyalty/activate#request-example)
* [Response Body](https://smartpossdk.gitbook.io/paywizard-open-api/loyalty/activate#response-body)
* [Balances Object](https://smartpossdk.gitbook.io/paywizard-open-api/loyalty/activate#balances-object)
* [Success Response Example](https://smartpossdk.gitbook.io/paywizard-open-api/loyalty/activate#success-response-example)
sun-brightdesktopmoon
Copy
{
"clientId": "825429536610058240",
"loyaltyChannel": "FACTOR4",
"accountId": "914639258868515",
"entryType": "K",
"activating": "Y",
"customerInfo": {
"customerType": "1",
"firstName": "Jon1",
"middleName": "Mid2",
"lastName": "Doe3",
"address1": "295R+VM Settat, Morocco",
"address2": "Settat,Morocco",
"city": "Morocco",
"state": "Settat",
"postal": "26000",
"country": "MA",
"mailPref": "O",
"phone": "+12125551234",
"isMobile": "N",
"phonePref": "O",
"email": "Jon@gmail.com",
"emailPref": "O",
"birthday": "20000101",
"anniversary": "",
"gender": "M"
}
}
Copy
{
"code": 200,
"msg": "success",
"timestamp": "2025-07-24 15:34:05",
"data": {
"accountId": "914639258868515",
"balances": [\
{\
"valueCode": "USD",\
"amount": 1534.10,\
"difference": 0\
},\
{\
"valueCode": "Points",\
"amount": 53.00,\
"difference": 0\
}\
],
"customerInfo": {
"customerType": "1",
"firstName": "Jon1",
"middleName": "Mid2",
"lastName": "Doe3",
"address1": "295R+VM Settat, Morocco",
"address2": "Settat,Morocco",
"city": "Morocco",
"state": "Settat",
"postal": "",
"country": "US",
"mailPref": "O",
"phone": "+8612154154",
"isMobile": "N",
"phonePref": "O",
"email": "Jon@gmail.com",
"emailPref": "O",
"birthday": "20000101",
"anniversary": "",
"gender": ""
}
}
}
sun-brightdesktopmoon
---
# Top-up | Paywizard Integration
[hashtag](https://smartpossdk.gitbook.io/paywizard-open-api/loyalty/top-up#overview)
Overview
--------------------------------------------------------------------------------------------------
This endpoint is used to add funds (reload/top-up) to an existing prepaid card. You can also optionally activate the card or update the associated customer information within the same request.
[hashtag](https://smartpossdk.gitbook.io/paywizard-open-api/loyalty/top-up#environments)
Environments
----------------------------------------------------------------------------------------------------------
Environment
Protocol
HTTP Method
URL
Sandbox
HTTPS
`POST`
`https://uat.paywizard.biz/ovstrade/openLoyaltyPay/giftIssuance`
Production
HTTPS
`POST`
`https://portal.paywizard.biz/ovstrade/openLoyaltyPay/giftIssuance`
* * *
[hashtag](https://smartpossdk.gitbook.io/paywizard-open-api/loyalty/top-up#headers)
**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://smartpossdk.gitbook.io/paywizard-open-api/cloud-api/paywizard-open-platform-api-signature-guide-v3)
.
[hashtag](https://smartpossdk.gitbook.io/paywizard-open-api/loyalty/top-up#request-body-parameters)
**Request Body Parameters**
------------------------------------------------------------------------------------------------------------------------------------
Parameter
Type
Required
Description
`clientId`
String
Yes
Your unique developer ID.
`tranOrderNo`
String
Yes
The unique order ID for this reload transaction, generated by your system.
`loyaltyChannel`
String
Yes
The prepaid channel provider. See [Prepaid Channelsarrow-up-right](https://oversea.hs1c.cn/showdoc/web/#/671575440/155776425)
for valid values.
`accountId`
String
Yes
The unique identifier for the prepaid card.
`entryType`
String
Yes
The method used to input the `accountId`. See [Entry Type Codesarrow-up-right](https://www.google.com/search?q=%23entry-type-codes)
below.
`activating`
String
No
Set to `"Y"` to activate the card or `"N"` to not activate.
`customerInfo`
Object
No
A JSON object containing the customer's details. See [CustomerInfo Objectarrow-up-right](https://www.google.com/search?q=%23customerinfo-object-optional)
structure below.
###
[hashtag](https://smartpossdk.gitbook.io/paywizard-open-api/loyalty/top-up#customerinfo-object-optional)
**CustomerInfo Object (Optional)**
Parameter
Type
Required
Description
`customerType`
String
No
`1`: Primary account holder, `2`: Alternate, `3`: Giver of card.
`firstName`
String
No
Customer's first name.
`middleName`
String
No
Customer's middle name.
`lastName`
String
No
Customer's last name.
`address1`
String
No
Primary address line.
`address2`
String
No
Secondary address line.
`city`
String
No
City name.
`state`
String
No
State or province.
`postal`
String
No
Postal code (must be a valid format for the country).
`country`
String
No
2-character ISO 3166-1 country code.
`mailPref`
String
No
Mail preference. `O`: Opt-out, `I`: Opt-in.
`phone`
String
No
Phone number in the format `+CCC AAA LLL LLL xEEEE`.
`isMobile`
String
No
`Y`: Yes, `N`: No.
`phonePref`
String
No
Phone contact preference. `O`: Opt-out, `I`: Opt-in.
`email`
String
No
Customer's email address.
`emailPref`
String
No
Email contact preference. `O`: Opt-out, `I`: Opt-in.
`birthday`
String
No
Customer's birthday in `YYYYMMDD` format.
`anniversary`
String
No
Customer's anniversary in `YYYYMMDD` format.
`gender`
String
No
`M`: Male, `F`: Female.
###
[hashtag](https://smartpossdk.gitbook.io/paywizard-open-api/loyalty/top-up#entry-type-codes)
**Entry Type Codes**
Code
Description
`B`
Barcode
`K`
Keyed (manually entered)
`M`
Magnetic Stripe
`P`
Proximity (NFC/Contactless)
###
[hashtag](https://smartpossdk.gitbook.io/paywizard-open-api/loyalty/top-up#request-example)
**Request Example**
* * *
[hashtag](https://smartpossdk.gitbook.io/paywizard-open-api/loyalty/top-up#response-body)
**Response Body**
----------------------------------------------------------------------------------------------------------------
The response object contains the status of the reload transaction request.
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.mid`
String
The merchant ID.
`data.paywizardId`
String
The unique platform ID for the transaction.
`data.checkoutId`
String
The unique transaction ID generated by the payment platform.
`data.transIndexCode`
String
A unique transaction reference code.
`data.amount`
String
The transaction amount that was reloaded.
`data.result`
Integer
An integer code representing the status of the transaction. See [Transaction Status Codesarrow-up-right](https://www.google.com/search?q=%23transaction-status-codes)
below.
###
[hashtag](https://smartpossdk.gitbook.io/paywizard-open-api/loyalty/top-up#transaction-status-codes)
**Transaction Status Codes**
The `result` field indicates the immediate outcome of the reload request.
Result Code
Description
`0`
Success
`1`
Failure
`2`
Pending / In Progress
[hashtag](https://smartpossdk.gitbook.io/paywizard-open-api/loyalty/top-up#success-response-example)
**Success Response Example**
--------------------------------------------------------------------------------------------------------------------------------------
[PreviousQuerychevron-left](https://smartpossdk.gitbook.io/paywizard-open-api/loyalty/query)
[NextPaychevron-right](https://smartpossdk.gitbook.io/paywizard-open-api/loyalty/pay)
Last updated 5 months ago
* [Overview](https://smartpossdk.gitbook.io/paywizard-open-api/loyalty/top-up#overview)
* [Environments](https://smartpossdk.gitbook.io/paywizard-open-api/loyalty/top-up#environments)
* [Headers](https://smartpossdk.gitbook.io/paywizard-open-api/loyalty/top-up#headers)
* [Request Body Parameters](https://smartpossdk.gitbook.io/paywizard-open-api/loyalty/top-up#request-body-parameters)
* [CustomerInfo Object (Optional)](https://smartpossdk.gitbook.io/paywizard-open-api/loyalty/top-up#customerinfo-object-optional)
* [Entry Type Codes](https://smartpossdk.gitbook.io/paywizard-open-api/loyalty/top-up#entry-type-codes)
* [Request Example](https://smartpossdk.gitbook.io/paywizard-open-api/loyalty/top-up#request-example)
* [Response Body](https://smartpossdk.gitbook.io/paywizard-open-api/loyalty/top-up#response-body)
* [Transaction Status Codes](https://smartpossdk.gitbook.io/paywizard-open-api/loyalty/top-up#transaction-status-codes)
* [Success Response Example](https://smartpossdk.gitbook.io/paywizard-open-api/loyalty/top-up#success-response-example)
sun-brightdesktopmoon
Copy
{
"clientId": "825429536610058240",
"tranOrderNo": "20250401123534801",
"loyaltyChannel": "FACTOR4",
"accountId": "914639258868515",
"entryType": "K",
"activating": "Y",
"customerInfo": {
"customerType": "1",
"firstName": "Jon1",
"middleName": "Mid2",
"lastName": "Doe3",
"address1": "295R+VM Settat, Morocco",
"address2": "Settat,Morocco",
"city": "Morocco",
"state": "Settat",
"postal": "",
"country": "US",
"mailPref": "O",
"phone": "+8612154154",
"isMobile": "N",
"phonePref": "O",
"email": "Jon@gmail.com",
"emailPref": "O",
"birthday": "20000101",
"anniversary": "",
"gender": ""
}
}
Copy
{
"code": 200,
"msg": "success",
"timestamp": "2025-07-24 15:52:21",
"data": {
"mid": "202507081058",
"paywizardId": "10020000080",
"checkoutId": "933434611567034368",
"transIndexCode": "100200000809631006007",
"amount": "10000",
"result": 0
}
}
sun-brightdesktopmoon
---
# Issue Points | Paywizard Integration
[hashtag](https://smartpossdk.gitbook.io/paywizard-open-api/loyalty/issue-points#overview)
Overview
--------------------------------------------------------------------------------------------------------
This endpoint is used to issue loyalty points to a customer's prepaid card. This operation is for adding points, not for reloading monetary value.
[hashtag](https://smartpossdk.gitbook.io/paywizard-open-api/loyalty/issue-points#environments)
Environments
----------------------------------------------------------------------------------------------------------------
Environment
Protocol
HTTP Method
URL
Sandbox
HTTPS
`POST`
`https://uat.paywizard.biz/ovstrade/openLoyaltyPay/loyaltyIssuance`
Production
HTTPS
`POST`
`https://portal.paywizard.biz/ovstrade/openLoyaltyPay/loyaltyIssuance`
[hashtag](https://smartpossdk.gitbook.io/paywizard-open-api/loyalty/issue-points#headers)
**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://smartpossdk.gitbook.io/paywizard-open-api/cloud-api/paywizard-open-platform-api-signature-guide-v3)
.
[hashtag](https://smartpossdk.gitbook.io/paywizard-open-api/loyalty/issue-points#request-body-parameters)
**Request Body Parameters**
------------------------------------------------------------------------------------------------------------------------------------------
Parameter
Type
Required
Description
`clientId`
String
Yes
Your unique developer ID.
`tranOrderNo`
String
Yes
The unique order ID for this points issuance transaction, generated by your system.
`loyaltyChannel`
String
Yes
The prepaid channel provider. See [Prepaid Channelsarrow-up-right](https://oversea.hs1c.cn/showdoc/web/#/671575440/155776425)
for valid values.
`accountId`
String
Yes
The unique identifier for the prepaid card.
`entryType`
String
Yes
The method used to input the `accountId`. See [Entry Type Codesarrow-up-right](https://www.google.com/search?q=%23entry-type-codes)
below.
`amount`
String
Yes
The number of loyalty points to add to the card.
###
[hashtag](https://smartpossdk.gitbook.io/paywizard-open-api/loyalty/issue-points#entry-type-codes)
**Entry Type Codes**
Code
Description
`B`
Barcode
`K`
Keyed (manually entered)
`M`
Magnetic Stripe
`P`
Proximity (NFC/Contactless)
[hashtag](https://smartpossdk.gitbook.io/paywizard-open-api/loyalty/issue-points#request-example)
**Request Example**
--------------------------------------------------------------------------------------------------------------------------
* * *
[hashtag](https://smartpossdk.gitbook.io/paywizard-open-api/loyalty/issue-points#response-body)
**Response Body**
----------------------------------------------------------------------------------------------------------------------
The response object contains the status of the points issuance transaction.
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.mid`
String
The merchant ID.
`data.paywizardId`
String
The unique platform ID for the transaction.
`data.checkoutId`
String
The unique transaction ID generated by the payment platform.
`data.transIndexCode`
String
A unique transaction reference code.
`data.amount`
String
The number of points that were issued.
`data.result`
Integer
An integer code representing the status of the transaction. See [Transaction Status Codesarrow-up-right](https://www.google.com/search?q=%23transaction-status-codes)
below.
###
[hashtag](https://smartpossdk.gitbook.io/paywizard-open-api/loyalty/issue-points#transaction-status-codes)
**Transaction Status Codes**
The `result` field indicates the immediate outcome of the points issuance request.
Result Code
Description
`0`
Success
`1`
Failure
`2`
Pending / In Progress
[hashtag](https://smartpossdk.gitbook.io/paywizard-open-api/loyalty/issue-points#success-response-example)
**Success Response Example**
--------------------------------------------------------------------------------------------------------------------------------------------
[PreviousVoidchevron-left](https://smartpossdk.gitbook.io/paywizard-open-api/loyalty/void)
[NextRedeem Pointschevron-right](https://smartpossdk.gitbook.io/paywizard-open-api/loyalty/redeem-points)
Last updated 5 months ago
* [Overview](https://smartpossdk.gitbook.io/paywizard-open-api/loyalty/issue-points#overview)
* [Environments](https://smartpossdk.gitbook.io/paywizard-open-api/loyalty/issue-points#environments)
* [Headers](https://smartpossdk.gitbook.io/paywizard-open-api/loyalty/issue-points#headers)
* [Request Body Parameters](https://smartpossdk.gitbook.io/paywizard-open-api/loyalty/issue-points#request-body-parameters)
* [Entry Type Codes](https://smartpossdk.gitbook.io/paywizard-open-api/loyalty/issue-points#entry-type-codes)
* [Request Example](https://smartpossdk.gitbook.io/paywizard-open-api/loyalty/issue-points#request-example)
* [Response Body](https://smartpossdk.gitbook.io/paywizard-open-api/loyalty/issue-points#response-body)
* [Transaction Status Codes](https://smartpossdk.gitbook.io/paywizard-open-api/loyalty/issue-points#transaction-status-codes)
* [Success Response Example](https://smartpossdk.gitbook.io/paywizard-open-api/loyalty/issue-points#success-response-example)
sun-brightdesktopmoon
Copy
{
"clientId": "825429536610058240",
"tranOrderNo": "20250401123534801",
"loyaltyChannel": "FACTOR4",
"accountId": "914639258868515",
"entryType": "K",
"amount": "1"
}
Copy
{
"code": 200,
"msg": "success",
"timestamp": "2025-07-24 16:13:25",
"data": {
"mid": "202507081058",
"paywizardId": "10020000080",
"checkoutId": "933439876320329728",
"transIndexCode": "100200000807013210966",
"amount": "10000",
"result": 0
}
}
sun-brightdesktopmoon
---
# Pay | Paywizard Integration
[hashtag](https://smartpossdk.gitbook.io/paywizard-open-api/loyalty/pay#overview)
Overview
-----------------------------------------------------------------------------------------------
This endpoint is used to process a payment using the available balance on a customer's prepaid (loyalty/gift) card.
[hashtag](https://smartpossdk.gitbook.io/paywizard-open-api/loyalty/pay#environments)
Environments
-------------------------------------------------------------------------------------------------------
Environment
Protocol
HTTP Method
URL
Sandbox
HTTPS
`POST`
`https://uat.paywizard.biz/ovstrade/openLoyaltyPay/giftTransaction`
Production
HTTPS
`POST`
`https://portal.paywizard.biz/ovstrade/openLoyaltyPay/giftTransaction`
[hashtag](https://smartpossdk.gitbook.io/paywizard-open-api/loyalty/pay#headers)
**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://smartpossdk.gitbook.io/paywizard-open-api/cloud-api/paywizard-open-platform-api-signature-guide-v3)
.
[hashtag](https://smartpossdk.gitbook.io/paywizard-open-api/loyalty/pay#request-body-parameters)
**Request Body Parameters**
---------------------------------------------------------------------------------------------------------------------------------
Parameter
Type
Required
Description
`clientId`
String
Yes
Your unique developer ID.
`tranOrderNo`
String
Yes
The unique order ID for this payment transaction, generated by your system.
`loyaltyChannel`
String
Yes
The prepaid channel provider. See [Prepaid Channelsarrow-up-right](https://oversea.hs1c.cn/showdoc/web/#/671575440/155776425)
for valid values.
`amount`
String
Yes
The total transaction amount. Example: `"10.50"`.
`tranCurrency`
String
Yes
The 3-letter ISO currency code for the transaction. Example: `"USD"`.
`accountId`
String
Yes
The unique identifier for the prepaid card.
`entryType`
String
Yes
The method used to input the `accountId`. See [Entry Type Codesarrow-up-right](https://www.google.com/search?q=%23entry-type-codes)
below.
`nsfAllowed`
Boolean
No
Non-Sufficient Funds Allowed. Set to `true` to permit the transaction to proceed even if the card balance is insufficient to cover the full amount.
###
[hashtag](https://smartpossdk.gitbook.io/paywizard-open-api/loyalty/pay#entry-type-codes)
**Entry Type Codes**
Code
Description
`B`
Barcode
`K`
Keyed (manually entered)
`M`
Magnetic Stripe
`P`
Proximity (NFC/Contactless)
[hashtag](https://smartpossdk.gitbook.io/paywizard-open-api/loyalty/pay#request-example)
**Request Example**
-----------------------------------------------------------------------------------------------------------------
* * *
[hashtag](https://smartpossdk.gitbook.io/paywizard-open-api/loyalty/pay#response-body)
**Response Body**
-------------------------------------------------------------------------------------------------------------
The response object contains the status of the payment transaction request.
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.mid`
String
The merchant ID.
`data.paywizardId`
String
The unique platform ID for the transaction.
`data.checkoutId`
String
The unique transaction ID generated by the payment platform.
`data.transIndexCode`
String
A unique transaction reference code.
`data.amount`
String
The transaction amount.
`data.result`
Integer
An integer code representing the status of the transaction. See [Transaction Status Codesarrow-up-right](https://www.google.com/search?q=%23transaction-status-codes)
below.
###
[hashtag](https://smartpossdk.gitbook.io/paywizard-open-api/loyalty/pay#transaction-status-codes)
**Transaction Status Codes**
The `result` field indicates the immediate outcome of the payment request.
Result Code
Description
`0`
Success
`1`
Failure
`2`
Pending / In Progress
###
[hashtag](https://smartpossdk.gitbook.io/paywizard-open-api/loyalty/pay#success-response-example)
**Success Response Example**
[PreviousTop-upchevron-left](https://smartpossdk.gitbook.io/paywizard-open-api/loyalty/top-up)
[NextVoidchevron-right](https://smartpossdk.gitbook.io/paywizard-open-api/loyalty/void)
Last updated 5 months ago
* [Overview](https://smartpossdk.gitbook.io/paywizard-open-api/loyalty/pay#overview)
* [Environments](https://smartpossdk.gitbook.io/paywizard-open-api/loyalty/pay#environments)
* [Headers](https://smartpossdk.gitbook.io/paywizard-open-api/loyalty/pay#headers)
* [Request Body Parameters](https://smartpossdk.gitbook.io/paywizard-open-api/loyalty/pay#request-body-parameters)
* [Entry Type Codes](https://smartpossdk.gitbook.io/paywizard-open-api/loyalty/pay#entry-type-codes)
* [Request Example](https://smartpossdk.gitbook.io/paywizard-open-api/loyalty/pay#request-example)
* [Response Body](https://smartpossdk.gitbook.io/paywizard-open-api/loyalty/pay#response-body)
* [Transaction Status Codes](https://smartpossdk.gitbook.io/paywizard-open-api/loyalty/pay#transaction-status-codes)
* [Success Response Example](https://smartpossdk.gitbook.io/paywizard-open-api/loyalty/pay#success-response-example)
sun-brightdesktopmoon
Copy
{
"clientId": "825429536610058240",
"tranOrderNo": "20250401123534801",
"loyaltyChannel": "FACTOR4",
"amount": "10.50",
"tranCurrency": "USD",
"accountId": "914639258868515",
"entryType": "K"
}
Copy
{
"code": 200,
"msg": "success",
"timestamp": "2025-07-24 13:06:10",
"data": {
"mid": "202507081058",
"paywizardId": "10020000080",
"checkoutId": "933392815902294016",
"transIndexCode": "100200000807293844967",
"amount": "10000",
"result": 0
}
}
sun-brightdesktopmoon
---
# Payment App Integration Protocol | Paywizard Integration
###
[hashtag](https://smartpossdk.gitbook.io/paywizard-open-api/semi-integration/local-integration/payment-app-integration-protocol#id-1.-introduction)
1\. Introduction
This document descripts data exchange protocol between Cashier and WIZARPOS terminal. The Cashier is caller to perform transactions and Terminal will listen to Cashier and execute financial transaction.
###
[hashtag](https://smartpossdk.gitbook.io/paywizard-open-api/semi-integration/local-integration/payment-app-integration-protocol#id-2.-transaction-flow)
2\. Transaction Flow
1. **Cashier shall send Handshake Request at first to confirm connection is ready.**
2. **After Handshake, Cashier shall perform transaction and send Transaction Request which contains payment data.**
3. **POS execute transaction and response the result.**
###
[hashtag](https://smartpossdk.gitbook.io/paywizard-open-api/semi-integration/local-integration/payment-app-integration-protocol#id-3.-communication-configuration)
3\. Communication Configuration
Serial port
Default Baud Rate: 115200
TCP server
Default port：6031
###
[hashtag](https://smartpossdk.gitbook.io/paywizard-open-api/semi-integration/local-integration/payment-app-integration-protocol#id-4.-data-format)
4\. Data Format
Data package between Cashier and Terminal.
STX
VERSION
CTRL
LEN
CONTENT
ETX
BCC
**0x02**
**0x02**
**(4 bytes)**
**(2 bytes)**
**(LEN bytes)**
**0x03**
**(1 byte)**
**STX** indicate start byte of data package.
**VERSION** indicate protocol version.
**CTRL** indicate control bytes of data package.
**LEN** indicate length bytes of CONTENT. Hex format.
**CONTENT** indicate main content of transaction.
**ETX** indicate end byte, Fixed **0x03**.
**BCC** indicate package check value, from VERSION (contain) to ETX (contain).
###
[hashtag](https://smartpossdk.gitbook.io/paywizard-open-api/semi-integration/local-integration/payment-app-integration-protocol#id-5.-handshake-request-content)
5\. Handshake Request Content
CONTENT
(4 bytes)
**Handshake request content is 4 bytes random value.**
###
[hashtag](https://smartpossdk.gitbook.io/paywizard-open-api/semi-integration/local-integration/payment-app-integration-protocol#id-6.-handshake-response-content)
6\. Handshake Response Content
CONTENT
(4 bytes)
**Handshake response content should be same with the request.**
###
[hashtag](https://smartpossdk.gitbook.io/paywizard-open-api/semi-integration/local-integration/payment-app-integration-protocol#id-7.-transaction-request-content)
7\. Transaction Request Content
**Transaction Request is content is json format as below:**
NAME
FORMAT
MANDATORY
DESCRIPTION
**TransType**
String
check
Indicate transaction type to be performed.
[See A1.1 Transaction Type](https://smartpossdk.gitbook.io/paywizard-open-api/semi-integration/local-integration/payment-app-integration-protocol#a1.1_transaction_type)
**TransScheme**
String
Cooperation with TransType，used in specific schemes
[See A1.2 Transaction Scheme](https://smartpossdk.gitbook.io/paywizard-open-api/semi-integration/local-integration/payment-app-integration-protocol#a1.2_transaction_type)
**CallerName**
String
Caller name
**TransIndexCode**
String
Indicate Cashier trace number
Should be unique for every transaction
**BusinessNum**
String
Business registration number
**TerminalNum**
String
Terminal number
**TransAmount**
String
\[Mandatory for payment\]
check
Total amount including OtherAmount and TipAmount
“112233” means 1122.33(USD) or 112.233(JOD) depending on CurrencyCode
**OtherAmount**
String
Cash back amount
**TipAmount**
String
Tip amount
**TaxAmount**
String
Tax amount, should be included in TransAmount
**DutyFreeAmount**
String
value of the tax exemption amount, should be included in TransAmount
**CurrencyCode**
String
check
Indicate currency code of transaction
156: RMB
840: USD
400: JOD
**ReqTransDate**
String (YYYYMMDD)
exp. “20201212”
**ReqTransTime**
String (hhmmss)
exp. “1614033”
**OriTransIndexCode**
String
Original request TransIndexCode
**OriTraceNum**
String
**OriInvoiceNum**
String
Original transaction InvoiceNum
**OriTransId**
String
Indicate original transaction id
**OriRrn**
String
Indicate original RRN
**OriTransDate**
String(YYYYMMDD)
Indicate original transaction date
**OriTransTime**
String(hhmmss)
Indicate original transaction time
**EnableReceipt**
boolean
false-Disable Receipt
true-Enable Receipt
**AppendingReceiptInfo**
String
Indicate message to be printed on receipt
**SkipConfirmProcedure**
boolean
false-Don not Skip
true-Skip Confirm Procedure
**EnableCancelInPayment**
boolean
true-Enable user cancel operation
false-Disable user cancel operation
**AdditionalInfo**
String
Request content sample:
###
[hashtag](https://smartpossdk.gitbook.io/paywizard-open-api/semi-integration/local-integration/payment-app-integration-protocol#id-8.-transaction-response-content)
8\. Transaction Response Content
**Transaction Request is content is json format which contain request data as below:**
NAME
FORMAT
MANDATORY
DESCRIPTION
**TransType**
String
check
Indicate transaction type to be performed.
**TransScheme**
String
Cooperation with TransType，used in specific schemes
[See A1.2 Transaction Scheme](https://smartpossdk.gitbook.io/paywizard-open-api/semi-integration/local-integration/payment-app-integration-protocol#a1.2_transaction_type)
**CallerName**
String
Caller name
**TransIndexCode**
String
Indicate Cashier trace number
**TransResult**
boolean
check
true: Success
false: Failed
**RespCode**
String
check
Response code from host server
**RespDesc**
String
check
Response message from host server
**ApprovalCode**
String
Approval code from host
**CardNum**
String
**EntryMode**
Int
0x01: Manual Entry
0x02: Swipe Entry(no CVV)
0x05: Contact ICC(with CVV)
0x07: Contactless
0x90: Swipe Entry(with CVV)
0x91: Contactless MSD
0x95: Contact ICC(no CVV)
**ExpiryDate**
String
**CardBrand**
String
exp.
Visa/MasterCard/Amex/Discover
**TransAmount**
String
\[Mandatory for Sale/Refund\]
check
“112233” means
1122.33(USD) 112.233(JOD)
**OtherAmount**
String
Cash back amount
**TipAmount**
String
Tip amount
**Balance**
String
**TaxAmount**
String
Tax amount, should be included in TransAmount
**DutyFreeAmount**
String
value of the tax exemption amount
**CurrencyCode**
String
Indicate currency code of transaction
156: RMB
840: USD
400: JOD
**CountryCode**
String
**DccOriCurrencyCode**
Integer
\[Mandatory when DCC\]
Original Request Currency Code to be converted
**DccOriAmount**
String
\[Mandatory when DCC\]
Original Request Amount
**DccFee**
String
\[Mandatory when DCC\]
DCC Fee of the transaction
**DccExchangeRate**
String
\[Mandatory when DCC\]
DCC exchange rate
**DccMarkUp**
String
\[Mandatory when DCC\]
DCC mark up
**DccFooterText**
String
\[Mandatory when DCC\]
DCC footer text
**TransDate**
String (YYYYMMDD)
check
Transaction date
exp. “20201212”
**TransTime**
String (hhmmss)
check
Transaction time
exp. “1614033”
**MID**
String
Merchant ID
**TID**
String
Terminal ID
**MerchantName**
String
Merchant Name
**MerchantAddress**
String
Merchant Address
**TraceNum**
String
Trace Number of payment app
**TransID**
String
Transaction ID returned from Host Server
**InvoiceNum**
String
Invoice Number of transaction
**RRN**
String
Retrieval Reference number returned from Host Server
**AuthCode**
String
Transaction Auth Code returned from Host Server
**OriTransIndexCode**
String
Original request TransIndexCode
**OriInvoiceNum**
String
Original transaction InvoiceNum
**OriTransId**
String
Indicate original transaction id
**OriRrn**
String
Indicate original RRN
**EmvAid**
String
Indicate EMV AID
**EmvAppName**
String
Indicate EMV app name
**EmvCryptogram**
String
Indicate EMV TC or ARQC
**EmvTVR**
String
Indicate EMV TVR
**AdditionalInfo**
String
**CardUniqueId**
String
Card unique ID is returned only when TransType is ReadCard.
###
[hashtag](https://smartpossdk.gitbook.io/paywizard-open-api/semi-integration/local-integration/payment-app-integration-protocol#id-9.-cancel-request-content)
9\. Cancel Request Content
Cancel request content is empty.
###
[hashtag](https://smartpossdk.gitbook.io/paywizard-open-api/semi-integration/local-integration/payment-app-integration-protocol#id-10.-cancel-response-content)
10\. Cancel Response Content
**NAME**
**FORMAT**
**DESCRIPTION**
**“cancelled”**
boolean
\[Mandatory\]
true: transaction cancelled.
False: transaction can’t be cancelled
[hashtag](https://smartpossdk.gitbook.io/paywizard-open-api/semi-integration/local-integration/payment-app-integration-protocol#annex-1)
Annex 1
-----------------------------------------------------------------------------------------------------------------------------------------------------
###
[hashtag](https://smartpossdk.gitbook.io/paywizard-open-api/semi-integration/local-integration/payment-app-integration-protocol#a1.1_transaction_type)
A1.1 Transaction Type
TransType
Description
**Purchase**
**PreAuth**
**IncrementalAuth**
**AuthCompletion**
**BalanceInquiry**
**Reversal**
**Refund**
**Settle**
**TipAdjust**
WorldPay only
**ReadCard**
To get card information, simply pass the TransType, and the CardUniqueId will be returned.
_Local transaction_
**QueryTransaction**
Query transaction result by OriTransIndexCode
**PrintLast**
**PrintTotal**
**PrintDetail**
**PrintParameter**
**GetPosInfo**
**VerifyCardPan**
Verify whether card number match original transaction
###
[hashtag](https://smartpossdk.gitbook.io/paywizard-open-api/semi-integration/local-integration/payment-app-integration-protocol#a1.2_transaction_type)
A1.2 Transaction Scheme
Scheme
Description
**Credit**
Credit card
**Debit**
Debit card
**EBT**
**ECS**
**QR**
QR transaction
[PreviousLocal Integrationchevron-left](https://smartpossdk.gitbook.io/paywizard-open-api/semi-integration/local-integration)
[NextSerial Connection Best Practicechevron-right](https://smartpossdk.gitbook.io/paywizard-open-api/semi-integration/local-integration/serial-connection-best-practice)
Last updated 22 days ago
* [1\. Introduction](https://smartpossdk.gitbook.io/paywizard-open-api/semi-integration/local-integration/payment-app-integration-protocol#id-1.-introduction)
* [2\. Transaction Flow](https://smartpossdk.gitbook.io/paywizard-open-api/semi-integration/local-integration/payment-app-integration-protocol#id-2.-transaction-flow)
* [3\. Communication Configuration](https://smartpossdk.gitbook.io/paywizard-open-api/semi-integration/local-integration/payment-app-integration-protocol#id-3.-communication-configuration)
* [4\. Data Format](https://smartpossdk.gitbook.io/paywizard-open-api/semi-integration/local-integration/payment-app-integration-protocol#id-4.-data-format)
* [5\. Handshake Request Content](https://smartpossdk.gitbook.io/paywizard-open-api/semi-integration/local-integration/payment-app-integration-protocol#id-5.-handshake-request-content)
* [6\. Handshake Response Content](https://smartpossdk.gitbook.io/paywizard-open-api/semi-integration/local-integration/payment-app-integration-protocol#id-6.-handshake-response-content)
* [7\. Transaction Request Content](https://smartpossdk.gitbook.io/paywizard-open-api/semi-integration/local-integration/payment-app-integration-protocol#id-7.-transaction-request-content)
* [8\. Transaction Response Content](https://smartpossdk.gitbook.io/paywizard-open-api/semi-integration/local-integration/payment-app-integration-protocol#id-8.-transaction-response-content)
* [9\. Cancel Request Content](https://smartpossdk.gitbook.io/paywizard-open-api/semi-integration/local-integration/payment-app-integration-protocol#id-9.-cancel-request-content)
* [10\. Cancel Response Content](https://smartpossdk.gitbook.io/paywizard-open-api/semi-integration/local-integration/payment-app-integration-protocol#id-10.-cancel-response-content)
* [Annex 1](https://smartpossdk.gitbook.io/paywizard-open-api/semi-integration/local-integration/payment-app-integration-protocol#annex-1)
* [A1.1 Transaction Type](https://smartpossdk.gitbook.io/paywizard-open-api/semi-integration/local-integration/payment-app-integration-protocol#a1.1_transaction_type)
* [A1.2 Transaction Scheme](https://smartpossdk.gitbook.io/paywizard-open-api/semi-integration/local-integration/payment-app-integration-protocol#a1.2_transaction_type)
sun-brightdesktopmoon
Copy
Fixed 0x02
Copy
Byte 1:
0x01 indicate data from Cashier
0x02 indicate data from POS
0xF1 indicate Handshake Request
0xF2 indicate Handshake Response
0xC1 indicate Cancel Request
0xC2 indicate Cancel Response
Byte 2:
Reserved. Set to 0x00.
Byte 3-4:
Sequence number, request package set to X, response package set to X+1 exp.
Request [01] [0F], Response [01] [10]
Copy
Exp. [01] [0F] means 0x10F (271) bytes.
Copy
BCC algorithm:
BCC := [VERSION] xor [CTRL Byte1] xor [CTRL Byte2] xor … xor [ETX]
Copy
{
“TransType”: “Purchase”,
“TransIndexCode”: “112233”,
“TransAmount”: “10000”,
“CurrencyCode”: “840”,
“ReqTransDate”: “20210302”,
“ReqTransTime”: “144230”,
“OriTransId”: “”,
“OriRrn “: “”,
“EnableReceipt “: true,
“AppendingReceiptInfo “: “”,
“SkipConfirmProcedure”: false
}
sun-brightdesktopmoon
---
# Payment App AIDL Integration Protocol | Paywizard Integration
###
[hashtag](https://smartpossdk.gitbook.io/paywizard-open-api/semi-integration/internal-integration/payment-app-aidl-integration-protocol#id-1.-introduction)
1\. Introduction
This document descripts how to use android AIDL to call payment app.
###
[hashtag](https://smartpossdk.gitbook.io/paywizard-open-api/semi-integration/internal-integration/payment-app-aidl-integration-protocol#id-2.-transaction-flow)
2\. Transaction Flow
a) put the **aidl** and java folders into path **src/main** under app module
b) rebuild your project to build aidl source code
c) bind the service and call payment app
package: **com.wizarpos.opc**
action: **com.wizarpos.payment.aidl.pay**
File you will need in your android project:
file-download
219B
[IPaymentPayCallback.aidl](https://2631785516-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FY7FuzH91SaNfvhwFA9Ic%2Fuploads%2FPmzk8lnaTZamZ6comJwK%2FIPaymentPayCallback.aidl?alt=media&token=727240ef-2f51-4f6e-8188-1b6269e38e04)
downloadDownload[arrow-up-right-from-squareOpen](https://2631785516-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FY7FuzH91SaNfvhwFA9Ic%2Fuploads%2FPmzk8lnaTZamZ6comJwK%2FIPaymentPayCallback.aidl?alt=media&token=727240ef-2f51-4f6e-8188-1b6269e38e04)
file-download
716B
[IPaymentPay(1).aidl](https://2631785516-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FY7FuzH91SaNfvhwFA9Ic%2Fuploads%2FoovGCo5ZCsjbADgiKrSU%2FIPaymentPay(1).aidl?alt=media&token=8614cb6d-efab-4bee-9514-a586de87b7a9)
downloadDownload[arrow-up-right-from-squareOpen](https://2631785516-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FY7FuzH91SaNfvhwFA9Ic%2Fuploads%2FoovGCo5ZCsjbADgiKrSU%2FIPaymentPay(1).aidl?alt=media&token=8614cb6d-efab-4bee-9514-a586de87b7a9)
###
[hashtag](https://smartpossdk.gitbook.io/paywizard-open-api/semi-integration/internal-integration/payment-app-aidl-integration-protocol#id-3.-transaction-request-content)
3\. Transaction Request Content
**Transaction Request is content is json format as below:**
NAME
FORMAT
MANDATORY
DESCRIPTION
**TransType**
String
check
Indicate transaction type to be performed.
[See A1.1 Transaction Type](https://smartpossdk.gitbook.io/paywizard-open-api/semi-integration/internal-integration/payment-app-aidl-integration-protocol#a1.1_transaction_type)
**TransScheme**
String
Cooperation with TransType，used in specific schemes
[See A1.2 Transaction Scheme](https://smartpossdk.gitbook.io/paywizard-open-api/semi-integration/internal-integration/payment-app-aidl-integration-protocol#a1.2_transaction_type)
**CallerName**
String
Caller name
**TransIndexCode**
String
Indicate Cashier trace number
Should be unique for every transaction
**BusinessNum**
String
Business registration number
**TerminalNum**
String
Terminal number
**TransAmount**
String
\[Mandatory for payment\]
check
Total amount including OtherAmount and TipAmount
“112233” means 1122.33(USD) or 112.233(JOD) depending on CurrencyCode
**OtherAmount**
String
Cash back amount
**TipAmount**
String
Tip amount
**TaxAmount**
String
Tax amount, should be included in TransAmount
**DutyFreeAmount**
String
value of the tax exemption amount, should be included in TransAmount
**CurrencyCode**
String
check
Indicate currency code of transaction
156: RMB
840: USD
400: JOD
**ReqTransDate**
String (YYYYMMDD)
exp. “20201212”
**ReqTransTime**
String (hhmmss)
exp. “1614033”
**OriTransIndexCode**
String
Original request TransIndexCode
**OriTraceNum**
String
**OriInvoiceNum**
String
Original transaction InvoiceNum
**OriTransId**
String
Indicate original transaction id
**OriRrn**
String
Indicate original RRN
**OriTransDate**
String(YYYYMMDD)
Indicate original transaction date
**OriTransTime**
String(hhmmss)
Indicate original transaction time
**EnableReceipt**
boolean
false-Disable Receipt
true-Enable Receipt
**AppendingReceiptInfo**
String
Indicate message to be printed on receipt
**SkipConfirmProcedure**
boolean
false-Don not Skip
true-Skip Confirm Procedure
**EnableCancelInPayment**
boolean
true-Enable user cancel operation
false-Disable user cancel operation
**AdditionalInfo**
String
Request content sample:
###
[hashtag](https://smartpossdk.gitbook.io/paywizard-open-api/semi-integration/internal-integration/payment-app-aidl-integration-protocol#id-4.-transaction-response-content)
4\. Transaction Response Content
**Transaction Request is content is json format which contain request data as below:**
NAME
FORMAT
MANDATORY
DESCRIPTION
**TransType**
String
check
Indicate transaction type to be performed.
**TransScheme**
String
Cooperation with TransType，used in specific schemes
[See A1.2 Transaction Scheme](https://smartpossdk.gitbook.io/paywizard-open-api/semi-integration/internal-integration/payment-app-aidl-integration-protocol#a1.2_transaction_type)
**CallerName**
String
Caller name
**TransIndexCode**
String
Indicate Cashier trace number
**TransResult**
boolean
check
true: Success
false: Failed
**RespCode**
String
check
Response code from host server
**RespDesc**
String
check
Response message from host server
**ApprovalCode**
String
Approval code from host
**CardNum**
String
**EntryMode**
Int
0x01: Manual Entry
0x02: Swipe Entry(no CVV)
0x05: Contact ICC(with CVV)
0x07: Contactless
0x90: Swipe Entry(with CVV)
0x91: Contactless MSD
0x95: Contact ICC(no CVV)
**ExpiryDate**
String
**CardBrand**
String
exp.
Visa/MasterCard/Amex/Discover
**TransAmount**
String
\[Mandatory for Sale/Refund\]
check
“112233” means
1122.33(USD) 112.233(JOD)
**OtherAmount**
String
Cash back amount
**TipAmount**
String
Tip amount
**Balance**
String
**TaxAmount**
String
Tax amount, should be included in TransAmount
**DutyFreeAmount**
String
value of the tax exemption amount
**CurrencyCode**
String
Indicate currency code of transaction
156: RMB
840: USD
400: JOD
**CountryCode**
String
**DccOriCurrencyCode**
Integer
\[Mandatory when DCC\]
Original Request Currency Code to be converted
**DccOriAmount**
String
\[Mandatory when DCC\]
Original Request Amount
**DccFee**
String
\[Mandatory when DCC\]
DCC Fee of the transaction
**DccExchangeRate**
String
\[Mandatory when DCC\]
DCC exchange rate
**DccMarkUp**
String
\[Mandatory when DCC\]
DCC mark up
**DccFooterText**
String
\[Mandatory when DCC\]
DCC footer text
**TransDate**
String (YYYYMMDD)
check
Transaction date
exp. “20201212”
**TransTime**
String (hhmmss)
check
Transaction time
exp. “1614033”
**MID**
String
Merchant ID
**TID**
String
Terminal ID
**MerchantName**
String
Merchant Name
**MerchantAddress**
String
Merchant Address
**TraceNum**
String
Trace Number of payment app
**TransID**
String
Transaction ID returned from Host Server
**InvoiceNum**
String
Invoice Number of transaction
**RRN**
String
Retrieval Reference number returned from Host Server
**AuthCode**
String
Transaction Auth Code returned from Host Server
**OriTransIndexCode**
String
Original request TransIndexCode
**OriInvoiceNum**
String
Original transaction InvoiceNum
**OriTransId**
String
Indicate original transaction id
**OriRrn**
String
Indicate original RRN
**EmvAid**
String
Indicate EMV AID
**EmvAppName**
String
Indicate EMV app name
**EmvCryptogram**
String
Indicate EMV TC or ARQC
**EmvTVR**
String
Indicate EMV TVR
**AdditionalInfo**
String
**CardUniqueId**
String
Card unique ID is returned only when TransType is ReadCard.
[hashtag](https://smartpossdk.gitbook.io/paywizard-open-api/semi-integration/internal-integration/payment-app-aidl-integration-protocol#annex-1)
Annex 1
-------------------------------------------------------------------------------------------------------------------------------------------------------------
###
[hashtag](https://smartpossdk.gitbook.io/paywizard-open-api/semi-integration/internal-integration/payment-app-aidl-integration-protocol#a1.1_transaction_type)
A1.1 Transaction Type
TransType
Description
**Purchase**
**PreAuth**
**IncrementalAuth**
**AuthCompletion**
**BalanceInquiry**
**Reversal**
**Refund**
**Settle**
**TipAdjust**
WorldPay only
**ReadCard**
To get card information, simply pass the TransType, and the CardUniqueId will be returned.
_Local transaction_
**QueryTransaction**
Query transaction result by OriTransIndexCode
**PrintLast**
**PrintTotal**
**PrintDetail**
**PrintParameter**
**GetPosInfo**
**VerifyCardPan**
Verify whether card number match original transaction
###
[hashtag](https://smartpossdk.gitbook.io/paywizard-open-api/semi-integration/internal-integration/payment-app-aidl-integration-protocol#a1.2_transaction_type)
A1.2 Transaction Scheme
Scheme
Description
**Credit**
Credit card
**Debit**
Debit card
**EBT**
**ECS**
**QR**
QR transaction
[PreviousInternal Integrationchevron-left](https://smartpossdk.gitbook.io/paywizard-open-api/semi-integration/internal-integration)
[NextAIDL Integration Best Practicechevron-right](https://smartpossdk.gitbook.io/paywizard-open-api/semi-integration/internal-integration/aidl-integration-best-practice)
Last updated 22 days ago
* [1\. Introduction](https://smartpossdk.gitbook.io/paywizard-open-api/semi-integration/internal-integration/payment-app-aidl-integration-protocol#id-1.-introduction)
* [2\. Transaction Flow](https://smartpossdk.gitbook.io/paywizard-open-api/semi-integration/internal-integration/payment-app-aidl-integration-protocol#id-2.-transaction-flow)
* [3\. Transaction Request Content](https://smartpossdk.gitbook.io/paywizard-open-api/semi-integration/internal-integration/payment-app-aidl-integration-protocol#id-3.-transaction-request-content)
* [4\. Transaction Response Content](https://smartpossdk.gitbook.io/paywizard-open-api/semi-integration/internal-integration/payment-app-aidl-integration-protocol#id-4.-transaction-response-content)
* [Annex 1](https://smartpossdk.gitbook.io/paywizard-open-api/semi-integration/internal-integration/payment-app-aidl-integration-protocol#annex-1)
* [A1.1 Transaction Type](https://smartpossdk.gitbook.io/paywizard-open-api/semi-integration/internal-integration/payment-app-aidl-integration-protocol#a1.1_transaction_type)
* [A1.2 Transaction Scheme](https://smartpossdk.gitbook.io/paywizard-open-api/semi-integration/internal-integration/payment-app-aidl-integration-protocol#a1.2_transaction_type)
sun-brightdesktopmoon
Copy
{
“TransType”: “Purchase”,
“TransIndexCode”: “112233”,
“TransAmount”: “10000”,
“CurrencyCode”: “840”,
“ReqTransDate”: “20210302”,
“ReqTransTime”: “144230”,
“OriTransId”: “”,
“OriRrn “: “”,
“EnableReceipt “: true,
“AppendingReceiptInfo “: “”,
“SkipConfirmProcedure”: false
}
sun-brightdesktopmoon
---
# Client SDK API | Paywizard Integration
This section details the methods and objects provided by the PayWizard Web Element SDK.
[hashtag](https://smartpossdk.gitbook.io/paywizard-open-api/online-card-payment/client-sdk-api#paywizard-clienttoken-options)
PayWizard(clientToken, options)
------------------------------------------------------------------------------------------------------------------------------------------------------------------
Initializes the PayWizard SDK instance.
Parameter
Type
Required
Description
`clientToken`
string
✓
Developer Token, used for authentication
`options`
Object
Optional parameters, currently undefined
###
[hashtag](https://smartpossdk.gitbook.io/paywizard-open-api/online-card-payment/client-sdk-api#returns)
**Returns**
SDK instance, providing the `initCheckout` method to create a checkout session.
###
[hashtag](https://smartpossdk.gitbook.io/paywizard-open-api/online-card-payment/client-sdk-api#example)
**Example**
Copy
const payWizard = PayWizard("your-client-token");
[hashtag](https://smartpossdk.gitbook.io/paywizard-open-api/online-card-payment/client-sdk-api#paywizard.initcheckout-params)
payWizard.initCheckout(params)
-----------------------------------------------------------------------------------------------------------------------------------------------------------------
Creates a new checkout session and returns the checkout object.
Parameter
Type
Required
Description
`params.clientId`
string
✓
Unique client identifier
`params.merchantId`
string
✓
Unique merchant identifier
`params.checkoutId`
string
✓
Unique checkout session identifier (obtained from server-side call to "Create Online Payment Order" API)
`params.elementsOptions`
Object
UI configuration options
`params.elementsOptions.appearance`
Object
Appearance-related configuration
`params.elementsOptions.appearance.width`
string | number
iframe width
`params.elementsOptions.appearance.theme`
`"light"` | `"night"`
Interface theme
`params.savePaymentMethods`
boolean
Whether to allow saving the customer's payment methods
###
[hashtag](https://smartpossdk.gitbook.io/paywizard-open-api/online-card-payment/client-sdk-api#about-params.checkoutid)
**About** `**params.checkoutId**`
`checkoutId` is the unique identifier for the checkout session, obtained by your server-side through calling the "Create Online Payment Order" API. Brief information about this API is mentioned in the "Core Integration Steps", and detailed information can be found in the Server-side API Details section at the end of the document.
###
[hashtag](https://smartpossdk.gitbook.io/paywizard-open-api/online-card-payment/client-sdk-api#returns-1)
**Returns**
`Promise` - A Promise that resolves to a `Checkout` object.
###
[hashtag](https://smartpossdk.gitbook.io/paywizard-open-api/online-card-payment/client-sdk-api#example-1)
**Example**
[hashtag](https://smartpossdk.gitbook.io/paywizard-open-api/online-card-payment/client-sdk-api#checkout-object)
Checkout Object
------------------------------------------------------------------------------------------------------------------------------------
The `Checkout` object provides methods for managing the payment process. It is the return value after a successful call to `payWizard.initCheckout()`.
###
[hashtag](https://smartpossdk.gitbook.io/paywizard-open-api/online-card-payment/client-sdk-api#checkout.session-options)
**checkout.session(options)**
Sets session-related parameters.
Parameter
Type
Required
Description
`options.customer`
string
Unique customer identifier, used for payment method storage
`options.card`
string
Saved payment method identifier
####
[hashtag](https://smartpossdk.gitbook.io/paywizard-open-api/online-card-payment/client-sdk-api#about-options.card)
**About** `**options.card**`
`options.card` is the identifier of the saved payment method (i.e., `cardToken`). If your user has previously agreed to save payment methods, you can obtain their `cardToken` list by calling the "Retrieve Bank Card Information by UserId" API on your server-side. Detailed information about this API can be found in the Server-side API Details section at the end of the document.
####
[hashtag](https://smartpossdk.gitbook.io/paywizard-open-api/online-card-payment/client-sdk-api#returns-2)
**Returns**
None
####
[hashtag](https://smartpossdk.gitbook.io/paywizard-open-api/online-card-payment/client-sdk-api#example-2)
**Example**
###
[hashtag](https://smartpossdk.gitbook.io/paywizard-open-api/online-card-payment/client-sdk-api#checkout.mount-selector)
**checkout.mount(selector)**
Mounts the payment interface to the specified DOM element.
Parameter
Type
Required
Description
`selector`
string
✓
CSS selector specifying the mount point
**Returns**
`Promise` - A Promise that resolves when mounting is complete.
**Example**
###
[hashtag](https://smartpossdk.gitbook.io/paywizard-open-api/online-card-payment/client-sdk-api#checkout.unmount)
**checkout.unmount()**
Unmounts the payment interface from the DOM.
**Returns**
None
**Example**
###
[hashtag](https://smartpossdk.gitbook.io/paywizard-open-api/online-card-payment/client-sdk-api#checkout.destroy)
**checkout.destroy()**
Destroys the checkout instance and cleans up all resources.
**Returns**
None
**Example**
###
[hashtag](https://smartpossdk.gitbook.io/paywizard-open-api/online-card-payment/client-sdk-api#checkout.confirm)
**checkout.confirm()**
Confirms the payment transaction.
**Returns**
`Promise