1.13.2 Payment flow

The onlineshop supports two models of integrations with payment providers:

• Through a provider’s API
• Through redirection to provider’s website

The payment can be initiated from VUP, VUC, mobile clients or through the onlineshop API. The user interface will depend on the model.

The diagram below shows the flow for the model with provider’s API.  The UI has to contain all the necessary fields required to make a transaction with a credit card or other payment method supported by the provider. The data are then sent from the onlineshop application to the provider’s API which processes the transaction and returns the result to the onlineshop. The result is presented by either success.aspx or cancel.aspx pages.

The communication between the onlineshop and the API is implementation specific. It can be done by connecting to provider’s web services or through an external library (SDK) delivered by provider.

In the second model, the UI of the portal has to contain only a basic form with selection of the top up amount. Once the form is submitted the onlineshop redirects the client’s browser to the payment provider’s website, passing the selected amount and login as parameters using POST method. The exact parameters which are sent to the provider depends on specific implementation.   On the provider’s website the client has to enter the required details into the payment web form. When transaction is completed its result is shown to the client and then the client’s browser is redirected to the onlineshop’s callback URL.

The callback URL is passed either as a parameter in the POST request or is defined in the provider’s backoffice.

Some providers, besides redirecting client’s browser, use server to server communication to pass the transaction’s results to onlineshop, i.e. the provider sends a direct request to the callback URL.  This is to ensure that the result is delivered to the seller’s platform. If a provider relies only on redirections it may happen that the result will not reach the onlineshop – for example when client closed the browser before the request has been sent.

Some providers can work in both models. Which model, for a given provider, is supported by onlineshop is indicated in the list of supported providers in the next section.

Web response

As shown on the diagrams, the transactions always end on either of the two pages:

• success.aspx
• cancel. aspx

The source files of these pages are in the onlineshop folder. The pages HTML look can be modified directly by changing the HTML code in the files. However, the message displayed there is generated dynamically. By default it simply reads the result and in case of error its code.

If you want to change the message text go to VSM Settings/Online payments/Web response menu. In the body field you can enter the text and use available variables (shown after clicking on the menu button next to the field). The body can be different for any of the combinations of client type, transaction type and transaction status.

Redirection

Instead of showing the default result pages you can redirect a client to another URL, for example to VUP or any other web application. To do so you will need to add an entry in the Redirect.config file. The onlineshop will redirect the client to the provided URL with a parameter key which is an encrypted transaction ID. The parameter is sent in GET method. To decode the key parameter send a request to the response.aspx page using GET method. In response you will receive the details as defined in the Web response menu (described in the earlier section). 

Example Redirect.config file:

The above entries define the redirect actions on two transaction statuses:

• Status: success
• Status: cancel   - when the transaction failed

In both case the redirect URL is the same and points to the VUP/ACTION/TransactionSummary which opens a panel with the transaction summary within VUP.

The from tag allows to define the request’s URL for which the redirect action will be performed. In this example it is * which is a wildcard character triggering the action for all requests.

The from can be limited to a particular URL, for example:

• the address of a web page -
  http://mydomain.com/OnlineShop/index.html

• the address of an application -
  http://mydomain.com/OnlineShop/

• the whole domain -
  http://mydomain.com/

The actions can be limited also to a specific platforms by using the deviceType attribute. If you want to limit the action only to windows users then add the deviceType attribute:

In addition, you can set a different redirection depending on the payment provider used for transaction. For example:

The above actions will be triggered only when the recharge has been processed by WorldPay provider.

The examples above show how you can create multiple entries with exceptions for various combinations

 of the redirect attributes and the from tag. The attributes include:

• status
• operation type (create type is deprecated as it is handled by the EMCD API now)
• deviceType – supported types:
  iPhone, Android, BlackBerry, Symbian, WindowsPhone, WindowsMobile, iPad,  Windows, Linux, Mac
• provider

When redirection URL is set to VUP you do not have to decode the key as it is done internally by VUP. The transaction summary page is shown as a popup window within the VUP and hence it requires that a client is already logged in.

If you want to open the transaction summary page without the client having to log in you should us the URL without /ACTION  i.e.:

The text shown in the popup can be changed in the resx file in the VUP’s resources folder.

inApp

Onlineshop supports inApp payments realized by Google Play and Apple Store. InApp payments are implemented in voipswitch’s RCS softphones.

 In the inApp model a client purchases a product, in this case a top up or subscription (plan), from the mobile application. The transaction is realized by the appropriate application store and when completed successfully the result is passed to the onlineshop. Subsequently the onlineshop connects to the app store’s API and verifies the result. If the transaction is confimed the client account is credited.

The products have to be defined in the app stores. In the onlineshop configure the top up amounts that match the prices of the products. Only these products will be shown in the softphones.

The onlineshop URL used for inApp payments is:

https://domain/store.ashx

Below is a diagram presenting the detailed flow:

1. Client clicks Top up button.
2. The softphone requests the list of available top ups.
3. The onlineshop returns the amounts
4. The softphones compares the products from the app store with the received amounts and displays only those which can be paired.
5. Client selects a product
6. (for android only) the softphone notifies the onlineshop about the selected product before client proceeds to the app store
7. (for android only) server returns a unique ID used to recognize the transaction. The ID must be sent to the onlineshop in point 9. The Google Play will use that ID as “nonce”
8. The softphone proceeds with the product purchase through the app store.
9. The softphone sends the result of transaction received from the app store to the onlineshop
10. For AppStore the onlineshop verifies the transaction result with the AppStore API and if confirmed top-ups the client account
11. For Google Play the onlineshop verifies the details received from the softphone using the certificate and top-ups account.
12. The onlineshop returns the final result to the softphone

The following section has to be added in the Payments.config file:

Subscriptions