Customize return URL

Enhance your mobile checkout experience with a custom return URL

SDKCurrentLast updated: October 5th 2021, @ 1:45:59 pm


A return URL redirects users back to the originating page during a checkout flow. For most integrations, using your application ID + ://paypalpay is the simplest and best returnUrl to use as part of the CheckoutConfig. However, there are circumstances when you may require greater control over the returnUrl, such as when your application ID has underscores.

Choose your custom return URL

Custom return URLs must end with ://paypalpay. You can customize anything that comes before.

In order to allow for seamless app switches, make the custom return URL unique. We recommend using reverse domain name notation.

If you're creating a custom return URL because your application ID contains underscores, then you can simply replace the underscores with periods. For example, you can change com.paypal.example_payment_application to com.paypal.example.paypal.application.

Prepare your app

Enable your app to respond to your custom redirect URL by registering new activities using the <activity> tag in the android manifest file.

Sample Native Checkout SDK code

<activity
    android:name="com.paypal.openid.RedirectUriReceiverActivity"
    android:excludeFromRecents="true"
    android:theme="@style/PYPLAppTheme">
    <intent-filter>
        <action android:name="android.intent.action.VIEW" />
        <category android:name="android.intent.category.DEFAULT" />
        <category android:name="android.intent.category.BROWSABLE" />
        <data
            android:host="paypalpay"
            android:scheme="YOUR-CUSTOM-SCHEME" />
    </intent-filter>
</activity>

<activity
    android:name="com.paypal.pyplcheckout.home.view.activities.PYPLInitiateCheckoutActivity"
    android:theme="@style/AppFullScreenTheme">
    <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:host="paypalxo"
            android:scheme="YOUR-CUSTOM-SCHEME" />
    </intent-filter>
</activity>

Modify the code

  1. Copy the sample Native Checkout SDK code and paste it into the code for your mobile checkout page.
  2. For both activities, replace YOUR-CUSTOM-SCHEME with the custom return URL that you chose in Step 1. In our example above, we would use com.paypal.example.paypal.application.

Step result

Your app can now respond to authentication and web checkout deep links.

Register the custom return URL

class YourApp : Application() {
    override fun onCreate() {
        super.onCreate()
        val config = CheckoutConfig(
            returnUrl = "YOUR-CUSTOM-SCHEME://paypalpay"
        )
        PayPalCheckout.setConfig(config)
    }
}
public class YourApp extends Application {
    @Override
    public void onCreate() {
        super.onCreate();
        CheckoutConfig config = new CheckoutConfig(
            //...,
            //...,
            //...,
            String.format("%s://paypalpay", YOUR-CUSTOM-SCHEME),
            //...,
            //...,
            //...
        );
        PayPalCheckout.setConfig(config);
    }
}

Note: Be sure to pass the custom return URL you created in Step 1, instead of your application ID.

Update the Developer Dashboard

Enter your custom return URL for your app on the Developer Dashboard. For details, see Integrate Android.