API‎ > ‎

mWallet API

WoraPay mWallet API should be used by bank (or any Payment Service Provider - PSP) mobile application (mobile wallet). It enables Bank clients to pay for goods and services at merchants that are integrated to WoraPay mobile payment system.

User Story

As a bank client
I want to pay with my bank's mobile wallet (mWallet, bank's app) anywhere in retail
So that I could pay remotely: convenient, fast, and secure.

User experience (UX flow)

 State  Description  UI example
 Home When user starts the mWalletmWallet needs to authenticate with WoraPay API: getPublicAccess(). If ever any method returns HTTP 401 Oauth Challenge error, mWallet should automatically call getPublicAccess() to get new access tokens and use new ones.

Then mWallet must get current information/status of the user: getInfo() and display accordingly (this method should always run in the background to check any changes):
  • No checkin to POS or open bills: show "Scan the code" and "Select location" buttons. 
    • If user clicks on it button "Scan the code", go to Code Scanner.
    • If user clicks on it button "Select location", go to Location selection.
  • Chekcin to POS exists, no bills: automatically show Waiting For Bill (POS info and waiting for bill)
  • Chekcin to POS exists, many bills: automatically show Bills List (POS info and bills list)
  • Chekcin to POS exists, one bill: automatically show Bill (POS info and bill info)
If this is first time user, he must agree with terms (if any) and provide his phone number (and confirm it to make sure he is using his phone number).

 
 Code Scanner  When user scans the code mWallet asks info about it: getCode().
  • if POS object is returned, checkInToPos() is performed automatically. If checkin is successful get current user information getInfo() and display accordingly:
    • Chekcin to POS exists, no bills: 
      • If POS.bill_mode equals to "menu" automatically show Menu
      • If POS.bill_mode equals to "auto" automatically show Bill (POS info and waiting for bill)
    • Chekcin to POS exists, one bill or one order: automatically show Bill (POS info and bill/order info)
    • Chekcin to POS exists, many bills: automatically show Bills List (POS info and bills list)
  • if code cannot be read or code info is not returned (code is not recognized in WoraPay system), show error/advice for the user.
  • user can exit: go to Home
 
 Location selection  When user selects this option mWallet request for all locations near the user: getLocationsForRemoteCheckin()
 A list of returned POS'es is displayed for users selection.
  • After user selects one of the  POS'es checkInToPos() is performed automatically. If checkin is successful get current user  information getInfo() and display accordingly:
    • Chekcin to POS exists, no bills: 
      • If POS.bill_mode equals to "menu" automatically show Menu
      • If POS.bill_mode equals to "auto" automatically show Bill (POS info and waiting for bill)
    • Chekcin to POS exists, one bill or one order: automatically show Bill (POS info and bill/order info)
    • Chekcin to POS exists, many bills: automatically show Bills List (POS info and bills list)
  • user can change radius for filtering POS'es
  • user can change category for filtering POS'es
  • user can exit: go to Home
 
 Waiting For Bill  User is checked in and waits for the bill. mWallet should show:
  • Payee (merchant/pos):
    • logo
    • name
    • description
    • address (address + city)
  • "Waiting for bill" text
 User can:
  • exit: checkOutOfPos() and check getInfo() which state to go to.
 
 Bills List  User is checked in and has few bills. mWallet should show:
  • Payee (merchant/pos): same as in Waiting For Bill
  • Bills List
    • bill description
    • bill amount
    • bill currency
    • option to choose the bill
User can:
  • choose bill: go to Bill
  • exit: checkOutOfPos() and check getInfo() which state to go to.
 
 Menu  User is checked in into POS with bill_mode equal to "menu" and does not have any bills. mWallet should get menu bay calling getProductMenu() and show:
  • Payee (merchant/pos): same as in Waiting For Bill
  •  Menu items list:
    • Categories
      • category description
      • option to open the category
    • Products
      • product description
      • product amount
      • product currency
      • option to open product
User can:
  • make an order: mWallet calls createOrder() and if bill object was returned opens Bill
  • go back: go to previous category in Menu or checkOutOfPos() (if this is already root category)
 
    
 Product  User has selected to open one of the products.mWallet should show:
  • Payee (merchant/pos): same as in Waiting For Bill
  • Products
    • product description
    • product amount
    • product currency
    • product modifiers
User can:
  • add product to the basket
  • select modifiers
  • select number of products to add to the cart
  • go back: go to the last location in Menu
 
 Bill  User is checked in and has few bills. mWallet should show:
  • Payee (merchant/pos): same as in Waiting For Bill
  • Bill
    • bill amount
    • bill currency
    • bill content (if there is no content bill description should be displayed here)
User can:
  • pay bill: go to Payment
  • go back: 
    • if order details are displayed and POS bill_mode is equal to "menu" mWallet cancels order using cancelOrder() api method and goes back to Menu
    • else go to Bills List
 
 Payment  User confirms payment with security mechanisms implemented by the bank mWallet.

 When user presses final pay button mWallet asks asks permission to start the payment (to lock the bill): askToLockBill(), reads getBill() response and shows statuses to the user:
  • when bill status changes to lockedmWallet informs to start transaction. this can take from a second to few minutes, e.g. if waiter is updating the bill at the time
  • when bill status changes to paidmWallet shows successful payment information.
    • confirmation_message from bill object should be shown to the user that is returned from API ("Thank you for buying" text in the example img on the right)
    • clicking OK should go to:
      • confirmation_url if it is stet in bill object
      • otherwise, where bank decides (home, payments history, etc.)
  • if bill status changes to other than locked or paid state, mWallet redirects user to corresponding state (e.g. if waiter was updating the bill, it will change to assigned state. mWallet must show the bill to the user as it might have different amount and data now).
 
  

Note: UI examples are intended to show one possible user experience flow. They can and should be improved according to bank needs, UX guidelines and best user experience.
Note: we advice to allow to use most functionality (get and see bill) for not authorized (logged in) users. Only when user wants to pay full authorization should be requested.

Sequence diagrams

Checkin and Get the Bill


Pay the Bill


Pay the Bill with Money Reservation




Resources

Note: Bank Server methods are accessible only from white listed IP's (bank server IP)
  1. When user starts mWallet, mWallet needs to authenticate with WoraPay API: getPublicAccess()
    1. If ever any method returns HTTP 401 Oauth Challenge error, app should automatically call getPublicAccess() to get new access tokens and use new ones.
  2. Every second mWallet must check current information/status of the user (POS Object and Bill Objects List): getInfo()This method should always run in the background to check any changes.
  3. When user scans the code mWallet asks info about it: getCode().
    1. If POS object is returned, checkInToPOS() is performed automatically. 
    2. If user decides to cancel chekckin: checkOutOfPOS().
  4. When user opens select location mWallet gets a list of near by locations:  getLocationsForRemoteCheckin()
    1. If user selects one of locations checkInToPOS() is performed automatically. 
    2. If user decides to go back and select other location, before showing list of locations previous chekckin should be canceled: checkOutOfPOS().
  5. If user is checked into POS that has bill_mode equal to "menu" mWallet calls getProductMenu() and displays menu
    1. User can navigate in menu and create product basket. After user confirms his basket order is created in server: createOrder()
    2. If user changes his mind and wants to get back to menu order is canceled in server: cancelOrder()
  6. When user presses final pay button mWallet asks permission to start the payment (to lock the bill): askToLockBill().
  7. GetBill() returns bill object to check it's data (and status).
  8. After successful payment Bank Server calls MarkBillAsPaid(). (If Bill Object has parameter reservation_required=false)
  9. If payment or reservation fails Bank Server calls MarkBillPaymentAsFailed(). Payment or reservation confirmation or failure MUST be called to unlock the bill.
  10. If Bill Object has parameter reservation_required=true then reservation is made and Bank Server calls MarkBillAsReserved().
    1. If reservation needs to be increased, increase_reservation_url callback from MarkBillAsReserved() will be executed. Bank should increase the reservation to amount provided, which will be greater than initial or increased reservation
    2. If reservation needs to be completed, complete_reservation_url callback from MarkBillAsReserved() will be executed. Bank should finalize the payment with the amount provided, which will be equal or smaller than reserved.
    3. If reservation needs to be canceled, cancel_reservation_url callback from MarkBillAsReserved() will be executed. Bank should cancel the reservation and no money should be charged.
  11. If Bill Object has parameter subscription_id set
    1. If subscription_id=init, then after successful payment or reservation confirmation, user subscription should be signed and subscription_id should be returned in MarkBillAsPaid() or MarkBillAsReserved() respectfully.
    2. If subscription_id=<available_subscription_id> then MakePayment() or MakeReservation() methods will be called to start the payment or reservation automatically (without user confirmation). Further process is exactly the same as in standard payment or reservation


Methods needed on Bank side

These methods should use HTTP Basic authentication. User name and password should be provided for WoraPay and will be used to sign each request.

For Subscription-based payments

MakePayment method

This method needs to be implemented on bank server side to allow subscription-based payments.

Resource: https://api.bankserver.com/payments/
Http method: POST

Request parameters:
 Name  Type  Description
 subscription_id  string  Subscription identifier
 payer  string  mWallet owner phone number
 amount
 decimal  Total amount to charge
 currency   string  Payment currency
 description  string  Payment description
 payee  string  Beneficiary (merchant) name
 reason_id (optional)  string  Reason identifier (e.g. id for the bill if reason object is bill)
 reason_object (optional)  string  Reason resource object type (e.g. bill)

Request example:
subscription_id=s_456413&payer=+37065699999&amount=12.21&currency=usd&description="some text"&reason_id=bl_398475698376&reason_object=bill

Response:
HTTP/1.1 200 OK

Errors:
HTTP/1.1 400

MakeReservation method

This method needs to be implemented on bank server side to allow subscription-based reservations.

Resource: https://api.bankserver.com/reservations/
Http method: POST

Request parameters:
 Name  Type  Description
 subscription_id  string  Subscription identifier
 payer  string  mWallet owner phone number
 amount
 decimal  Total amount to reserve
 currency   string  Reservation currency
 description  string  Reservation description
 payee  string  Beneficiary (merchant) name
 reason_id (optional)  string  Reason identifier (e.g. id for the bill if reason object is bill)
 reason_object (optional)  string  Reason resource object type (e.g. bill)

Request example:
subscription_id=s_456413&payer=+37065699999&amount=12.21&currency=usd&description="some text"&reason_id=bl_398475698376&reason_object=bill

Response:
HTTP/1.1 200 OK

Errors:
HTTP/1.1 400

CancelSubscription method

This method needs to be implemented on bank server side to cancel (disable) active subscription.

Resource: https://api.bankserver.com/subscriptions/
Http method: PUT

Request parameters:
 Name  Type  Description
 subscription_id  string  Subscription identifier
 payer  string  mWallet owner phone number

Request example:
subscription_id=s_456413&payer=+37065699999

Response:
HTTP/1.1 200 OK

Errors:
HTTP/1.1 400

For end-user communication

SendMessage method

This method needs to be implemented on bank server side to provide possibility for merchant to communicate with end user. Message delivering to end user in PSP server side should be done asynchronously, this means received request should be registered and response to WoraPay sent synchronously and message sending would be done asynchronously in other thread. 

Resource: https://api.bankserver.com/messages/
Http method: POST

Request parameters:
 Name  Type  Description
 user  string  Phone number of user that this message had to be delivered to
 type  string  A classifier of possible message types
 sub_type
 string  A classifier of possible message sub-types
 message_id  string  Unique message identifier that will be used to get message status
 meta_data  JSON  Metadata is a JSON object that is passed together with message and contains specific parameters for each type of message
 title  string  Title of the message that can be showed to end user if technology used for message delivery allows that (please note that it can be empty)
 message  string  Message from merchant to end user that must be delivered to end user

Message type classifier:
  • order_status_change - this message type is used to inform end user about his order status changes
    • Sub-types:
      • accepted - can be sent after order was successfully paid and it was delivered to the merchant 
      • started - can be sent when merchant started processing this order
      • completed - can be sent when merchant finished processing this order and it is available for pick-up
      • delivered - can be sent after this order was already picked up
    • Metadata:
      • order_id - this is id of an order in worapay system. If delivery method supports clicking on user message it could open this order in the banks app
  • e_item - this message type is used to send end user some resource
    • Sub-types:
      • ticket - is sent when user paid for tickets
      • other - is sent when user should receive some kind or resource
    • Metadata:
      • url - link to resource that should be available for end user to click and reach. Originally it will also be in the message.
  • marketing - this is message type when merchant wants to communicate some marketing information. This type of messages are not mandatory to deliver. End user should have possibility to disable them.
    • Metadata:
      • pos_code - can be provided if merchant wants user to be automatically checked-in when it click on the message

Request example:
user=+37065699999&type=order_status_change&sub_type=completed&message_id=asd5421asd&title=Your order is ready and waiting to be picked up.&message=Your&meta_data={"order_id":"12345679321"}

Response:
HTTP/1.1 200 OK
Example:

    "status": "in_progress",
    "message": "Message was registered and being delivered"
 
}

Statuses:
  • in_progress - message is still being delivered
Errors:
HTTP/1.1 400
Example:

    "status": "unknown_user",
    "message": "Could not find user by provided phone number"
 
}

Statuses:
  • unsubscribed - user does not allow this kind of messages
  • unknown_user - end user could not be identified by provided phone number or is not a registered user any more

GetMessageStatus method

This method needs to be implemented on bank server side to provide possibility for merchant to validate if message was delivered to end user.
Resource: https://api.bankserver.com/messages/
Http method: GET

Request parameters:
 Name  Type  Description
 message_id  string  ID of the message that was passed to this service.

Request example:
message_id=asd5421asd

Response:
HTTP/1.1 200 OK
Example:

    "status": "delivered",
    "message": "Successfully delivered"
 
}

Statuses:
  • delivered - message was successfully delivered to end user
  • in_progress - message is still being delivered
  • failed - after several tries message delivery was unsuccessful
  • unsubscribed - user does not allow this kind of messages

Errors:
HTTP/1.1 400

Change log

  • 2013-10: version=2 of API introduced:
    • Version = 2 parameter should be used in every call 
    • Response is always standardized object e.g. pos_objector bill_object
    • Errors are returned in standardized and unified format
  • 2013-10 bill can be split at restaurants, many orders can be set on one QR code (pos code)
    • GetInfo method returns multiple bill objects (if there is one bill, it should be opened automatically to save one click for the user. If there is more than one, list should be presented)
  • 2013-10 payment confirmation call from bank server should send paid amount and currency to ensure that correct amount was charged from the client
  • 2014-04 user can pay with mWallet in mShops
    • When mWallet is opening it should check if it does not have already created bills (GetInfo method). If it does, show the bill to the user immediately. 
    • After successful payment, when user clicks on confirmation button (in payment confirmation screen), mWallet should open the mShop which user came from to pay. Confirmation button should call confirmation_url from BillObject
  • 2014-04 user can get specific confirmation message after successfully payment. E.g. "Cashier knows that you have paid. Jump in petrol station for the receipt (of course, if you need it). Have a good drive! :)."
    • getPublicAccess method should provide language parameter to define mWallet language that is used
    • After successful payment, confirmation_message from the BillObject should be displayed for the user in payment confirmation screen.
  • 2014-07 user can enter his company details that will be printed on receipt (works only in Lukoil)
  • 2014-10 money reservation - reserving the money first (before using the service), increasing the reservation, if needed (service continues being used and costs more than initial reservation), and confirming actual payment amount (after the service was provided).
    • user can reserve (approve) amount, but actual amount, smaller or equal to the reserved, will be confirmed after user uses the service (e.g. reserving money for fuel in Petrol Station, filling the tank, confirming actual amount e.g. if there was less fuel filled than money reserved). This must be used if Bill Object has parameter reservation_required=true. See step 7 ir Resources description above.
    • user can reserve (approve) amount, and confirm that actual amount, greater than the reserved one, can be confirmed after user uses the service (e.g. reserving money for initial time for parking and then the reservation will be increased every x min until user stops using the service). This is used if Bill Object has parameter reservation_required=true. See step 7 ir Resources description above.
  • 2014-10 subscription based payment - while paying the first bill user confirms that from now he allows to charge his account at this merchant without his explicit confirmation (opening a mobile wallet).
    • This is used if Bill Object has parameter subscription_id. See step 9 ir Resources description above. Note: subscriptions work with money reservation as well.
  • 2015-09 checking by location
  • 2015-09 product menu and order creation
    • Check-in version=3 introduced. mWallets calling checkin with version=3 must support menu and order creation flow
    • New API methods getProductMenu()createOrder() and  cancelOrder()
    • New screens Menu and Product in UX flow
  • 2016-11 direct mwallet settlement with merchant
    • Optional parameter introduced in MarkBillAsPaid method to notify WoraPay that settlement of the transaction with merchant will be done directly by mWallet
Papildomi puslapiai (1): Test Scenarios