API Reference

Client UX Integration

 Client UX Integration

This section describes how to launch the UI/UX from a mobile application and return to the mobile application.

Once the mobile app receives thePazecheckout URL from the /checkout/session/create API call, and the consumer taps the Paze button (or related action), the mobile app needs to open the Paze checkout URL in the specific WebView control for the given mobile operating system. The WebViews maintains the state between multiple invocations and across the main browser as well as other apps, providing the best experience to a returning consumer.

Operating SystemWebView Control to Use
iOSASWebAuthenticationSession
AndriodCustom Chrome Tab

When the consumer exits the Paze UX, the Paze API  redirect the WebView to the callbackURLScheme that the Merchant has provided in the `/checkout/session/create` API call.

It is expected that this URL is provided in a native mobile format that will cause control to return to the native mobile app.

On redirect to this schema, the Paze API appends query string parameters of status and a hash(#) param response.

  1. "status" parameter with one of the following values:
    • success - the consumer successfully completed the Paze checkout steps, and the Merchant can utilize the other Paze APIs to get data to display or to get the secure payload
    • canceled – the consumer cancelled out of the Paze UX before the last step
    • failed – there was some error encountered during the Paze UX flow
  2. “response” parameter, includes a Base64URL encoded string with a JWS containing the minimal 'maskedCard' structure in the claim section. Once decoded the JWKS is the code for review/complete call.

Implementation Examples

iOS

This section will describe the iOS specific setup and code to launch the Paze checkout experience in a webview. The webview that must be used for iOS is the ASWebAuthenticationSession.

  1. Import the `AuthenticationServices` framework in the project file.
    • import AuthenticationServices
  2. Configure the URL Scheme
    • Open your Xcode project.
    • Go to the project settings, select your target, and open the "Info" tab.
    • Add a new URL Type by clicking on the plus button.
    • Set the callback URL scheme (e.g., com.domain.appid).
  3. ASWebAuthenticationSession takes two parameters:
    • url
    • callbackURLScheme

Implementation

class PazeViewController: UIViewController, ASWebAuthenticationPresentationContextProviding {
    // startPaze should be called when user hit PAZE checkout button 
    func startPaze() {
        /* pazeURL will be returned in /checkout/session/create response.this is the same, callbackURLScheme which is passed in createCheckoutSession, generally it is app’s bundle identifier( like – com.domain.appName ) */
        let callbackPazeScheme = "com.domain.appid"
        let sessionPaze = ASWebAuthenticationSession.init(url: pazeURL, callbackURLScheme: callbackPazeScheme) {
            callbackURL,
            error in guard
            let successCallbackURL = callbackURL,
                error == nil
            else {
                // Handle error; checkout with Paze has not be successful.
                return
            }
            let queryItems = URLComponents(string: successCallbackURL.absoluteString) ? .queryItems
                // Extract 'status' and 'response' from queryItems and proceed accordingly
        }
        session.presentationContextProvider = self
        session.start()
    }
    func presentationAnchor(
        for session: ASWebAuthenticationSession) - > ASPresentationAnchor {
        return self.view.window!
    }
}

Android

This section will describe the Android specific setup and code to launch thePazeexperience in a webview. The webview that must be used for Android is the Custom Chrome Tab (CCT).

  1. Add your Dependencies in the  build.gradl file:
    • implementation androidx.browser:browser:<version>
  2. Configure the Custom URL Scheme
    • Open your AndroidManifest.xml.
    • Add an intent filter to handle the callback URL scheme (e.g., 'com.domain.app_name').

AndroidManifest.xml

 <activity android:name=.PazeCallbackActivity”>
 <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:scheme="<com.domain.app_name>"; android:host=”callback” />
 </intent-filter>
</activity>

Implementation

Launch the WebView

 import android.content.Intent;
 import android.net.Uri;
 import androidx.appcompat.app.AppCompatActivity;
 import androidx.browser.customtabs.CustomTabsIntent;
 public class PazeActivity extends AppCompatActivity {

     @Override
     protected void onCreate(Bundle savedInstanceState) {
         super.onCreate(savedInstanceState);
         setContentView(R.layout.activity_paze);
         startPaze();
     }

     private void startPaze() {
         // pazeURL will be returned in createCheckoutSession response
         Uri uri = Uri.parse(pazeUrl);
         CustomTabsIntent.Builder builder = new CustomTabsIntent.Builder();
         CustomTabsIntent customTabsIntent = builder.build();
         customTabsIntent.intent.setData(uri);
         customTabsIntent.launchUrl(this, uri);
     }

 }

Handle the Callback

public class PazeCallbackActivity extends AppCompatActivity {

    /* This is the same callbackURLScheme which is passed in   
    createCheckoutSession; generally it is app’s applicationId (like – 
    com.domain.appName )*/
    private static final String CALLBACK_SCHEME_PAZE = "com.domain.app_name";

    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        Uri uri = getIntent().getData();
        if (uri != null && uri.getScheme().equals(CALLBACK_SCHEME_PAZE)) {
            // Process 'status' and 'response' parameters and proceed accordingly
        }
        finish();
    }

}