Pay by Bank · Mobile SDK

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.

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.

JSON
[
{
  "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"
    ]
  }
}
]

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.

XML
<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.

Kotlin
class PayByBankReturnActivity : Activity() {
  override fun onCreate(savedInstanceState: Bundle?) {
      super.onCreate(savedInstanceState)
      if (isTaskRoot) {
          startActivity(Intent(this, MainActivity::class.java))
      }
      finish()
  }
}

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.

JSON
{
"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.

XML
<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.

If link verification fails, the return URL opens in a browser and the customer has to switch back to your app manually. The SDK still resumes when the app comes to the foreground, but the experience is worse - check the link with the commands in Testing.

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.