Integrate with a mobile app
How to integrate with a mobile application.
- User Experience
- Before Starting
- Integration Process
- Example Flow
- Get Support
- Front-end component: Everything that the user sees on a mobile app
- Back-end component: The component of a mobile app that operates on a server. It stores, secures, and processes the data
- WebView: An in-app browser that displays interactive web content as part of the front-end component. Android platforms use a WebView object, iOS platforms use a WKWebView object
- DeepLink: A link that opens and passes specific data to the front-end component
- Flutter: An open source framework by Google for building beautiful, natively compiled, multi-platform applications from a single codebase. Although developed by Google, Flutter can be used for both Android and iOS applications
This process requires the use of your Smart Checkout API credentials. To avoid security issues, you should not store these credentials in the front-end component
Both the App Store and Play Store impose a set of regulations for apps that use an external payment service provider. The apps that offer specific products mentioned in their guidelines must be using Apple IAP/Google Play’s billing system. Before starting an app integration, please review Apple Store payment guidelines and Google Play billing guidelines to see if you are eligible to accept payments from a third party or not.
Please notice the following points to ensure that the Web View integration works smoothly.
- Please do not load a page that opens Viva Wallet Smart Checkout inside an iframe. Using an iframe will disable certain features, it will also result in a poor user experience, and thus overall reduce significantly your conversion rates.
- If a user selects to pay with different payment methods, our smart checkout can make redirection to the relevant page of an alternative payment method. In this case, please make sure that you are not intercepting the process during the user’s navigation.
Step 1: Create Order Code
When a customer clicks the “Pay” button on the appropriate step/screen of the mobile app, the front-end component sends the relevant data to the back-end component. Here, you must not rely on the data coming from the front end. You should verify it or rely on back-end data for important values such as Amount, IsvAmount, etc.
The back-end application sends a create payment order request to Viva Wallet servers and receives the Viva Wallet payment order code. Please see Step 1: Create the payment order.
The back-end component saves the order details to verify them later.
The back-end component then returns the payment order code to the front-end component.
Step 2: Redirect Customer to Smart Checkout
As soon as the payment order is received, the front-end component opens a WebView and loads the Viva Wallet Smart Checkout. Please see Step 2: Redirect the customer to Smart Checkout.
The customer then completes the payment and is redirected to the Success URL or the Failure URL inside the WebView.
The following features should be allowed in the WebView:
- Redirects – for bank and 3DS authorization (for all payments), as well as for certain payment methods, such as iDEAL. If the WebView blocks redirects, the customer will not be able to complete the transaction
- Pop-ups – for payment methods which utilise modals, such as PayPal
- Scripts – for payment methods which utilise scripts, such as Apple Pay
Step 3: Handle Redirect and Verify Payment
There are a few options for handling the redirection and verifying the payment:
Option 1: Listening for Redirect URL:
The front-end component detects the URL changes on the WebView browser. As soon as the URL matches the Success or Failure URL, the front-end component captures the URL, parses the transactionId (in the case of success) or the eventId (in the case of failure), and closes the WebView.
The back-end component updates the status of the payment.
The front-end component sends the transactionId or the eventId to the back-end component and verifies the status of the payment.
The front-end component then shows the result to the customer.
Option 2: Using DeepLink:
DeepLinks are a type of link that send users directly to an app instead of a website. Similarly to the above Option 1: Listening for Redirect URL, this option relies on the Success or Failure URL.
When a user is redirected to a DeepLink through the browser, they are sent to the in-app location where you initially wanted them to land. You may pass the transaction information (the transactionId or the eventId) to your app, via a DeepLink.
The result of the payment is then shown to the customer.
Some users may prefer to pay with an external banking app supported on Smart Checkout, such as Payconiq. In this case, the bank app will not know how to return to your app so the result will be passed to your Success or Failure URL via the browser. In this situation, forwarding users to your app via a DeepLink can help you to pass the result to your mobile app.
Option 3: Using Webhook:
When the payment is completed, Viva Wallet sends a notification to the back-end component. For successful transactions, please see the Transaction Payment Created webhook. For failed transactions, please see the Transaction Failed webhook.
The back-end component confirms the status of the payment and sends this information to the front-end component.
The front-end component closes the WebView and shows the result of the payment to the customer.
Webhooks should be handled on your back-end service. Once you get the Viva Wallet notification to your back-end, you should process it and send the result with a silent notification to your mobile app. So your app can take appropriate action.
- In the mobile app, when the customer wants to pay for an order, a WebView is opened inside the mobile app
- There is a timer which regularly checks the current URL being displayed by the WebView
- If/when the URL matches the “success” URL, the mobile app closes the WebView, retrieving the transactionId and proceeds to process the order of the customer: inserting the order into the system, clearing the current basket and everything else that needs to be done according to the processes of our business
- If/when the URL matches the “failed” URL, the mobile app retrieves the eventId and proceeds to handle the payment failure according to the processes of our business
If you have any questions about our solutions, or questions about how to integrate with our solutions, please refer to our Get Support page.