Online Payments Integration for Mobile Apps

In today’s article we bring you a guide on how to integrate Twispay Payment Gateway with your mobile application, using a Webview component.

As we’ve come to know, mobile is the fastest growing platform of the modern era, and, with it becoming more and more integrated into people’s daily lives, eCommerce is rapidly adapting.

Nowadays, you can research, browse and purchase almost any kind of product at your own leisure, straight from your mobile device. As online markets become more trustworthy, users are feeling more comfortable than ever purchasing goods online. And when we’re talking about online shopping, one of the core components of eCommerce, as well as the nature of all commerce, is the Checkout and Payment process. Twispay offers a versatile solution for your Payment processing, available on multiple platforms and covering a wide range of merchant needs. Therefore, today we’ll show you how to integrate it with a mobile app.

The Pre-requisites You’ll Need

Here is what you will need before you can start your integration:

1. A native mobile app 

2. A Twispay Test Account from where you get your Secret key and Site ID, which you’ll need later (https://merchant-stage.twispay.com/auth/signup)

3. A back-end application (module) that stores all data regarding Orders, Customers, Transactions, Cards. Basically, your business.

This should also include:

• A Page or API Endpoint that can Render/ Calculate the JSON Request, Checksum and the URL.

• A Page/ Script (URL) that knows to update the statuses of the current transaction/ order and display a Thank You/ Error Message.

• IPN Listener (Webhook)

How It Works

The customer adds some products from a merchat’s app into the virtual cart. He then proceeds to place his order by clicking a Checkout/ Purchase button.

When the Purchase button is hit, the merchant’s app sends a request to the merchant’s server to create an internal order entry with the appropriate information in their own system (order number, customer information, cart details, order amount, etc.).

Note: Orders, Customers, Transactions and Cards should have IDs associated with them. Any unique string less than 32 characters long can be used as ID. Auto-incrementing numbers are a great fit.

Depending on how complicated your business is, you will have different statuses to reflect the state of your orders. For this guide we will use a simple flow with only three statuses.

The initial status of an Internal Transaction entry, when created, will be Payment Pending. (Mark 1 in the Transaction Status Diagram).

When the merchant’s server creates the internal transaction entry, it also generates two parameters required for the Transaction with Twispay:  The JSON and the Checksum.

The jsonOrderData variable contains all the transaction parameters required by Twispay and it should look something like this:

{
  "siteId": 1,
  "customer": {
    "identifier": "1",
    "firstName": "John ",
    "lastName": "Doe",
    "country": "RO",
    "city": "Bucharest",
    "phone": "0012120000000",
    "email": "john.doe@test.com"
  },
  "order": {
     "orderId": "ID",
     "description" : "Description",
     "type": "purchase",
     "amount": 2194.98,
     "currency": "RON",
    "description": "order description",
   },
  "cardTransactionMode": "authAndCapture",
  "backUrl": "http://example.com"
} 

A checksum is an alphanumeric sequence that verifies the integrity of the JSON. Twispay uses a checksum algorithm to protect against malicious users that might change the contents of the JSON (for example, lowering the amount).

Here is an example written in Java on how to use these SDKs:

// get the HTML form
String base64JsonRequest = Twispay.getBase64JsonRequest(jsonOrderData);
String base64Checksum = Twispay.getBase64Checksum(jsonOrderData, secretKey.getBytes(StandardCharsets.UTF_8));
String hostName = twispayLive ? "secure.twispay.com" : "secure-stage.twispay.com";
 

You can find more details on our GitHub account (github.com/twispay), where you can also find the SDKs alongside examples on how to use them.

There are, of course, other payment-related operations that an online business needs, such as refunds. Twispay supports such operations, but, for simplicity, we will not cover them in this guide. Instead, you can find them documented at docs.twispay.com. Next the merchant’s server sends the two parameters + the secure URL back to the merchant’s app, which uses a WebView to render a hidden html form.

$htmlForm = <<<FORM
<form name="form1" action="https://secure-stage.twispay.com" method="post" accept-charset="UTF-8"> 
<input type="hidden" name="jsonRequest" value="{$base64JsonRequest}">
<input type="hidden" name="checksum" value="{$base64Checksum}"> 
<input type="submit" value="Pay"> 
</form> 
FORM;
 

This form inside the WebView can be auto-submitted using Javascript, so the customer does not need to take any action.

<body onload="document.form1.submit()"> 

Twispay checks the parameters and then displays the payment form.

The customer inserts their credit card information and submits the form.

Then Twispay ends the process and redirects the Webview to a URL provided by the merchant with an encrypted POST Parameter named opensslResult. (Mark 2 in the Transaction Status Diagram)

The merchant’s backend should decrypt this message to obtain the status of the payment and other relevant information.

Note: The Back URL needs to be on the Merchant’s Server publicly so it can load inside the Webview.

The merchant’s server finalizes the order by updating the status of the transaction in their internal system depending on the status received from Twispay and then displays a result page to the Customer (Either Thank You for Your Purchase or Error Page). (Mark 3 in the Transaction Status Diagram)

At this point the merchant’s app can close the Webview. Also the merchant’s server must save the provided Customer ID, Card ID and Transaction ID & Status, creating a double linkage. Twispay knows about the merchant’s Customer ID and Order ID while the merchant knows about the Twispay’s Customer ID and Transaction ID, both parties being aware of each other’s data. This allows both to reconcile the data in case of any out of sync issues.

What if a Returning Customer Wants to Buy Again?

Twispay offers a simple server-to-server solution for clients that have already made a payment and chose to save their card details for further purchases by simply choosing their card from a list. This is what the payment industry refers to as One Click Payments.

The merchant’s server sends a POST Order request to the Twispay’s API with a matching Card ID and Customer ID combination.

You can find more details & documentation about this feature on docs.twispay.com.

Final Thoughts

That’s it. This is how you integrate Twispay’s Payment Gateway with your mobile app.

You can now access whole new world of commerce and can place your products and services at your customer’s fingertips.

We hope this was an informative read and we’d love to hear your thoughts at marketing@twispay.com or, if you need technical assistance with your solution, give us an e-mail at support@twispay.com. We’ll be glad to help you!