Getting Started v1.50

Introduction

This document contains the developer guide for third party POS to integrate their POS system with AppsPOS customer loyalty programs/ Rewards systems for mobile app users to perform over the counter transactions including voucher redemption and digital payments.

There are a total of 8 APIs that will be made available to third party POS for mobile app integration as listed below:

API No.	API Description	API Name
API 1	Order API	voucher_to_add_cart_from_pos
API 2	Proceed to Payment API	order_to_release_payment
API 3	Payment Status API	check_paid_status
API 4	Cancel Transaction API	cancel_transaction
API 5	Remove Voucher API	remove_voucher_from_pos
API 6	Refund API	refund
API 7	Complete Transaction	payment_completed
API 8	Get Bill Info	order_update_discount_svc_gst

You can reach out to us at contact@appspos.com if you need technical support on API integration matters.

Beta server link	To be provided when you contact AppsPOS
User ID	To be provided	Password	To be provided

Application Programming Interfaces (API)

Order API

Sample Request:

{
    "transaction_qrcode": "QR-20191218-724B-0000005",
    "branch_code": "B1",
    "invoice_no": "64",
    "api_key": "fff426a0-3ddf-43f6-93f9-8a63ce29cb76",
    "language_code": "en",
    "pos_name": "20171004124370",
    "request_signature": "c4661a88d3e68c69690563eeed266c2f761e1aff63a5ba17cd67c9dda61dc8a1",
    "request_signature": "cart_details"
    "data": [
        {
            "price": -2.00,
            "qty": 1,
            "special_comment": "",
            "product_code": "ITEM01",
            "product_name": "Item Discount",
            "category_code": "APOSDUM01",
            "category_name": "Dummy",
            "product_type": "1"
        },
        {
            "price": -1.26,
            "qty": 2,
            "special_comment": "",
            "product_code": "PD009",
            "product_name": "Percentage Discount",
            "category_code": "APOSDUM01",
            "category_name": "Dummy",
            "product_type": "2"
        },
        {
            "price": 3.10,
            "qty": 1,
            "special_comment": "",
            "product_code": "APOSPRO01",
            "product_name": "Chicken Chunky Pops with Cheese Sauce",
            "category_code": "APOSCAT01",
            "category_name": "SEASONAL",
            "product_type": "0"
        },
        {
            "price": 3.50,
            "qty": 1,
            "special_comment": "",
            "product_code": "APOSPRO02",
            "product_name": "Spicy Cheese Mid Joint Wings",
            "category_code": "APOSCAT01",
            "category_name": "SEASONAL",
            "product_type": "0"
        },
        {
            "price": 4.00,
            "qty": 2,
            "special_comment": "",
            "product_code": "APOSPRO18",
            "product_name": "Black Pepper Chicken ",
            "category_code": "APOSCAT01",
            "category_name": "SEASONAL",
            "product_type": "0"
        },
        {
            "price": 2.00,
            "qty": 1,
            "special_comment": "",
            "product_code": "APOSPRO18",
            "product_name": "Black Pepper Chicken ",
            "category_code": "APOSCAT01",
            "category_name": "SEASONAL",
            "product_type": "0"
        }
    ]
    
}

Sample Response:

{
    "status": "1",
    "message": "Item(s) added to cart successfully",
    "server_time": "2019-12-19 13:44:09",
    "data": {
        "total_final_amount": 2.34,
        "is_zero_dollar_pay": false,
        "stop_loading_this_api": false,
        "request_signature": c4661a88d3e68c69690563eeed266c2f761e1aff63a5ba17cd67c9dda61dc8a1,
        "response_signature": e5629be69ea8687ec9a6dc9e501e43fec95a06d0716b0ee5a8b4c177afd4a593,
        "last_pos_request_unique_number": APOS-20191219-76BA-0000001,
        "values_voucher_details": [
            {
                "price": -2.00,
                "qty": 1,
                "special_comment": "",
                "product_code": "ITEM01",
                "product_name": "Item Discount",
                "category_code": "APOSDUM01",
                "category_name": "Dummy",
                "product_type": "1"
            },
            {
                "price": -1.26,
                "qty": 2,
                "special_comment": "",
                "product_code": "PD009",
                "product_name": "Percentage Discount",
                "category_code": "APOSDUM01",
                "category_name": "Dummy",
                "product_type": "2"
            },
            {
                "price": 3.10,
                "qty": 1,
                "special_comment": "",
                "product_code": "APOSPRO01",
                "product_name": "Chicken Chunky Pops with Cheese Sauce",
                "category_code": "APOSCAT01",
                "category_name": "SEASONAL",
                "product_type": "0"
            },
            {
                "price": 3.50,
                "qty": 1,
                "special_comment": "",
                "product_code": "APOSPRO02",
                "product_name": "Spicy Cheese Mid Joint Wings",
                "category_code": "APOSCAT01",
                "category_name": "SEASONAL",
                "product_type": "0"
            },
            {
                "price": 4.00,
                "qty": 2,
                "special_comment": "",
                "product_code": "APOSPRO18",
                "product_name": "Black Pepper Chicken ",
                "category_code": "APOSCAT01",
                "category_name": "SEASONAL",
                "product_type": "0"
            },
            {
                "price": 2.00,
                "qty": 1,
                "special_comment": "",
                "product_code": "APOSPRO18",
                "product_name": "Black Pepper Chicken ",
                "category_code": "APOSCAT01",
                "category_name": "SEASONAL",
                "product_type": "0"
            }
        ]
    }
}

This API allow mobile app users to receive order details from third-party POS after the QR code from mobile app is scanned and read by third-party POS.

API name: voucher_to_add_cart_from_pos

Fields

Field name	Data Type & Max Length	Mandatory / Optional	Description
transaction_qrcode	string(50)	M	The QR code value
branch_code	string(50)	M	The identification number of the outlet assigned by third party POS
invoice_no	string(50)	M	The identification number of invoice
api_key	string(50)	M	The code to authenticate the user or calling program to an API
language_code	string(2)	M	The language code, set to en for English by default
pos_name	string(50)	M	The identification number of the machine assigned by third party POS
request_signature	string(500)	M	Refer to section 3(a)(iii)
cart_details		M
- price	Amount(2d.p.)	M	The total price of the product eg. If product cost $2 and there are 3 quantity purchased, value return is $6
- qty	int	M	The quantity of the product
- special_comment	string(250)	O	Remarks
- product_code	string(20)	M	The identification number of the product
- product_name	string(250)	M	The name of the product
- category_code	string(20)	M	The identification code of the category that item is from
- category_name	string(250)	M	The name of the category that item is from
- product_type	int	M	The classification of product: 1: Item discount 2: Percentage discount 0: Normal product

Field name	Data Type & Max Length	Mandatory / Optional	Description
status	int	M	Response status
show_status	boolean	M	Status to inform to display message
message	string(500)	M	The displayed message
server_time	datetime	M	The time of the response
total_final_amount	decimal	M	The total final amount of the transaction
is_zero_dollar_pay	boolean	M	Status to inform no payable amount. Assume customer only want to redeem voucher for productX, item voucher for productX input to mobile app and item entered to POS, total payable will be zero
stop_loading_this_api	boolean	M	Status to stop loading any further API and return to POS
request_signature	string(500)	M	Refer to section 3(a)(iii)
response_signature	string(500)	M	Refer to section 3(a)(iii)
last_pos_request_unique_number	string(50)	M	Unique identification number for request to be used in upcoming transaction
values_voucher_details
- price	decimal	M	The price of the voucher applied
- qty	int	M	The quantity of the voucher applied
- voucher_type	int	M	The type of voucher applied 1: Value voucher 2: Percentage Discount voucher 3: Item voucher
- voucher_unique_number	string(50)	M	The identification number of the voucher
- voucher_values	string(50)	M	The voucher value: - Numerical for dollar value voucher - Numerical for percentagediscount voucher Item code for item voucher

Digital Signature

For the creation of the request signature, the following values are to be concatenated with ampersand(&) between each value, leading and trailing space removed. Please note that the order of the fields is important.

Request Signature
Field name	Description
api_key	The code to authenticate the user or calling program to an API
transaction_qrcode	The QR code value
branch_code	The identification number of the outlet assigned by third party POS
invoice_no	The identification number of invoice
pos_name	The identification number of the machine assigned by third party POS
- product_code	The identification number of the product
- category_code	The identification code of the category that item is from
- product_type	The classification of product: 1: Item discount 2: Percentage discount 0: Normal product
- price	The price of the product
- qty	The quantity of the product

For the creation of the response signature, the following values are to be concatenated with ampersand(&) between each value, leading and trailing space removed. Please note that the order of the fields is important.

Response Signature
Field name	Description
total_final_amount	The final total payable of the invoice
is_zero_dollar_pay-> 1 when true, 0 when false	Status to inform no payable amount. Assume customer only want to redeem voucher for productX, item voucher for productX input to mobile app and item entered to POS, total payable will be zero
api_key	The code to authenticate the user or calling program to an API
transaction_qrcode	The QR code value
branch_code	The identification number of the outlet assigned by third party POS
invoice_no	The identification number of invoice
pos_name - voucher_unique_number - voucher_type - voucher_values - price - qty	The identification number of the machine assigned by third party POS

Get Bill Info(Add on V1.5)

Sample Request:

{
    "api_key": "86712516-1668-4169-8440-81db5f5edf1e",
    "transaction_qrcode": "QR-20211019-17F4-0000027",
    "branch_code": "OCK_AMK",
    "invoice_no": "OCK_AMK-19102021065355",
    "language_code": "en",
    "pos_name": "20210120115451",
    "discount": "0.52",
    "svc": "1",
    "gst": "1",
    "round_off": "-0.08",
    "request_signature": "28e71c9d306ef7ef339615004bcc06cd51b643a2124a51ec4034414ae7b59e71"
}

Sample Response:

{
    "status": "1",
    "show_status": "0",
    "message": "MsgResticed",
    "server_time": "2021-10-19 16:13:07",
    "data": {
        "request_signature": "28e71c9d306ef7ef339615004bcc06cd51b643a2124a51ec4034414ae7b59e71",
        "response_signature": "82e31e7baa24f55b3af7e6a48ddc618410b84f480884863ecf80f0b5dd8f889d",
        "stop_loading_this_api": false,
        "request_signature": c4661a88d3e68c69690563eeed266c2f761e1aff63a5ba17cd67c9dda61dc8a1,
        "calculation_details": {
            "sub_total": 3.2,
            "gst": 1,
            "svc": 1,
            "discount": "0.52",
            "round_off": "-0.08",
            "total_payable": "4.6"
        }
    }
}

This API allows POS tosend additional bill information like discount, service charge, GST, Round Off.

API Name: order_update_discount_svc_gst

Fields

Field name	Data Type & Max Length	Mandatory / Optional	Description
transaction_qrcode	string(50)	M	The QR code value
branch_code	string(50)	M	The identification number of the outlet assigned by third party POS
api_key	string(50)	M	The code to authenticate the user or calling program to an API
language_code	string(2)	M	The language code, set to en for English by default
pos_name	string(50)	M	The identification number of the machine assigned by third party POS
request_signature	string(500)	M	Refer to section 3(b)(iii)
discount	decimal	O	If available with two decimal places
svc	decimal	O	If available with two decimal places
gst	decimal	O	If available with two decimal places
round_off	decimal	O	If available with two decimal places

Field name	Data Type & Max Length	Mandatory / Optional	Description
status	int	M	Response status
show_status	boolean	M	Status to inform to display message
message	string(500)	M	The displayed message
server_time	datetime	M	The time of the response
data
-request_signature	string(500)	M	Refer to section 3(b)(iii)
-response_signature	string(500)	M	Refer to section 3(b)(iii)
-calculation_details
--sub_total	decimal	M	Before Any deduction
--gst	decimal	M	External gst
--svc	decimal	M	External svc
--discount	decimal	M	External discount
--round_off	decimal	M	Round off on the total payable
--total_payable	decimal	M	Final billing amount and pos side final amount

Digital Signature

Request Signature
Field name	Description
api_key	The code to authenticate the user or calling program to an API
last_request_unique_number	Unique identification number for request to be used in upcoming transaction from API 1
transaction_qrcode	The QR code value
branch_code	The identification number of the outlet
pos_name	The identification number of the machine
Discount	If available with two decimal places
Svc	If available with two decimal places
Gst	If available with two decimal places
Round off	If available with two decimal places

Response Signature
Field name	Description
api_key	The code to authenticate the user or calling program to an API
transaction_qrcode	The QR code value
branch_code	The identification number of the outlet assigned by third party POS
pos_name	The identification number of the machine assigned by third party POS
total_payable	The total payable which need to verify with the pos

Proceed to Payment API

Sample Request:

{
    "transaction_qrcode": "QR-20191218-724B-0000005",
    "branch_code": "B1",
    "api_key": "fff426a0-3ddf-43f6-93f9-8a63ce29cb76",
    "language_code": "en",
    "pos_name": "20171004124370",
    "request_signature": "7563696a7e565a263ba4ae393b835e979e4c026c5752c3c8bd22bf46331d6b8c",
    "can_release_for_payment": 1
}

Sample Response:

{
    "status": "1",
    "show_status": "1",
    "message": "successful",
    "server_time": "2019-12-19 13:51:37",
    "data": {
        
    }
}

This API is to verify that the received total payable matched with POS and to allow user to proceed to payment page.

API Name: order_to_release_payment

Fields

Field name	Data Type & Max Length	Mandatory / Optional	Description
transaction_qrcode	string(50)	M	The QR code value
branch_code	string(50)	M	The identification number of the outlet assigned by third party POS
api_key	string(50)	M	The code to authenticate the user or calling program to an API
language_code	string(2)	M	The language code, set to en for English by default
pos_name	string(50)	M	The identification number of the machine assigned by third party POS
request_signature	string(500)	M	Refer to section 3(c)(iii)
can_release_for_payment	boolean	O	If total payable is equal to API 1’s final amount and signature verified, then send 1, else 0
total_payable	decimal	O	Need to send the final payable.To make third party POS Payable and AppsPOS . if verified.will give success response else failure response (Included in V1.4)

Field name	Data Type & Max Length	Mandatory / Optional	Description
status	int	M	Response status
show_status	boolean	M	Status to inform to display message
message	string(500)	M	The displayed message
server_time	datetime	M	The time of the response

Digital Signature

Request Signature
Field name	Description
api_key	The code to authenticate the user or calling program to an API
last_request_unique_number	Unique identification number for request to be used in upcoming transaction from API 1
transaction_qrcode	The QR code value
branch_code	The identification number of the outlet
pos_name	The identification number of the machine

Payment Status API

Sample Request:

{
    "api_key": "fff426a0-3ddf-43f6-93f9-8a63ce29cb76",
    "transaction_qrcode": "QR-20200130-4D03-0000002",
    "language_code": "en",
    "branch_code": "B1",
    "pos_name": "20171004124370",
    "payment_status_reference_no": "150",
    "request_signature": "ef8f87a3f9be3da6aae98fefe01bc9c2509aca348b17fd218dd0e6dff79b41d7"
}

Sample Response:
[Fail(status:0) & In Process(status:2)]

{
    "status": "2",
    "show_status": "0",
    "message": "Payment in process..",
    "server_time": "2019-12-19 13:53:12",
    "data": {
        "request_id": "",
        "transaction_id": "",
        "paid_amount": 0.0,
        "refund_id": "",
        "payment_status_reference_no": "150"
    }
}

Sample Response:
[Success(status:1)]

{
    "status": "1",
    "show_status": "1",
    "message": "Payment made sucessfully",
    "server_time": "2020-03-05 13:06:28",
    "data": {
        "request_id": "dbssg-test-registercc-20200203080713",
        "transaction_id": "b5dff350-1df6-4594-94e7-b15da43328e7",
        "paid_amount": 2.00,
        "refund_id": "05032020103628",
        "payment_status_reference_no": "150"
    }
}

This API is to check the status of payment upon successful Cart Verification API request. The API will call and time out in 2 mins and if status 1 then successful payment if status 0 payment failed so we can reinitialize from scan qrcode again if status 2 then customer not clicked pay button then we need to re-scan qrcode and ask customer to make payment.

API Name: check_paid_status

Fields

Field name	Data Type & Max Length	Mandatory / Optional	Description
transaction_qrcode	string(50)	M	The QR code value
api_key	string(50)	M	The code to authenticate the user or calling program to an API
language_code	string(2)	M	The language code, set to en for English by default
branch_code	string(50)	M	The identification number of the outlet
pos_name	string(50)	M	The identification number of the machine
payment_status_reference_no	string(50)	M	The unique identification number from Third party POS
request_signature	string(500)	M	Refer to section 3(d)(iii)

Field name	Data Type & Max Length	Mandatory / Optional	Description
status	int	M	Status code: 0: Fail 1: Successful 2: In process
show_status	boolean	M	To return 0 if fail or 1 if success
message	string(500)	M	The displayed message
server_time	datetime	M	The time of the response
request_id	string(250)	M	Banker ref number (Change in V1.3)
transaction_id	string(250)	M	The identification number of the successful transaction
paid_amount	decimal	M	The amount paid in the successful transaction
refund_id	string(50)	M	Reference number to initialise refund request
payment_status_reference_no	string(50)	M	The unique identification number from Third party POS

Digital Signature

For the creation of the request signature, the following values are to be concatenated withampersand(&) between each value, leading and trailing space removed. Please note that the order of the fields is important.

Request Signature
Field name	Description
api_key	The code to authenticate the user or calling program to an API
last_request_unique_number	Unique identification number for request to be used in upcoming transaction from API 1 (Included in V1.3)
transaction_qrcode	The QR code value
branch_code	The identification number of the outlet
pos_name	The identification number of the machine
payment_status_reference_no	The unique identification number from Third party POS
payment_status_reference_no

Cancel Transaction API

Sample Request:

{
    "transaction_qrcode": "QR-20191219-FF99-0000001",
    "api_key": "fff426a0-3ddf-43f6-93f9-8a63ce29cb76",
    "language_code": "en",
    "branch_code": "B1",
    "pos_name": "20171004124370",
    "request_signature": "ef1740be8c6b03b0eec0d28cf90a5aa3d52598b761679aee84dfd026d5fa1fc5"
}

Sample Response:

{
    "status": "1",
    "show_status": "1",
    "message": "successful",
    "server_time": "2019-12-19 13:56:34",
    "data": {

    }
}

This API allow the cancellation of the transaction from third party POS

API Name: cancel_transaction

Fields

Field name	Data Type & Max Length	Mandatory / Optional	Description
transaction_qrcode	string(50)	M	The QR code value
api_key	string(50)	M	The code to authenticate the user or calling program to an API
language_code	string(2)	M	The language code, set to en for English by default
branch_code	string(50)	M	The identification number of the outlet
pos_name	string(50)	M	The identification number of the machine
request_signature	string(500)	M	Refer to section 3(e)(iii)

Field name	Data Type & Max Length	Mandatory / Optional	Description
status	int	M	Status code: 0: Fail 1: Successful
show_status	boolean	M	To return 0 if fail or 1 if success
message	string(500)	M	The displayed message
server_time	datetime	M	The time of the response

Digital Signature

Request Signature
Field name	Description
api_key	The code to authenticate the user or calling program to an API
last_request_unique_number	Unique identification number for request to be used in upcoming transaction from API 1
transaction_qrcode	The QR code value
branch_code	The identification number of the outlet
pos_name	The identification number of the machine

Remove Voucher API

Sample Request:

{
    "transaction_qrcode": "QR-20191219-FF99-0000001",
    "api_key": "fff426a0-3ddf-43f6-93f9-8a63ce29cb76",
    "language_code": "en",
    "branch_code": "B1",
    "pos_name": "20171004124370",
    "invoice_no": "B1",
    "request_signature": "bbe4c18cc50c016dc206bdb1e4f7535fc83d9fc294c6db93046ff7b93ab2507e"
}

Sample Response:

{
    "status": "1",
    "show_status": "1",
    "message": "successful",
    "server_time": "2019-12-19 13:56:34",
    "data": {

    }
}

This API allows the removal of voucher applied.

API Name: remove_voucher_from_pos

Fields

Field name	Data Type & Max Length	Mandatory / Optional	Description
transaction_qrcode	string(50)	M	The QR code value
api_key	string(50)	M	The code to authenticate the user or calling program to an API
language_code	string(2)	M	The language code, set to en for English by default
branch_code	string(50)	M	The identification number of the outlet
pos_name	string(50)	M	The identification number of the machine
invoice_no	string(50)	M	InvoiceNoGeneared
voucher_no	string(50)	M	VoucherNo of the voucher
request_signature	string(500)	M	Refer to section 3(f)(iii)

Field name	Data Type & Max Length	Mandatory / Optional	Description
status	int	M	Status code: 0: Fail 1: Successful
show_status	boolean	M	To return 0 if fail or 1 if success
message	string(500)	M	The displayed message
server_time	datetime	M	The time of the response

Digital Signature

Request Signature
Field name	Description
api_key	The code to authenticate the user or calling program to an API
transaction_qrcode	The QR code value
branch_code	The identification number of the outlet
pos_name	The identification number of the machine
invoice_no	The identification number of invoice
voucher_no	The identification number of voucher

Refund API(Add on V1.2)

Sample Request:

{
    "api_key": "a5552c47-85e4-4044-a67f-9f3e4a4e5522",
    "refund_request_no": "20200512-58A9-0000002",
    "branch_code": "OCK_CSM",
    "language_code": "zh",
    "pos_name": "20171004124370",
    "request_signature": "be23d1754c4654286e6505ca24ee4541df4ac4d5e1663f70763cf1e0294248ed",
}

Sample Response:

{
    "status": "1",
    "show_status": "1",
    "message": "Refund sucessfull",
    "server_time": "2020-05-12 13:49:39",
    "data": {

    }
}

This API allows the reversal of a completed transaction.

API Name: refund

Fields

Field name	Data Type & Max Length	Mandatory / Optional	Description
api_key	string(50)	M	The code to authenticate the user or calling program to an API
refund_request_no	string(50)	M	The refund request ID provided in API3 upon successful payment
language_code	string(2)	M	The language code, set to en for English by default
branch_code	string(50)	M	The identification number of the outlet
pos_name	string(50)	M	The identification number of the machine
request_signature	string(500)	M	Refer to section 3(g) (iii)

Field name	Data Type & Max Length	Mandatory / Optional	Description
status	int	M	Status code: 0: Fail 1: Successful
show_status	boolean	M	To return 0 if fail or 1 if success
message	string(500)	M	The displayed message
server_time	datetime	M	The time of the response
status	string(150)	M	The response for the requested action
status_code	string(5)	M	The response code for the requested action

Digital Signature

Request Signature
Field name	Description
api_key	The code to authenticate the user or calling program to an API
refund_request_no	The refund request ID provided in API3 upon successful payment
branch_code	The identification number of the outlet
pos_name	The identification number of the machine

Complete Transaction (Add on V1.3)

Sample Request:

{
    "api_key": "a5552c47-85e4-4044-a67f-9f3e4a4e5522",
    "refund_request_no": "20200512-58A9-0000002",
    "branch_code": "OCK_CSM",
    "language_code": "zh",
    "pos_name": "20171004124370",
    "request_signature": "be23d1754c4654286e6505ca24ee4541df4ac4d5e1663f70763cf1e0294248ed",
}

Sample Response:

{
    "status": "1",
    "show_status": "1",
    "message": "Refund sucessfull",
    "server_time": "2020-05-12 13:49:39",
    "data": {

    }
}

This API allows to tell AppsPOS that the transaction is completed once we got successful payment ie (status 1 in payment status API)

API Name: payment_completed

Fields

Field name	Data Type & Max Length	Mandatory / Optional	Description
api_key	string(50)	M	The code to authenticate the user or calling program to an API
transaction_qrcode	string(50)	M	The QR code value
refund_id	string(50)		The Refund ID in Payment Status API
transaction_id	string(250)	M	The Transcation ID in the Payment Status API
language_code	string(2)	M	The language code, set to en for English by default
branch_code	string(50)	M	The identification number of the outlet
pos_name	string(50)	M	The identification number of the machine
request_signature	string(500)	M	Refer to section 3(h)(iii)

Field name	Data Type & Max Length	Mandatory / Optional	Description
status	int	M	Status code: 0: Fail 1: Successful
show_status	boolean	M	To return 0 if fail or 1 if success
message	string(500)	M	The displayed message
server_time	datetime	M	The time of the response

Digital Signature

Request Signature
Field name	Description
api_key	The code to authenticate the user or calling program to an API
transaction_qrcode	The Qr Code
refund_id	The Refund ID from Payment Status API
transaction_id	The transcation ID from Payment Status API
branch_code	The identification number of the outlet
pos_name	The identification number of the machine