Return URL setup
The bank sends the customer back to your app through the HTTPS return URL you pass to the SDK. Register it as an App Link on Android and a Universal Link on iOS so the hand-back reopens your app.
Choose the return URL
Use an HTTPS URL on a domain you control, for example
https://pay.example.com/pay-by-bank/return, and pass the same value to
processBankPayment. The argument is required - the SDK does not fall back to
a URL of its own. The API validates it and rejects custom URL schemes such as
myapp://pay-by-bank/return, so the return has to be a web link.
Android: App Links
For the full reference, see Android's App Links documentation. The steps below cover the minimum the SDK needs.
1. Host the verification file
Serve https://<your-host>/.well-known/assetlinks.json over HTTPS with a
application/json content type, no redirects and no authentication. It must list
your package name and every certificate the app is signed with - the debug
keystore, the release keystore, and the Play App Signing key certificate when you
use Play App Signing.
[
{
"relation": ["delegate_permission/common.handle_all_urls"],
"target": {
"namespace": "android_app",
"package_name": "com.example.app",
"sha256_cert_fingerprints": [
"AA:BB:CC:DD:EE:FF:00:11:22:33:44:55:66:77:88:99:AA:BB:CC:DD:EE:FF:00:11:22:33:44:55:66:77:88:99"
]
}
}
]2. Declare the App Link
Add an intent filter for the return URL to the activity that should receive it.
autoVerify is what makes Android open your app instead of the browser once it
has checked the verification file.
<activity
android:name=".PayByBankReturnActivity"
android:exported="true"
android:excludeFromRecents="true"
android:noHistory="true"
android:theme="@android:style/Theme.NoDisplay">
<intent-filter android:autoVerify="true">
<action android:name="android.intent.action.VIEW" />
<category android:name="android.intent.category.DEFAULT" />
<category android:name="android.intent.category.BROWSABLE" />
<data
android:scheme="https"
android:host="pay.example.com"
android:pathPrefix="/pay-by-bank/return" />
</intent-filter>
</activity>3. Return to the existing screen
The bank returns while the SDK's payment sheet is open. Opening your normal entry activity for the link would stack a second copy of the app on top of the sheet, so use a no-display trampoline like the one above. It brings the existing task - and the sheet - back to the foreground and finishes immediately. On a cold start there is no task to return to, so send the customer to your normal entry point.
class PayByBankReturnActivity : Activity() {
override fun onCreate(savedInstanceState: Bundle?) {
super.onCreate(savedInstanceState)
if (isTaskRoot) {
startActivity(Intent(this, MainActivity::class.java))
}
finish()
}
}iOS: Universal Links
For the full reference, see Apple's Supporting associated domains documentation. The steps below cover the minimum the SDK needs.
1. Host the association file
Serve https://<your-host>/.well-known/apple-app-site-association over HTTPS
with a application/json content type, no redirects and no authentication. It
lists your Apple Team ID, bundle ID and the path the link uses.
{
"applinks": {
"apps": [],
"details": [
{
"appIDs": ["TEAMID1234.com.example.app"],
"paths": ["/pay-by-bank/return*"]
}
]
}
}2. Add the Associated Domains capability
Enable Associated Domains on the App ID and for the app target, then add the return URL's host to the entitlements file.
<key>com.apple.developer.associated-domains</key>
<array>
<string>applinks:pay.example.com</string>
</array>Universal Links only open your app from another app - a banking app, a browser, Messages or Notes. Typing the URL into Safari opens the web page instead. Apple also caches the association file, so allow time after a change and reinstall the app after changing the entitlement.
What the SDK does when the customer returns
If the bank loads the return URL inside the SDK's sheet, the SDK recognises it and resumes the payment. If the bank opened its own app or an in-app browser instead, the SDK resumes as soon as your app comes back to the foreground through the App Link or Universal Link.
There is no return URL parsing to write: the SDK resumes the transaction and reports the outcome through the payment result callback. Keep the rest of your app's handling out of the way - the trampoline activity above is enough on Android.
The return page - the backup that catches everything
The bank arrives at the return URL with a plain browser GET, so the URL must
answer a GET request - an endpoint that only accepts POST never sees the
customer come back.
Host a page at the URL itself. When the App Link or Universal Link works the customer never sees it; the page is the fallback for everything that goes wrong - verification that has not completed, an install without the capability, or a browser the link could not leave. A minimal page telling the customer to return to your app is enough; without one they land on a 404.
Build the link and the page with two things in mind:
- Treat nothing in the URL as proof of anything. It arrives from a browser redirect and can be typed by hand. The result of a payment is whatever PaySuite tells you when you ask - see Retrieve a transaction.
- Parameters may be appended to your link. The PaySuite Payment Page adds
the session id to the
returnUrl, so the link your app is opened with is not byte-for-byte the one you sent. Build it so extra query parameters do it no harm.
Once the flow reaches the return URL there is nothing left for your app or
the page to do. The SDK recognises the return, resumes the transaction once
and reports the outcome through the payment result callback. The payment can
still be PENDING while the bank transfer settles, so keep the transaction
id and retrieve the transaction
for the final status.
Next steps
- Take a payment - pass this return URL to
processBankPayment. - Testing - verify the link and complete a payment in MITE.