Public Documentation
HomePublic DocumentationAPI Reference
Start typing to search…

Mobile API Guide

Overview

This guide walks through integrating Paze Button with Express Pay into your checkout experience. Express Pay is a streamlined Paze checkout experience that allows customers to select their payment method, review their total, and complete payment directly within the Paze wallet. This eliminates the need to return to the merchant site for confirmation and helps reduce checkout drop-off.


At a high level, the sequence involves:

  • Getting API Access
  • Integrating the Paze Button
  • Creating a Paze checkout session on button click
  • Sample requests and responses
  • Completing the transaction

Sequence Diagram

The following sequence diagram illustrates how the merchant site , Paze API, and Paze Experience interact during this process. It is a quick reference that illustrates the end-to-end flow at a high level before a deep dive into the integration steps


Integration Steps

There are six basic steps to integrate the Button and Express Pay flow from the Paze API with your application:

  1. Generate Client Assertion
  2. Get Access Token
  3. Render Button
  4. Create Checkout Session
  5. Complete Checkout Session

Each step includes what’s happening, why it matters, when to implement, and notes on best practices.

1. Generate Client Assertion

When authenticating with the private_key_jwt method, your application must generate a JWT client assertion signed with your registered private key using the RS256 algorithm. This JWT is then passed as the value of the client assertion parameter in your token request. The JWT header must include the algorithm (alg) set to RS256, the type (typ) set to JWT, and a key ID (kid) corresponding to your public key.

The JWT payload must include the following:

  • sub: your client ID (same as iss)
  • aud: the token endpoint URL
  • exp: the expiration time in UNIX
  • iat: the issued-at timestamp
  • jti: a unique identifier for the JWT

WHAT: Create an RS256-signed JWT client assertion with claims iss, sub, aud, exp, iat, nbf, jti and header kid.

WHY: You must generate a client assertion to retrieve your access token.

WHEN: Create the client assertion before making a call to the token URL.

BEST PRACTICE: Never transmit private keys over the network.

2. Get Access Token

After generating your client assertion, make a call to generate your access token. The access token expires after 30 minutes.

Sample Request

curl --location 'https://auth.wallet.cat.earlywarning.io/token' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'grant_type=client_credentials' \
  --data-urlencode 'client_assertion=<CLIENT_ASSERTION_FROM_STEP_1>' \
  --data-urlencode 'client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer'

Sample Response

{
  "access_token": "eyJraWQiOi...",
  "expires_in": "1800",
  "token_type": "bearer"
}

WHAT: Make a call to the token generation endpoint by passing the valid client assertion RS256-signed JWT obtained in the previous step.

WHY: You must generate an access token to access the Paze services. The access token lasts 30 minutes, and in the event of expiration, generate a new token. Paze does not support refresh tokens.

WHEN: Obtain the access token after generating the client assertion.

BEST PRACTICE: Ensure the aud claim matches the exact token URL. If the token is expired, re-generate the assertion and re-request the token. RS256-signed JWT

3. Render button: Display the Paze Button adhering to brand guidelines

Merchants render the Paze button according to the Paze Checkout User Interface Standards guide. The required .SVG logo files and usage instructions are provided to merchants during onboarding. Use one of the approved colorways such as the preferred Paze Blue (#F042F8) or variants approved for monochromatic sites. Maintain clear space at least one-third of the logo’s height and display the button as a rectangular or pill-shaped button as outlined in the standards guide. It should load immediately with other wallet options, not hidden in menus, and match their visual prominence.

WHAT: Render the branded Paze button on your checkout pages. This button allows customers to initiate the Paze checkout experience by clicking. Make sure to adhere to the Paze Button Guide to ensure compliance. There are a few approved variants so you can align with your site’s design while staying compliant with brand guidelines.

WHY: The button offers a customer-driven entry point into the Paze experience.

WHEN: Render the button whenever you surface payment options in your checkout experiences.

BEST PRACTICE: Follow brand guidelines in the Paze Button Guide. Reference the button overview and checkout user interface standards.

4. Create Checkout Session

The checkout session create endpoint, v1/checkout/sessions/create, enables merchants to create a checkout session within a native mobile experience. This endpoint returns a URL that merchants can use to launch the Paze experience in a Secured WebView. Call this endpoint when a customer clicks the Paze button.

Sample Request

curl --location 'https://mobile-east.wallet.cat.earlywarning.io/v1/checkout/sessions/create' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer eyJraWQiOi...' \
  --data-raw '{
    "clientContext": "create-mobile-session-req",
    "data": {
      "client": {
        "id": "YOUR_CLIENT_ID",
        "name": "YOUR_MERCHANT_DISPLAY_NAME",
        "profileId": "YOUR_PROFILE_ID"
      },
      "sessionId": "14eb0b01-a6c0-40a0-8816-aecfa99d5954",
      "phoneNumber": "[email protected]",
      "emailAddress": "CUSTOMER_MOBILE_NUMBER",
      "callbackURLScheme": "pazecheckout",
      "actionCode": "START_FLOW",
      "intent": "EXPRESS_CHECKOUT",
      "transactionValue": {
        "transactionCurrency": "USD",
        "transactionAmount": "10"
      },
      "shippingPreference": "ALL",
      "billingPreference": "ALL"
    }
  }'

Sample Response

"data": {
    "pazeCheckoutUrl":  " https://checkout.wallet.cat.earlywarning.io/web/mobile/checkout?param=eyJwIjoiZXlKbGJtTWlPaUpCTWpVMlIwTk5JaXdpWlhod0lqb3hOell4T0RVNU5UYzVMQ0pwWVhRaU9qRTNOakU0TlRrd09Ua3NJbUZzWnlJNklsSlRRUzFQUVVWUUxUSTFOaUlzSW10cFpDSTZJakJFTmtOQk5UazJJbjAuTHNmTWpRQi1GSWtBTXNzS0djN0wzdk1pMElhamN3eDJ1OFpCSmpRak9EV0RwQXBHeThja2tZa1I0dGRDaGtuclVpYnRJQWxvUk1OVkk1dlVHanhFOG9TTGNfaV9fZXc3bkVFT3V2NllzOEtpRlZJSkhUQWNPS21VejZPcVVZWS14NHlobTJ1SFZaNXpaR0JhdVpFOEM3TjR6X21GOGthOXNxV0FLZUJHSUVOZjhVd0RPc2w1ckh2cmRObXhtUEJxdWVfWHBjdGNVb2x0clFOSW5FWHpyRVBmZHpYYkJLR0dmNVlNbGlCN2hoQ0xhU2t3MU9tS05iQlpMN1h0WVJBeVNaa3dRWWF3ZnByQk9vR25ZUmc5RWttTkJ6eElxVERjbnl1VWtTeUgzUVZfQ0w0OFQ5eDhTOF8tdHVBSW5hcUpWczVNN0gwcXdGRHQ1MFpWaUpFU0VBLmRSZXNNODNteW1qbjZzUzIuRXU4aERoS0FXMnRLc0VlNlFIRUJaTVpEUE5Ock9OVU9GMWdRN0t1VDA5OEh1UGJRWXBHb3FnMldad0pBRkx4QlJ2MW1nQlE2RWh3VEhqWmJvV05wUVNXTlktMzhJOXJoeThQaUdKTTh1MDhxN2E5ckpZcFdhUXZsQ2VsWXZyWWE5WF9xT3gzR3EydldzS04wQW1UelNkNEFRLTJBWWVuQy1MbXI1QU8zdTJJd3lXN1B6RVgxT1dZR1FVTUdteVVwd2ZzYUxldUVncmxoSlhiYU84T25BdEhvVTd4RFhpWkp4QUUzSV93UTFDQ1JHbkhhSGJwYWt2b1B1cUxiaEFHVXNOQm1FOENyVWo3b1dPY1V1ZWcwSGdxSjhSOS1CQkNRckxHbFdDY1hVSmowMDVlcUZUczJQeEJtT2NzR1JGZ3RFb2lCdWRydzZ2akhvb2pxb3ZlUXJoOE1uWXQtSW1PejBFVzljUVQyZERxcmk2akljNVhBTV9OZDhvMVRuMkYzdW9iUW5sZV9tLVRXSzY5Z09UNjk3WGxyelF4elE2eFVXRnRYMU9vendIcWFjUml0ZWFFYUFtTXAxdjI1cGZaZWVmVXlyV3VNelliRDU3eHhxQlh1ZENpa3Y4OGFKUnQ2ZC1EbWxjYlp1QkFfSG13MDBmWnhUNHREN3U5WHEwMlJKWEdoZHVPemh6MGxVZ19yYzR0TjhJSGhhSnBULkZRdXk3bGhNQWo2ZXJ0anlTTUVqcHcifQ "
  },
  "clientContext": "create-mobile-session-req",
  "ewSID": "dd97217a-cd71-4c8b-9d97-3599d24c704e",
  "timestampISO8601": "2025-10-10T01:35:16Z"
}

WHAT: Make a call to checkout sessions create to start your checkout session when the customer presses the Paze button.

WHY: You must generate the Paze checkout URL to launch the Paze checkout experience.

WHEN: Embed the Paze checkout URL with a Paze button to initiate the checkout experience when the customer clicks on Paze.

BEST PRACTICE: Paze recommends opening the URL in ASWebAuthenticationSession for iOS and Android Custom Tabs to ensure that returning Paze users have a seamless login experience.

REDIRECT URL: After the customer completes their checkout, a redirect URL is returned pazecheckout://status=success#response=ZXlKaGRXUWlPbTUxYkd3c0ltdHBaQ0k2SWpVd016UkJRamt6TkRkRk9UUTBRa1V3UVRaRlFrVkNRall3UkVVMk5UVkZORUpDUVVaRE5qUWlMQ0pwYzNN

5. Call Checkout Complete

The checkout session complete endpoint (v1/checkout/sessions/complete) returns a JSON Web Signature completeResponse which can be verified with Paze public key for authenticity, then decoded with a base64 decoder. This contains the sessionId which matches the other calls in this session. The securedPayload is a JSON Web Encryption (JWE) that is encrypted and must be decrypted with the merchant's private key associated with the certificate provided by the merchant during onboarding. This object contains the data needed for your payment services provider to process the transaction. The dynamic data cryptogram is sent by the merchant to the payment processor and is valid for 24 hours.

Sampe Request

curl --location 'https://mobile-east.wallet.cat.earlywarning.io/v1/checkout/sessions/complete' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer eyJraWQi...' \
  --data '{
    "clientContext": "client-context-from-create-call",
    "data": {
      "transactionType": "PURCHASE",
      "sessionId": "YOUR_SESSION_ID",
      "code": "eyJhdWQiOm...",
      "transactionOptions": {
        "merchantCategoryCode": "2121",
        "billingPreference": "ALL",
        "payloadTypeIndicator": "PAYMENT"
      },
      "transactionValue": {
        "transactionCurrency": "USD",
        "transactionAmount": "10"
      }
    }
  }'

Sample Response

{
  "data": {
    "completeResponse": "eyJhdWQiOm...",
    "payloadId": "5C8DE7AFC400cb9b1c61-91d2-ab9a-1ebc-108435823a01",
    "securePayload": "eyJraWQiOiJwY..."
  },
  "clientContext": "client-context-from-create-call",
  "ewSID": "1cde1f8c-572d-4fc5-b329-e48e084a2360",
  "timestampISO8601": "2025-12-04T04:03:45Z"
}

What: Make a call to the complete endpoint to close the merchant and customer sessions.

Why: This endpoint closes the Merchant and customer sessions (where applicable) and provides a payment identifier and if requested, the card details required to process the transaction.

When: Make a call to this endpoint when you, the merchant, is ready to receive the securePayload or completeResponse completing the flow and submitting for payment processing. The dynamic data cryptogram is sent to the payment processor and is valid for 24 hours.

NOTE: The redirect URL contains the callbackURLScheme and the response parameter contains a Base64-encoded code. Decode it before calling the complete endpoint. The code can only be used within 8 minutes of receiving the checkout response.


Decoded completeResponse

After receiving the completeResponse JWS, first decode it to extract the JSON payload containing payloadId, sessionId, and optionally securedPayload.

{
  "payloadId": "5C8DE7AFC400c", // Required: String (≤ 50 chars)
  "sessionId": "YOUR_SESSION_ID", // Optional: String (echoed if provided)
  "securedPayload": "eyJhbGciOi..." // Conditional: String (JWE<JWS<Payload>>)
}

Decrypted securePayload

Decrypt the securePayload using the merchant's private key. The decrypted payload contains sensitive information necessary for you to process the transaction

{
  "clientId": "merchant-12345", // Required: String
  "profileId": "profile-6789", // Required: String
  "eci": "05", // Optional: String (ECI code)
  "consumer": {
    // Required: Object (Consumer)
    "fullName": "paul Doe", // Required: String
    "emailAddress": "[email protected]" // Required: String (RFC 5322)
  },
  "billingAddress": {
    // Conditional: Object (Address)
    "line1": "123 Main St", // Required: String
    "city": "Phoenix", // Required: String
    "state": "AZ", // Required: String
    "zip": "85001", // Required: String
    "countryCode": "US" // Required: String (ISO 3166-1 alpha-2)
  },
  "token": {
    // Required: Object (Token)
    "paymentToken": "[Removed]", // Required: String (network token)
    "tokenExpirationMonth": "12", // Required: String (MM)
    "tokenExpirationYear": "2028", // Required: String (YYYY)
    "paymentAccountReference": "PAR1234567890" // Required: String (PAR)
  },
  "paymentCardNetwork": "VISA", // Required: Enum (VISA | MASTERCARD | DISCOVER)
  "dynamicData": [
    // Required: Array<DynamicData>
    {
      "dynamicDataType": "PURCHASE", // Required: Enum (PURCHASE | CARD_ON_FILE)
      "dynamicData": "CiAgICAg...", // Required: String (cryptogram) This is sent to the payment processor as is and is not decrypted by the merchant. The cryptogram is valid for 24 hours.
      "dynamicDataExpiration": "2025-12-31T23:59:59Z" // Optional: String (ISO 8601)
    }
  ]
}




Updated 3 days ago