Integrate with a mobile app

How to integrate with a mobile application.

User Experience

Definitions

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

Before Starting

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.

Integration Process

Please notice the following points to ensure that the Web View integration works smoothly.

  • Make sure that the JavaScript is enabled for your WebView.
  • Please do not load a page that opens Viva 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 servers and receives the Viva 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 Smart Checkout. Please see Step 2: Redirect the customer to Smart Checkout.

Flutter example:

@override
Widget build(BuildContext context) {
  return Scaffold(
    body: WebView(
      initialUrl: ' https://www.vivapayments.com/web/checkout?ref={OrderCode}  ',
      javascriptMode: JavascriptMode.unrestricted,
      userAgent: 'Flutter;Webview',
    ),
  );
}

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.

Flutter example:

@override
Widget build(BuildContext context) {
  return Scaffold(
    body: WebView(
      initialUrl: ' https://www.vivapayments.com/web/checkout?ref={OrderCode}  ',
      javascriptMode: JavascriptMode.unrestricted,

     userAgent: 'Flutter;Webview',
      navigationDelegate: (navigation){
        //Listen for callback URL
        //Capture the URL and close the WebView
        //Verify the payment and show the result
      }
    ),
  );
}

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 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 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.

Example Flow

  1. In the mobile app, when the customer wants to pay for an order, a WebView is opened inside the mobile app
  2. There is a timer which regularly checks the current URL being displayed by the WebView
  3. 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
  4. 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

Get Support

If you have any questions about our solutions, or questions about how to integrate with our solutions, please refer to our Get Support page.