Introduction

This a guide to integrate with Merit Marketplace and enable users to login via SSO.

Upon successful integration, users can choose from Merit's large catalog and use their points to redeem rewards.

Clients must implement the following API to support the integration with Merit Marketplace.

1. Get Access Token (machine-to-machine authentication)
2. Get User by MemberId
3. Get Point Balance
4. Debit Points
5. Refund Points

Merit will provide clients with the following API

1. Get Access Token (machine-to-machine authentication)
2. SSO Login

Client Implementation

M2M Authentication

With machine-to-machine (M2M) applications, such as CLIs, daemons, or services running on your back-end, the system authenticates and authorizes the app rather than a user. For this scenario, we use the Client Credentials Flow.

Credentials must be granted per loyalty program. If an organization has more than one loyalty program, they must provide Merit one set of credentials for each loyalty program.

Get Access Token

curl --location -g --request POST '{{baseUrl}}/identity/v1/clients/token' \
--header 'Content-Type: application/json' \
--data-raw '{
    "clientId": "{{clientId}}",
    "clientSecret": "{{clientSecret}}"
}'

If successful, the above command returns JSON structured like this:

{
    "data": {
        "accessToken": "SuM-qV4WCs6rjkX3zzKMU9tnzP--FiR8ZKRG2NCHwTFKRaVabIaIf17glCcs_b50rFM8JzKy7b_AMy10UtTSfonS7ddK56MQuDA5OPfyKvYCinxsXi4l5L_JSam2Juqq5-YNZ3bjXxXzj6sOiVs-WhJwThL4v3Umeizs-ea3cqU",
        "expiresIn":  3600,
        "tokenType":  "Bearer"
    }
}

Sample error response. Please refer Errors for more information.

{
    "code": "ERR-1001",
    "message": "invalid client credentials"
}

Use Client ID and Client Secret to authenticate and get access token.

HTTP Request

POST {{baseUrl}}/identity/v1/clients/token

Request Headers

Request Schema

Success Response Schema

Error Response Schema

Member ID

Unique identifier of the user within the loyalty program

1. Must be unique within the loyalty program.
2. After the user is created, Member ID can't be changed.
3. Maximum length of 128.
4. Allowed characters are A-Z, a-z, 0-9, :, -, @, ..

Get User by MemberId

curl --location -g --request GET '{{baseUrl}}/identity/v1/users/{{memberID}}' \
--header 'Authorization: Bearer {{AccessToken}}'

If successful, the above command returns JSON structured like this:

{
    "data": {
        "memberId": "U123456",
        "firstName": "John",
        "lastName": "Doe",
        "email": "john.doe@meritincentives.com",
        "phone": "+442072343456",
        "country": "GBR",
        "currency": "GBP",
        "language": "en",
        "metadata": {
            "gender": "MALE",
            "tier": "GOLD"
        },
        "isActive": true,
        "createdAt": 1672664992,
        "updatedAt": 1672664992
    }
}

Sample error response. Please refer Errors for more information.

{
    "code": "ERR-1002",
    "message": "invalid access Token"
}

HTTP Request

GET {{baseUrl}}/identity/v1/users/{memberID}

Request Headers

Success Response Schema

Error Response Schema

Exchange Rates

As a prerequisite, exchange rates from points to currencies must be configured while onboarding the loyalty program to Merit platform.

Example conversion table

Get Point Balance

curl --location -g --request GET '{{baseUrl}}/loyalty/v1/users/{{memberId}}/balance' \
--header 'Authorization: Bearer {{AccessToken}}'

If successful, the above command returns JSON structured like this:

{
  "data": {
    "points": 10000,
    "updatedAt": 1672664992
  }
}

Sample error response. Please refer Errors for more information.

{
    "code": "ERR-1002",
    "message": "invalid access token"
}

HTTP Request

GET {{baseUrl}}/loyalty/v1/users/{memberID}/balance

Request Headers

Success Response Schema

Error Response Schema

Debit Points

curl --location -g --request POST '{{baseUrl}}/loyalty/v1/users/{{memberId}}/debit' \
--header 'Authorization: Bearer {{AccessToken}}' \
--header 'Content-Type: application/json' \
--data-raw '{
    "referenceId": "REF123414342",
    "points": 100,
    "metadata": {
        "description": "Order #1234. Purchase of Amazon Gift Card"
    }
}'

The above command returns JSON structured like this:

{
  "data": {
    "id": "0c781f3f-fa61-460b-81e6-d1bf00d1fdd9"
  }
}

Sample error response. Please refer Errors for more information.

{

    "code": "ERR-3001",
    "message": "transaction with referenceId already exists"
}

HTTP Request

POST {{baseUrl}}/loyalty/v1/users/{memberID}/debit

Request Headers

Request Body Schema

Success Response Schema

Error Response Schema

Refund Points

curl --location -g --request POST '{{baseUrl}}/loyalty/v1/transactions/{{transactionId}}/refund' \
--header 'Authorization: Bearer {{AccessToken}}' \
--header 'Content-Type: application/json' \
--data-raw '{
    "points": 50,
    "metadata": {
        "description": "Order #1234. Cancellation of Amazon Gift Card"
    }
}'

Refund points (partial or total) against an existing debit transaction.

If successful, the above command returns JSON structured like this:

{
  "data": {
    "id": "0c781f3f-fa61-460b-81e6-d1bf00d1fdd9"
  }
}

Sample error response. Please refer Errors for more information.

{
    "code": "ERR-1002",
    "message": "invalid access token"
}

HTTP Request

POST {{baseUrl}}/loyalty/v1/transactions/{transactionId}/refund

Request Headers

Request Body Schema

Success Response Schema

Error Response Schema

Errors

Merit API

M2M Authentication

With machine-to-machine (M2M) applications, such as CLIs, daemons, or services running on your back-end, the system authenticates and authorizes the app rather than a user. For this scenario, we use the Client Credentials Flow.

Credentials are granted per loyalty program. If an organization has more than one loyalty program, Merit will grant each program it's own set of credentials.

Get Access Token

curl --location -g --request POST '{{baseUrl}}/identity/v1/clients/token' \
--header 'Content-Type: application/json' \
--data-raw '{
    "clientId": "{{clientId}}",
    "clientSecret": "{{clientSecret}}"
}'

If successful, the above command returns JSON structured like this:

{
    "data": {
        "accessToken": "SuM-qV4WCs6rjkX3zzKMU9tnzP--FiR8ZKRG2NCHwTFKRaVabIaIf17glCcs_b50rFM8JzKy7b_AMy10UtTSfonS7ddK56MQuDA5OPfyKvYCinxsXi4l5L_JSam2Juqq5-YNZ3bjXxXzj6sOiVs-WhJwThL4v3Umeizs-ea3cqU",
        "expiresIn":  3600,
        "tokenType":  "Bearer"
    }
}

Sample error response. Please refer Errors for more information.

{
    "code": "ERR-1002",
    "message": "invalid access token"
}

Use Client ID and Client Secret to authenticate and get access token.

HTTP Request

POST {{baseUrl}}/identity/v1/clients/token

Request Headers

Request Schema

Success Response Schema

Error Response Schema

SSO Login

curl --location --request POST '{{baseUrl}}/identity/v1/sso/login' \
--header 'Authorization: Bearer {{AccessToken}}' \
--header 'Content-Type: application/json' \
--data-raw '{
    "memberId": "U123466"
}'

The above command returns HTTP Status Code 302 (Redirect). User is redirected to Merit Marketplace and signs in automatically.

Sample error response. Please refer Errors for more information.

{
    "code": "ERR-1002",
    "message": "Invalid Access Token"
}

Initiate SSO login and redirect user to Merit Marketplace. User signs in automatically.

HTTP Request

POST {{baseUrl}}/identity/v1/sso/login

Request Headers

Request Body Schema

Error Response Schema