Overview

Paze® messages can be conveniently retrieved via API request so merchants can display the promotion in the right place at the right time.

Returned Messages JSON content includes:

Message verbiage HTML tag
Identifiers
Start and end time for message display
Message placement

Implementing Messages

The Paze message component displays promotional content returned by the Paze Messages API. In terms of implementation, the mobile message component is defined and rendered by the merchant, but the actual message (content and date range) is retrieved via the API.

If you haven't already, start with one of the available checkout flows:

Integration Steps

There are three basic steps to retrieve Messages.

Generate Client Assertion
Get Access Token
Retrieve Messages

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

Steps 1 and 2 are consistent with those used in the API guides for Paze Checkout: Express Pay Flow or Review & Pay Flow

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:

iss: your client ID
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 PRACTICES: 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 lasts for 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. Retrieve Messages

Refer to the Messages API to retrieve Paze messages.

Example Request

curl --location 'https://mobile.wallet.cat.earlywarning.io/marketing/v2/messages' 
--header 'Content-Type: application/json' 
--header 'Authorization: Bearer <ACCESS_TOKEN_FROM_STEP_2>' 
--data '{
  "clientContext": " client-context-from-create-call",
  "data": {
    "profileId": "default",
    "messagePlacement": "checkout"
  }
}

Sample Response

{ 
  "count": 2, 
  "limit": 10, 
  "nextToken": "next-token-hash", 
  "data": [ 
    { 
      "messageId": "message-uuid-1", 
      "merchantId": "merchant-uuid-1", 
      "startTimestamp": "2025-12-01T00:00:00Z", 
      "endTimestamp": "2026-01-01T00:00:00Z", 
      "messagePlacement": "checkout", 
      "contentHtml": "<div data-paze-message-id=\"message-uuid-1\">Save $10 When You Spend $10 With Paze®</div>", 
      "contentNodes": [ 
        { 
          "type": "TEXT", 
          "content": "Save $10 When You Spend $10 With Paze" 
        }, 
        { 
          "type": "SUPERSCRIPT", 
          "content": "®" 
        } 
      ] 
    }, 
    { 
      "messageId": "message-uuid-2", 
      "merchantId": "merchant-uuid-1", 
      "startTimestamp": "2025-12-01T00:00:00Z", 
      "endTimestamp": "2026-01-01T00:00:00Z", 
      "messagePlacement": "checkout", 
      "contentHtml": "<div data-paze-message-id=\"message-uuid-2\"><strong>Save $30 With Paze® and Merchant1</strong><img src=\"https://www.paze.com/sites/default/files/2024-09/convenient.png\"/>\nFind terms and conditions here: <a href=\"https://www.paze.com\" target=\"_blank\">Learn More</a></div>", 
      "contentNodes": [ 
        { 
          "type": "HEADER", 
          "children": [ 
            { 
              "type": "STRONG", 
              "children": [ 
                { "type": "TEXT", "content": "Save $30 With Paze" }, 
                { "type": "SUPERSCRIPT", "content": "®" }, 
                { "type": "TEXT", "content": " and Merchant1!" } 
              ] 
            } 
          ] 
        }, 
        { 
          "type": "IMAGE", 
          "attributes": { 
            "src": "https://www.paze.com/sites/default/files/2024-09/convenient.png" 
          } 
        }, 
        { 
          "type": "SUBTEXT", 
          "children": [ 
            { "type": "TEXT", "content": "Find terms and conditions here: " }, 
            { 
              "type": "ANCHOR", 
              "attributes": { "href": "https://www.paze.com", "target": "_blank" }, 
              "content": "Learn More" 
            } 
          ] 
        } 
      ] 
    } 
  ] 
}

WHAT: Make a request to the retrieve all messages for the merchant
WHY: This endpoint provides the Merchant with the current offer (if one exists) along with page placement, start time, end time, and other attributes for display purposes.
WHEN: Make a call to this endpoint when you, the merchant, want to display the current offer to customers. Follow UX guidelines and best practices for display