Integrate with a mobile app

On this page:

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

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.

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.

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:

Similarly to the above Option 1: Listening for Redirect URL, this option relies on the Success or Failure URL. In this case, the back-end component is listening for these URLs.

When one of these is detected, the back-end component forwards the transaction information (the transactionId or the eventId) to the WebView within the front-end component, via a DeepLink.

The result of the payment is then shown to the customer.

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.

This option is only recommended for synchronous payment methods in which the webhook notification will arrive promptly. For Asynchronous payment methods – such as alternative payment methods, Payconiq and others – options 1 and 2 should be considered instead

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.