POS Integration and how to use

This is the document that will explain to us, how we can integrate POS machine integration into our product app.

Architecture

Product App - Web app will contain all the modules, like Property Tax, Trade license, etc, It's a responsive web app.

Technologies

Repository

https://github.com/egovernments/frontend/tree/master/web/rainmaker

IDE

Atom, Visual code

2. Android Wrapper - It's an Android native app it's having Webview to show the product app. Here we have created a javascript bridge to communicate with the Product App.

Technologies

Java
Javascript

Repository

https://github.com/egovernments/frontend/tree/master/web/rainmaker-webview

IDE

Android Studio

3. Custom App - It's an Android native app, It receives a signal from the Android Wrapper app about payment information it will talk with POS machine vendor APIs to make the payment.

Technologies

Java/React Native

Repository

It will state implementation repository

IDE

Android Studio

Steps

We need to install POS enabled APK and Custom App APK to the POS machine.
Click on the Pay button in any module(TL, Property Tax, etc).
It will come to the common pay screen. Because of the POS enabled APK, the javascript bridge set the isPosMachine true, So that we can see collect Button in the POS machine.

4. Clicking on the collect button, it will send the payment information to the Android app, Android app receive the data and it will open the new Intent and its open Custom app that is created specifically to the state machine. The custom app receives all the information required for the POS machine payment gateway.

Contract of the YAML sent by product app to custom APP

title: POSCollectRequest
type: object
x-examples: {}
properties:
  instrumentType:
    type: string
    description: 'Mode of payment. If CHOOSE is selected, then the POS App needs to choose which method of payment is select. Only support methods are CASH, CHEQUE, DD, CARD'
    enum:
      - CASH
      - DD
      - CHEQUE
      - CARD
  paymentAmount:
    type: integer
    format: int32
    minimum: 1
    description: |
      The paymentAmount to be collected
  customerName:
    type: string
    description: The name of the customer. This is a optional property
  customerMobile:
    type: string
    description: Customer Mobile number. This is a optional property
  message:
    type: string
    description: Required message to be shown on the POS app
  emailId:
    type: string
    description: Email address. Optional property
  amountDetails:
    type: array
    description: Bifercation of amounts
    items:
      type: object
      properties:
        type:
          type: string
        amount:
          type: number
      required:
        - type
        - amount
  billNumber:
    type: string
  consumerCode:
    type: string
  businessService:
    type: string
  collectorName:
    type: string
  collectorId:
    type: string
  instrumentDate:
    type: number
  instrumentNumber:
    type: string
required:
  - instrumentType
  - paymentAmount
  - message
  - billNumber
  - consumerCode

3. Select the payment mode and click on Pay.

4. Now the custom app will open the POS machine vendor payment screen on intent, verify the payment, and click on pay.

5. Once we collect the payment, the Acknowledge screen will appear, click next.

6. Clicking on the Next button, the Custom app will return below information to Android App,

Contract of the Custom app should send back to product app

title: POSCollectResponse
type: object
properties:
  amountPaid:
    type: number
    minimum: 1
  transactionId:
    type: string
  transactionStatus:
    type: string
    enum:
      - CANCELLED
      - COMPLETE
      - FAILED
required:
  - amountPaid
  - transactionId

After receiving the above information Android app sends this information to the web app using JS bridge,

7. The web app will process the information sent by the Android app, it will take 2 or 3 seconds to process then it will go to acknowledge screen. Click on mini receipt it will send receipt information to Bluetooth app(This app might be given or created by state team)

Note: - We need to inject the JS file to show the Mini receipt button. Please find the example file added in Punjab.

https://s3.ap-south-1.amazonaws.com/pb-egov-assets/ulb-overrides-uat-20191226.js

8. Bluetooth app shows the information, verify the information click on Print Reciept.

9. Clicking on Print receipt it will print the receipt in the POS machine.

How to generate APK(DEV) for the POS machine.

Switch to POS specific branch.
Go to the below location project from the android studio.

https://github.com/egovernments/frontend/tree/master/web/rainmaker-webview

3. It will take some time to set up the project, once the project setup is done, click on the menu Build,

select the Build Bundle(s) / APK(s) sub-menu, and click on Build APK(s).

4. It will take some seconds to generate the APK and it will show the location where the APK generated. Take the APK and install it into the POS machine.