September 19, 2020

Safepay Checkout for mobile apps

Today, we’re excited to announce support for our newest source -mobile.

Along with Woocommerce, Shopify, Opencart and more, mobile will be especially useful for developers looking to integrate the Safepay Checkout experience in their native mobile applications — be they iOS or Android, written in Swift, Java or even React Native.

In order to take advantage of this source in your applications, there are a few steps you’d need to follow. But on the whole, it’s extremely easy to integrate.

import querystring from "query-string";const params = {
beacon: "tracker_from_async_request",
order_id: "you-internal-order-id",
source: "mobile"
};// get the base url based on the environment
// you're integrating against
const baseURL = process.env.ENVIRONMENT === "PRODUCTION" ?
"https://api.getsafepay.com/components" : "https://sandbox.api.getsafepay.com/components";// url encode the params
const qs = queryString.stringify(params);
// construct the checkout url
const checkoutUrl = `${baseURL}?${qs};// redirect user to this url
return checkoutUrl

When constructing your Safepay checkout url, set the `source` param to mobile. For example in javascript you could do this:

One thing you’ll notice is that for mobile integrations the query params on the checkout url do not require redirect_url or cancel_url. This is because since the Safepay Checkout experience will be rendered inside a WebView, there isn’t a need for redirecting to an external website if your customer cancels or completes the payment. More on this below.

We recommend you construct the URL server side, but it can also be constructed within your app once your customer clicks the “Checkout” button.

Once you’ve constructed your URL, it’s time to pass it to the WebView for rendering. I’ll use pseudo `react-native` for code examples but the same ideas can be extrapolated to other languages like Swift and Java.

Assuming you’re using the react-community WebView, you can construct it like so:

renderWebView = () => {
return <WebView
// The main ones
source={{ uri: 'THE CHECKOUT URL' }}
onNavigationStateChange={this.onNavigationStateChange}// Extra props
ref={WEBVIEW_REF}
onError={this.onError}
onMessage={this.handleMessage}
domStorageEnabled={true}
javaScriptEnabled={true}
javaScriptEnabledAndroid={true}
style={{flex: 1}}
/>
};

The main props to take note off are source and onNavigationStateChange.

Now we get to why the initial Safepay Checkout params don’t require either the redirect_url or cancel_url params. When your customer cancels the payment, Safepay mark the transaction cancelled and navigate the user to /mobile?action=cancelled&order_id=<the-order-id>. If your customer completes the payment, Safepay will redirect your customer to /mobile?action=complete&….

Now the onNavigationStateChange prop comes in handy. In you application where you define the handler for this prop you can use this logic to handle both cancel and success steps:

onNavigationStateChange = (event) => {
const url = event.url

// If the customer has not been redirected to
// /mobile yet (meaning he has neither completed
// or cancelled the payment) do nothing.
if (url.indexOf("/mobile") === -1) {
return;
}// Get the query params as a string
const params = url.split(?)[1]
// parse the query string using the
// npm package
// https://github.com/sindresorhus/query-string
const parsed = queryString.parse(params);if (parsed.action === "cancel") {
// close the webview since the customer
// cancelled the paymentreturn;
}if (parsed.action === "complete") {
// the customer completed the payment,
// you should close the WebView and then
// asynchronously call your server to
// mark the payment complete.// Additionally, the params will include
- tracker
- reference
- token
- signature
}
};

In words, if your customer cancels the payment, you should simply close the WebView and take them back to your app’s checkout page. Optionally, you can take the order_id from the parsed params:parsed.order_id and mark the payment cancelled on your backend.

If they complete the payment however, you should first close the webview. After the webview is closed, you should asynchronously make a request to your backend to mark the payment complete and pass the params as well. The params on a successful payment will contain the following:

- tracker — This is the tracker token
- reference — This is the 6 digit transaction reference number
- token — This is the transaction token
- sig — This is the transaction signature
- order_id — This is your internal order id

You should pass these params back to your server to mark the order complete. You should also verify the signature to make sure the transaction is authentic. To learn more about Transaction verification, please check out our blog post on Transaction Integrity