Make Your First SSO API Call

Punchh provides a robust platform for offering loyalty programs to customers. When a business integrates its back-end with the Punchh server, the Punchh APIs become instrumental in executing loyalty programs for enrolled customers, primarily via business-branded mobile apps and websites tailored by Punchh.

To establish integration with the Punchh APIs, you need to understand how they are invoked and what responses are returned by the Punchh server. You can call APIs using any suitable API test client. In the following sections, we use Postman to invoke the Punchh APIs. Thus, the response to every API call made in Postman under a chosen environment (in app and/or dashboard) is reflected in the app and/or dashboard.

Base URIs

Please contact your Punchh representative in order to receive the sandbox and production base URLs that you should be using in order to consume the Punchh APIs.

Step 1: Get Client and Secret

The following parameters are required in all API calls:

• client: A string that identifies a particular business

• secret: It is optional to pass the secret in the body of the API call, but it must be set in the settings of the environment (production/testing) before invoking any API.

• x-pch-digest: A signature placed in the header section of every API call. It is generated via a secure signature generating algorithm, as described in the following section.

For every business, values are different for the client and secret parameters.

Step 2: Generate Signature

You can use SHA1 (Secure Hash Algorithm) to generate a secure signature. Copy and paste the following function into the 'pre-request script' section of Postman. This function uses the secret parameter value to generate a secure signature.

Text
var index = request.url.indexOf('/api/');
var uri_path = request.url.substring(index);
var payload;
if(_.isEmpty(request.data)){
    payload = uri_path;
}else{
    payload = uri_path + request.data;   
}
console.log("Using payload as " + payload);
var hash = CryptoJS.HmacSHA1(payload, environment.secret);
var hashInBase64 = CryptoJS.enc.Hex.stringify(hash);
postman.setGlobalVariable("signature", hashInBase64);

Function To Generate Signature

The function can be implemented in any language of your choice. For reference, we provide implementations for generating x-pch-digest header in commonly used languages.

Now place the x-pch-digest parameter in the headers section along with other parameters. In place of its value, type {{signature}} so that this fetches the signature received from the pre-request function.

The signature is generated when you click the send button in Postman, and it goes along with other parameters as a significant element of the API call.

Step 3: Make the Request

Following is an example request for the sign-up user API call, which registers a user's profile in the Punchh server. It is invoked when a user presses the Submit button after entering profile information in the sign-up section of the app. The app then makes the sign-up API call to the Punchh server. The sign-up API requires the following parameters for a successful (yet incomplete) request:

client, email, and password

With headers, HTTP request method, endpoint, and function to generate the signature in place, you can now begin to invoke the Punchh API.

An example sign-up API request in cURL is provided below.

curl -X POST \
  https://SERVER_NAME_GOES_HERE.punchh.com/api/auth/customers.json \
  -H 'Content-Type: application/json' \
  -H 'x-pch-digest: X_PCH_DIGEST_GOES_HERE' \
  -d '{
    "client":"CLIENT_GOES_HERE",
    "user":
    {   "email":"test@example.com",
    "first_name":"FIRST_NAME_GOES_HERE",
    "last_name":"LAST_NAME_GOES_HERE",
    "password":"PASSWORD_GOES_HERE"
    }
}'

On success, Punchh returns the following JSON response.

{
    "address_line1": null,
    "anniversary": null,
    "avatar_remote_url": null,
    "birthday": null,
    "city": null,
    "created_at": "2019-12-20T03:46:49Z",
    "email": "test@example.com",
    "email_verified": false,
    "fb_uid": null,
    "first_name": "FIRST_NAME_GOES_HERE",
    "age_verified": false,
    "privacy_policy": false,
    "gender": null,
    "id": 111111111,
    "last_name": "LAST_NAME_GOES_HERE",
    "state": null,
    "updated_at": "2019-12-20T03:46:49Z",
    "zip_code": null,
    "allow_multiple": false,
    "apple_pass_url": "URL_GOES_HERE",
    "authentication_token": "AUTHENTICATION_TOKEN_GOES_HERE",
    "favourite_locations": null,
    "favourite_store_numbers": null,
    "marketing_email_subscription": false,
    "marketing_pn_subscription": false,
    "passcode_configured": false,
    "profile_field_answers": {},
    "referral_code": "REFERRAL_CODE_GOES_HERE",
    "referral_path": "URL_GOES_HERE",
    "secondary_email": null,
    "terms_and_conditions": false,
    "title": null,
    "user_as_barcode": "1111111",
    "user_as_qrcode": "QR_CODE_GOES_HERE",
    "user_code": "P11111111",
    "user_id": 111111111,
    "user_relations": [],
    "work_zip_code": null,
    "mindbody_client_id": null,
    "preferred_locale": "en",
    "force_password_reset": null,
    "expiration_date": "2020-06-17",
    "sms_subscription": false,
    "phone": null,
    "migrate_status": false,
    "email_unsubscribe": true,
    "allow_push_notifications": false,
    "facebook_signup": false,
    "communicable_email": "test@example.com",
    "access_token": null
}

The user object will get you information regarding every possible balance the user may have, so sometimes it is difficult to determine which type of redemption should be available for the user. A configuration is needed on the online ordering side to specify which type of redemption should be available for the entire business. The types of redemption are:

Reward

This is an offer available to the user. This may be awarded to the user as a result of some campaign or may be explicitly gifted by a business admin. No points will be deducted for the redemption of this offer.

Redeemable

These are core offers configured in the Punchh dashboard. For every reward, you will find the corresponding configured redeemable in the redeemable object. Also, if a business is configured for the "points unlock" program, redemption of these offers results in a deduction of points.

Discount Amount

Banked currency can be used for redemption if the program structure configured is "points convert to banked currency".

Card Completion / Unredeemed Card

This is part of a visit-based program.

Redemption Code

This is an intermediary code for the redemption of a reward or redeemable. The redemption code can be generated from an app or iFrame.

Purpose of iFrame

You can create an account on iFrame and use it for testing. You can also see the loyalty status of the user using iFrame.

There are two ways to implement sign-up:

• iFrame: If you use iFrame to sign up, no additional coding/development is required. Additionally, some elements of iFrame can be customized (e.g., colors). This can expedite implementation.
• API calls: This approach gives you the flexibility to implement any design of your choice. However, this requires custom coding/development for your intended UI.