API‎ > ‎

Merchant API

WoraPay Merchant API is used by merchant's Point of Sale (POS) system. It enables merchants to allow their clients to see and pay for goods and services via any mobile walltet that is integrated to WoraPay system.

Scenarios

Note: specific scenario and its implemetation for merchants mobile (including apps) and online shops can be found here.

As a mobile wallet user
I want to pay with my mobile wallet in retail
So that I could pay in most convenient and fast way

Creating and Updating the Bill

As a mobile wallet user
I want to get my bill to my mobile wallet
So that I could review it with it's current content


Paying the Bill

As a mobile wallet user
I want to pay with my mobile wallet in retail
So that I could pay in most convenient and fast way

Paying the Bill with money reservation

As a mobile wallet user
I want to confirm money reservation with my mobile wallet
So that I could be charged the exact amount after I use the service

Diagram TO BE ADDED

Resources

  1. POS gets information every second about checked in clients and/or active (not paid or canceled) bills by calling GetMerchantInfo() (this polling should be running in POS system all the time or initiated on PosChekInCallBack())
    1. After client checkins to the table, waiter must get information message: "Client GOT the bill of the table {0} to his mobile phone". Message should appear after waiter swipes his authorization card. Messages are sent only to the waiters of the specific table. If there are more than one bill created on the table, only one message should be shown (first one). Message should be configurable in configuration files (for easier change/translation). There should be an option in settings to turn off this message (it is not needed in locations where mobile payments take big part of the transactions).
    2. If there is client and/or loyalty objects defined in POS object response, best matching loyalty should be applied to the customer. System should always track if there are changes to customer/loyalty. If so, new loyalty should be applied or old one removed.
  2. POS creates bill to pay for POS where user is checked in: CreateBill(). From this moment, POS must monitor created bill until it is closed (POS cannot leave this bill open even if it restarts, crashes etc.).
    1. If money reservation is required, set parameter reservation_required=true.
  3. POS gets information about specific bill: GetBill().
  4. POS updates bill information: UpdateBill().
  5. When user wants to start paying the bill (or reserving money), POS must check if bill is not being edited (e.g. by the waiter), lock it in POS from any further editing and allow to lock it: AllowToLockBill(). Only when POS allows to lock the bill, client will start transaction. 
    1. In the POS UI waiter must get payment confirmation message: "Client PAID the bill of the table {0} with his mobile phone". Message should appear after waiter swipes his authorization card. Messages are sent only to the waiters of the specific table. Message should be shown for each paid bill. Message should be configurable in configuration files (for easier change/translation). 
    2. Waiter presses OK button in this message which closes the table and prints fiscal receipt. The means of payment should be written "Mobile phone" on the fiscal receipt.
    3. Money should be added to specific credit "Mobile phone" in the accounting part of the POS. Waiter/manager/accountant should be able to get report by this credit.
  6. If bill was paid by other means (cash, credit card etc.), POS must mark that it was paid: MarkBillAsPaidInPOS().
  7. If bill was canceled in POS for any reason, POS must cancel it: CancelBill().
  8. If bill was created with parameter reservation_required=true. POS must execute following actions:
    1. Optional (can be executed many times): POS reserves extra money where parameter amount must be greater than in created bill: IncreaseBillReservation().
    2. Mandatory (once): POS completes reservation with final amount where parameter amount must be equal or less than in created bill: CompleteBillReservation().
  9. All log items logged on the POS must be sent to WoraPay so it could actively monitor and act proactively if anything unexpected happens on POS. POST must ensure that this does not slow down the actual activity of the service: SendLogs().
  10. For mapping QR codes generated in WoraPay system and tables or cash-registers configured in POS system AssignCode() must be called.

Security, authentication and responses

Detailed documentation and examples: https://sites.google.com/site/worapay/api.
Note: If POS configuration is done using config files and user interface is not implemented for mobile payment configuration, POS does not need to call getAccess() method. Access Key and Access Secret will be provided on merchant request and won't timeout.

Setup of merchant profile

Getting tokens

Merchant that would decide to accept mobile payments should sign contract with WoraPay and will receive credentials. These credential may be used for getting tokens: Access Key, and Access Secret. 
Bellow is a sample screen in a POS system:

  • This screen should be accessible only by manager or technical administrator
  • First time this screen is opened all fields would be empty
  • After user enters credentials and clicks "get tokens" a WoraPay API method getAccess()  is called
    • Result is stored in POS for later use while making calls to WoraPay API
    • User name and password fields are cleared
  • Next time screen is opened consumer and access fields are filled with data previously received in getAccess() response
  • If user enters credentials and clicks "get tokens" a WoraPay API method getAccess() is called
    • Result overrides previously stored tokens  
    • User name and password fields are cleared

Assignment of QR codes (predefined tables)

Merchant generates QR codes that are unique for each table and cash desk. For POS system to communicate with WoraPay API those QR codes must be mapped with cash desk and table setup inside POS system. 
Bellow is a sample screen in a POS system:
  • This screen should be accessible only by manager or technical administrator
  • All description fields are set with values from cash desk and table setup in POS
    • User is allowed to change description of the table or cash desk. What is entered in this field will be displayed in m-wallets.
  • After user enters QR code and clicks "Assign" a WoraPay API method AssignCode() must be called
    • On successful response this code must be stored and used for later communication with WoraPay API

Assignment of QR codes (dynamic tables)

Merchant generates QR codes that are unique for each table and cash desk. For POS system to communicate with WoraPay API those QR codes must be mapped with cash desk setup and dynamically created tables inside POS system. 
Bellow is a sample screen in a POS system:
  • This screen should be accessible only by manager or technical administrator
  • All description fields are set with values from cash desk setup in POS
    • User is allowed to change description of the cash desk. What is entered in this field will be displayed in m-wallets.
  • User must enter code that is used during bill creation. This will be used for mapping created bills with QR codes.
  • User must enter description for dynamic table codes. What is entered in this field will be displayed in m-wallets.
  • After user enters QR code and clicks "Assign" a WoraPay API method AssignCode() must be called
    • On successful response this code must be stored and used for later communication with WoraPay API


Papildomi puslapiai (3): Merchant Service mShop API Test App
Comments