Checkout Native App Integration
Integrate Billwerk+ Checkout in your native mobile app
Billwerk+ Checkout can be integrated into a native mobile app by using WebView approach.
NOTE
Deep Linking is required when using payment methods that can perform app switch such as MobilePay or Vipps. See here how to set up app scheme URL
Other payment methods such as Card Payment, Apple Pay or PayPal only requires an Accept and Cancel URL.
Requirements
- Deep linking setup ( iOS URL Scheme or Android Deep Links ).
- Native WebView ( iOS WKWebView or Android WebView ).
- Set your app scheme URL as an alternative return URL on Checkout session creation.
- NOTE:
alternative_return_url
is placed undersession_data
object. - Example:
alternative_return_url: "MyCustomApp://?"
.
- NOTE:
- Add
accept_url
andcancel_url
to Checkout session creation.- NOTE: This will indicate
Accept Event
andCancel Event
after handling incoming URL.
- NOTE: This will indicate
- Handle incoming URL once returned back from Mobile Payment App e.g. MobilePay ( iOS handle incoming URL or Android handle incoming URL ).
- NOTE: The incoming URL consists of your app scheme URL and query parameter
returnUrl
. E.g.MyCustomApp://?returnUrl=https://checkout.reepay.com/...
. - Once Billwerk+ Checkout return URL has been loaded in WebView, it will redirect to your accept or cancel URL afterwards.
- NOTE: The incoming URL consists of your app scheme URL and query parameter
- Handle WebView URL changes.
- Register URL listener on WebView to register when Billwerk+ Checkout has redirected to your accept URL (indicates
Accept Event
) or cancel URL (indicatesCancel Event
).
- Register URL listener on WebView to register when Billwerk+ Checkout has redirected to your accept URL (indicates
Redirect to App
For payment methods that has Mobile App such as Vipps/MobilePay/Swish, Billwerk+ Checkout redirects to their app scheme URL (e.g. Vipps app vipps://...
) when the Checkout detects a Mobile Device.
Otherwise, it will redirect to the payment method's original website (e.g. Vipps website https://vippsmobilepay.com/...
).
If you prefer to use web based redirect instead of app switch on Mobile Device, please refer to Vipps desktop flow flag or Swish desktop flow flag.
Return from App
Upon return from a Mobile Payment App such as MobilePay app, it will by default return to Billwerk+ Checkout website (https://checkout.reepay.com/...
). This will result in opening of a browser app on the mobile such as Chrome or Safari app.
To return to your own app, it is required to have created a Checkout Session with alternative_returl_url
that includes your app scheme URL such as:
{
...
"session_data": {
"alternative_return_url": "MyCustomApp://?"
}
...
}
The Mobile Payment App (e.g. MobilePay app), will return an URL that must be handled in your app. The returned URL will be MyCustomApp://?returnUrl=https://checkout.reepay.com/...
.
In your app, you would need to extract the actual returnUrl
and load it in your WebView. You can find how to handle incoming URL on iOS and Android here.
Handle events
Handling of events relies on URL changes. Your WebView must register a listener on URL changes. When creating a Checkout Session, it is required to add accept_url
and cancel_url
.
It is recommended to add additional query parameters to your URLs to contain relevant information that can be used after payment fails or completes. They be extracted once WebView has detected that the Checkout has redirected to Accept/Cancel URL.
{
...
"accept_url": "https://mywebsite.com/accept?id=xxx",
"cancel_url": "https://mywebsite.com/cancel?id=xxx",
...
}
Further development
It is generally recommended that your app handles other events such as when a user closes WebView/Checkout, creation of unique Checkout Sessions and a final screen after a payment has been cancelled or paid successfully.
This will provide the user the best user experience and a seamless mobile app payment experience.
Updated 10 days ago