Display the Hosted Payment Page

After obtaining the transaction ID, present the Hosted Payment Page to your user.

There are several methods to display the Hosted Payment Page:

• Redirect within the existing page

• Open in a new tab

• Embed within an iFrame

• Display within a webview

You can redirect the customer to the URL returned in the payment request initiation response. Alternatively, use the Base URL provided below with appropriate parameters to open the Hosted Payment Page.

Pre-requisite

• You have received a success response from the payment request initiation.

Method 1 (Preferred): Using redirectUrl returned from payment request initiation to open the Hosted Payment Page

You can use the redirectUrl returned in the Successful response of the payment request initiation to open the Hosted Payment Page.

If you are within a Native App environment, we recommend opening the redirectUrl using an external browser, rather than the in-app web-views.

{
    "initResult": {
        ...
        "redirectUrl": "https://airtime.codapayments.com/airtime/begin?txn_id=7144594637002072212",
        ...
    }
}

Optional: Append optional query parameters to the redirectUrl before opening

Refer to Query parameters for a list of supported query parameters

---

Method 2: Using the Base URL & attaching all query parameters to construct the Hosted Payment Page URL

Environment	Base URL
Sandbox	https://sandbox.codapayments.com/airtime/begin
Production	https://airtime.codapayments.com/airtime/begin

If you are within a Native App environment, we recommend opening the redirectUrl using an external browser, rather than the in-app web-views.

Query parameters

Parameter	Required	Description
txn_id	Mandatory	Mandatory The transaction ID you've collected after initiating the payment
browser_type	Optional	Optional If your user is on a mobile device, browser_type=mobile-web needs to be passed to make sure that the payment page is optimised to the device. If any other value or none is passed, the payment page will be optimised for a desktop view.
utm_souce	Optional	utm_source as it is detected in your page URL. For example, utm_souce=google, utm_source=coda
utm_medium	Optional	utm_medium as it is detected in your page URL. For example, utm_medium=banner, utm_medium=email
utm_campaign	Optional	utm_campaign as it is detected in your page URL. For example, utm_campaign=spring_sale, utm_campaign=new_season_launch
utm_content	Optional	utm_content as it is detected in your page URL. For example, utm_content=, utm_content=email

Samples

Desktop on Sandbox

https://sandbox.codapayments.com/airtime/begin?txn_id=7144594637002072212&utm_source=testing

Mobile in Production

https://airtime.codapayments.com/airtime/begin?txn_id=7144594637002072212&browser_type=mobile-web&utm_source=facebook

Unlocking Marketing analytics on payment page

Our payment page supports marketing analytics out-of-the-box. You can pass along UTM parameters from your store's page to the Codapay page. The UTMs will then be available in your payment funnel data analysis & marketing channel attribution analysis.

* We recommend that you pass along UTM parameters without any modifications, so that analytics data collected on the hosted payment page can be used together with other analytics data captured on your web page (for instance, data captured using Google Analytics) without any discrepancies.

Example:

The user landed on your page with this UTM tracked URL:

https://game.webstore.com?utm_source=google&utm_medium=cpc&utm_campaign=123412341234&utm_content=creative_123

Then, when the user makes a purchase, you can pass along the UTMs to the Codapay page URL along with other mandatory URL parameters:

https://airtime.codapayments.com/airtime/begin?txn_id=7144594637002072212&browser_type=mobile-web&utm_source=google&utm_medium=cpc&utm_campaign=123412341234&utm_content=creative_123

Special Considerations for Webviews

Handling redirection

Some channels may redirect users to their wallet app. To handle the redirections properly when using Webviews, you will need to use WebViewClient.shouldOverrideUrlLoading using the intents below:

Regions	Channel list	Override URL	Only support external browser
Brazil	PicPay	picpay://
Brazil	AmeDigital	amedigital://
Indonesia	GO-PAY	gojek://
Indonesia	Shopee Pay	shopeeid:// & shopeepayid://
Indonesia	Dana	danaid:// & market://details?id=id.dana
Malaysia	GrabPay	grab://
Malaysia	Shopee Pay	shopeepaymy://
Malaysia	Maxis	sms:32083
Malaysia	-	-	U Mobile
Singapore	GrabPay	grab://
Philippines	GrabPay	grab://
Philippines	GCash	gcash://
Thailand	Shopee Pay	intent://
Taiwan	Line Pay	intent://
Myanmar	KBZPay	intent://
United States	Cash App	cashme://
Vietnam	MoMo	momo://
All countries	-	-	Google Pay/Apple Pay

Common Webview Pitfalls and Tips

Android WebView Configuration

When using Android's WebView, configure WebViewClient as follows:

1. Override the onCreateWindow Method:

override fun onCreateWindow(view: WebView, dialog: Boolean, userGesture: Boolean, resultMsg: Message): Boolean {
    val newWebView = WebView(view.context)
    view.webViewClient?.let { newWebView.webViewClient = it }
    val webSettings = newWebView.settings
    setWebSettings(webSettings)
    (resultMsg.obj as WebView.WebViewTransport).webView = newWebView
    resultMsg.sendToTarget()
    return true
}

1. Set WebView Settings:

fun setWebSettings(webSettings: WebSettings) {
    webSettings.javaScriptEnabled = true
    webSettings.setSupportMultipleWindows(true)
    webSettings.domStorageEnabled = true
    webSettings.loadsImagesAutomatically = true
    webSettings.mediaPlaybackRequiresUserGesture = false
    webSettings.cacheMode = WebSettings.LOAD_DEFAULT
}

ERR_UNKNOWN_URL_SCHEME

Root Cause

The webview only recognizes standard URL schemes like http and https. Custom schemes, such as weixin:// and qunaraphone://, are not recognized by the webview, leading to the error ERR_UNKNOWN_URL_SCHEME. This error indicates that the webview cannot handle the custom scheme provided by the payment channel.

Solution

To handle custom URL schemes, you need to override the shouldOverrideUrlLoading method in WebViewClient. This method allows you to intercept and manage URL loading behavior in Webview, ensuring that custom schemes are properly handled.

Steps to implement the solution:

1. Implement the shouldOverrideUrlLoading(WebView view, String url) method in your WebViewClient class.

2. Configure the method to intercept URLs and handle custom schemes:

   • Return true: When the URL uses a custom scheme that needs special handling. This indicates that Webview should not handle the URL and allows you to process it as needed.

   • Return false: For standard schemes (http, https), allowing Webview to load the URL as usual.

Example implementation:

kotlinCopy codeoverride fun shouldOverrideUrlLoading(view: WebView?, url: String?): Boolean {
    if (url != null && url.startsWith("customscheme://")) {
        // Handle custom scheme
        return true
    }
    return false // Default behavior for standard schemes
}

By implementing this method, you can ensure that custom URL schemes are properly redirected or handled according to your application's requirements, preventing the ERR_UNKNOWN_URL_SCHEME error.

Screen Rotation Issues

Screen rotation can cause the webview pages to refresh and display errors.

Solution

Add the following to your AndroidManifest.xml to prevent activity restart on screen orientation change:

xmlCopy code<activity
    android:configChanges="orientation|screenSize|keyboardHidden"/>

This ensures that the activity remains stable during screen rotation.

iOS Webview (about:blank)

Implement the WKUIDelegate delegate and set it to _webview.uiDelegate. Then implement:

- (WKWebView *)webView:(WKWebView *)webView createWebViewWithConfiguration:(WKWebViewConfiguration *)configuration forNavigationAction:(WKNavigationAction *)navigationAction windowFeatures:(WKWindowFeatures *)windowFeatures
{
  if (!navigationAction.targetFrame.isMainFrame) {
    [webView loadRequest:navigationAction.request];
  }

  return nil;
}

iOS Webview (Capture redirect URL)

WKWebView is located at the iOS system level and cannot be directly accessed or modified via API. Due to the strict limitations of iOS, we recommend:

webView(_:createWebViewWith:for:windowFeatures adjust
swift

func webView(_ webView: WKWebView, createWebViewWith configuration: WKWebViewConfiguration, for navigationAction: WKNavigationAction, windowFeatures: WKWindowFeatures) -> WKWebView? 
{ if navigationAction.targetFrame == nil { webView.load(navigationAction.request) } return nil }
{ if navigationAction.targetFrame == nil { webView.load(navigationAction.request) } return nil }