Integrate with a mobile app

How to integrate with a mobile application.

• User Experience
• Definitions
• Before Starting
• Integration Process
  • Step 1: Create Order Code
  • Step 2: Redirect Customer to Smart Checkout
  • Step 3: Handle Redirect and Verify Payment
• Example Flow
• Get Support

User Experience

Definitions

• 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

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

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.

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.

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.

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.