Asynchronous Payments

In an asynchronous workflow a redirection takes place to allow the account holder to complete/verify the payment. After this the account holder is redirected back to the app and the status of the payment can be queried.

This article will guide you how to support communication between apps for the asynchronous payment methods.

NOTE: This article assumes you've already followed our First Integration tutorial.

iOS

Register a custom URL scheme

In Xcode, click on your project in the Project Navigator and navigate to App Target > Info > URL Types
Click [+] to add a new URL type
Under URL Schemes, enter your app switch return URL scheme. This scheme must start with your app's Bundle ID. For example, if the app bundle ID is com.companyname.appname, then your URL scheme could be com.companyname.appname.payments.

If your app is built using iOS 9 as its Base SDK, then you must add URLs to a whitelist in your app's Info.plist:

<key>LSApplicationQueriesSchemes</key>
<array>
    <string>com.companyname.appname.payments</string>
</array>

NOTE: If you have multiple app targets, be sure to add the return URL type for all of the targets.

Shopper result URL

Make sure that you send valid shopper result URL in the prepare checkout request. This URL will be opened after user passes verification or completes payment in another app (no matter successfully or not).

URL scheme should be the same that you've registered in the previous step. The rest part of URL can be any valid string (but not empty).
For example, com.companyname.appname.payments://test

Update your application delegate

Then, in order to finalize the step, in your application delegate you need to process the payment authorization URL.
Make sure that URL scheme is identical to the registered one in previous step. Then send notification to request payment status and display result to the customer.

iOS 8

- (BOOL)application:(UIApplication *)application openURL:(NSURL *)url sourceApplication:(NSString *)sourceApplication annotation:(id)annotation {
    if ([url.scheme caseInsensitiveCompare:@"com.companyname.appname.payments"] == NSOrderedSame) {
        // send notification to get payment status
        return YES;
    } else {
        return NO;
    }
}

func application(_ application: UIApplication, open url: URL, sourceApplication: String?, annotation: Any) -> Bool {
    if url.scheme?.caseInsensitiveCompare("com.companyname.appname.payments") == .orderedSame {
        // send notification to get payment status
        return true
    }
    return false
}

NOTE: The URL will not be opened for BOLETO payment brand. You can use another application callback to detect that the shopper returned to the app.

- (void)applicationWillEnterForeground:(UIApplication *)application {
    if (BOLETO_transaction_is_processed && [NSProcessInfo processInfo].operatingSystemVersion.majorVersion == 8) {
        // send notification to get payment status
    }
}

func applicationWillEnterForeground(_ application: UIApplication) {
    if BOLETO_transaction_is_processed && ProcessInfo().operatingSystemVersion.majorVersion == 8 {
        // send notification to get payment status
    }
}

iOS 9 and newer

- (BOOL)application:(UIApplication *)app openURL:(NSURL *)url options:(NSDictionary *)options {
    if ([url.scheme caseInsensitiveCompare:@"com.companyname.appname.payments"] == NSOrderedSame) {
        // send notification to get payment status
        return YES;
    } else {
        return NO;
    }
}

func application(_ app: UIApplication, open url: URL, options: [UIApplicationOpenURLOptionsKey : Any]) -> Bool {
    if url.scheme?.caseInsensitiveCompare("com.companyname.appname.payments") == .orderedSame {
        // send notification to get payment status
        return true
    }
    return false
}

Testing

You can test your custom URL scheme by opening up a URL that starts with it (e.g. com.companyname.appname.payments://test) in Mobile Safari on your iOS Device or Simulator.

In addition, always test your app switching on a real device.

Android

Register a custom URL scheme

Define the name of your custom scheme (for example companyname) and add intent filter to your target activity in the AndroidManifest.xml

<activity
    android:name="YOUR_ACTIVITY"
    android:launchMode="singleTask">

    <intent-filter>
        <data android:scheme="companyname"/>

        <action android:name="android.intent.action.VIEW"/>

        <category android:name="android.intent.category.DEFAULT"/>
        <category android:name="android.intent.category.BROWSABLE"/>
    </intent-filter>
</activity>

NOTE: it is important to use launchMode singleTask for target activity.

Shopper result URL

Use this scheme for result URL to request the checkout ID (for example companyname://callback).

Handle the redirect intent in target activity

Override onNewIntent method of your target activity to handle redirect intent and make payment status request.

@Override
protected void onNewIntent(Intent intent) {
    super.onNewIntent(intent);

    if (intent.getScheme().equals("companyname")) {
        String checkoutId = intent.getData().getQueryParameter("id");
        
        /* request payment status */
    }
}

NOTE: The URL will not be opened for BOLETO payment brand. You can use your Activity callback to detect that the shopper returned to the app, for example onStart().