Priceless Specials

Mastercard loyalty program in Poland. Learn how to integrate. Mastercard value added services platform in Czech and Slovakia. Learn how to integrate.

Introduction to RPM


RPM is a platform that supports loyalty program components using Mastercard Rewards System (MRS) API services to support the reward catalog.

Where to start? 

First check out our offers and make a decision: 

  1. How to connect with us - Learn about the MRS API which we use to integrate our customers with MC loyalty programs— for more information (here)
  2. Or maybe you are interested in integration between Issuer application and loyalty platform?  Check out our Webview implementation.
  3. Do you want to have your own Enrollment widget for direct user and card registration to MRS API? You can find more information here.

Intro slides

Rewards & Loyalty

Loyalty platform integrated with Mastercard Rewards Systems and other solutions enables collection of points, redemption of rewards and various value added functionalities.

Priceless Mastercard Rewards & Loyalty.png

MRS.png

Priceless Specials.png

Overview PL

Introduction

RPM is a paltform thet offers acces to loyalty services using various components.

The RPM consists of:

Main functionalities

Login/Enrollment process

There are three registration scenarios available for Priceless Specials:

Website registration path:

First, the Cardholder will be asked to go to the login page to enter PAN + DOB (verification option). Then the Verestro use the MRS API to determine the status of the card (getCustomerAccounts WS and getCustomerDetails WS).

If the card exists in the MRS API and has a status: (“Good-standing/Redeem Only”) then Verestro add it card to database and stores the AREF of card. Enrollment is not needed.

Cardholder additionally introduces data such as:

If the card does not exists in the MRS API then Verestro need to enroll the card using enroll WS. If the bank has 3DS enabled then the cardholder must pass the verification correctly. Then cardholder additionally introduces data such as:

MRS Data Mapping Elements:

Customer

Account:

Consents:

Rewards catalog

In order to retrieve information on Catalog, Verestro uses getRewardCatalog WS and getRewardItems WS which return a full listing of the rewards catalog for a given program of cardholder’s card.

Verestro displays different categories for Cardholder.

The following data will be received from MRS API response:

  1. rewardMatrixItemId – the internal MRS Matrix ID associated with the item,
  2. rewardItemShortDescription - The short description of the item,
  3. rewardItemLongDescription - The long description of the item,
  4. Image URL - The url that links to the item image,
  5. rewardMatrixItemPointValue – The point value of the reward item,
  6. shippingAddressSw – indicates whether or not a Shipping Address is required (e.g. physical or instant),
  7. redeemableItemSw – indicates if the Reward Item can be redeemed,
  8. physicalAddressRequiredSw – indicates whether or not the Reward Item will be shipped to a physical address,
  9. SingleQuantityRedemptionSw – indicates whether or not the Reward Item can only be redeemed with a quantity of one,
  10. emailAddressRequiredSw – indicates if an Email Address is required for the Reward Item when redeemed,
  11. orderInformation - the Shipping Message associated to the Reward Matrix Item’s Reward Category in the requested language,
  12. personalizationInformationSw,
  13. personalizationInformationLength,
  14. personalizationLabel.

The cardholder can choose to mark a specific reward as “selected”. Such a reward is displayed on the main page.

Points balance

To display the point balance information for registered cards, Verestro send separate (per each card) API request to MRS system via getPointDetails WS.

The cardholder receives points for making any transaction with the card. For making a transaction with a partner, relatively more.

Opt-out process

There are following possible options to opt-out from Priceless Specials Program:

Once Cardholder has requested to opt-out from the PS program, Verestro or Call Center needs to change the T&C for cardholder. During 30 day “grace period” cardholders continue to login to website, redeem points etc. – and can opt back in. Once 30 days have passed record is moved so cardholder no longer has access to account and website.

Benefits

Static benefits

Static benefits are a type of offers added and fully managed in CMS. Benefits are always active and their main goal is to display descriptions.

Travel tool

Travel Tool will be supported by existing Travel Tool vendor (Inspire). Online Travel to enable possibility to use the points on various travel selections (Hotel, Car Rental, Flight) and will be available for all new programs. 

Offers

RPM is using Personalized Card Links Offers (PCLO) to provide possibility for cardholders to accrue additional points per specific merchant offers.

 

Overview CZ/SK

Introduction

RPM is a paltform thet offers acces to loyalty services using various components.

The RPM consists of:

Main functionalities

Login/Enrollment process

There are three registration scenarios available for Priceless Specials:

Website registration path:

First, the Cardholder will be asked to go to the login page to enter PAN + DOB (verification option). Then the Verestro use the MRS API to determine the status of the card (getCustomerAccounts WS and getCustomerDetails WS).

If the card exists in the MRS API and has a status: (“Good-standing/Redeem Only”) then Verestro add it card to database and stores the AREF of card. Enrollment is not needed.

Cardholder additionally introduces data such as:

If the card does not exists in the MRS API then Verestro need to enroll the card using enroll WS. If the bank has 3DS enabled then the cardholder must pass the verification correctly. Then cardholder additionally introduces data such as:

MRS Data Mapping Elements:

Customer

Account:

Consents:

Rewards catalog

In order to retrieve information on Catalog, Verestro uses getRewardCatalog WS and getRewardItems WS which return a full listing of the rewards catalog for a given program of cardholder’s card.

Verestro displays different categories for Cardholder.

The following data will be received from MRS API response:

  1. rewardMatrixItemId – the internal MRS Matrix ID associated with the item,
  2. rewardItemShortDescription - The short description of the item,
  3. rewardItemLongDescription - The long description of the item,
  4. Image URL - The url that links to the item image,
  5. rewardMatrixItemPointValue – The point value of the reward item,
  6. shippingAddressSw – indicates whether or not a Shipping Address is required (e.g. physical or instant),
  7. redeemableItemSw – indicates if the Reward Item can be redeemed,
  8. physicalAddressRequiredSw – indicates whether or not the Reward Item will be shipped to a physical address,
  9. SingleQuantityRedemptionSw – indicates whether or not the Reward Item can only be redeemed with a quantity of one,
  10. emailAddressRequiredSw – indicates if an Email Address is required for the Reward Item when redeemed,
  11. orderInformation - the Shipping Message associated to the Reward Matrix Item’s Reward Category in the requested language,
  12. personalizationInformationSw,
  13. personalizationInformationLength,
  14. personalizationLabel.

The cardholder can choose to mark a specific reward as “selected”. Such a reward is displayed on the main page.

Points balance

To display the point balance information for registered cards, Verestro send separate (per each card) API request to MRS system via getPointDetails WS.

The cardholder receives points for making any transaction with the card. For making a transaction with a partner, relatively more.

Opt-out process

There are following possible options to opt-out from Priceless Specials Program:

Once Cardholder has requested to opt-out from the PS program, Verestro or Call Center needs to change the T&C for cardholder. During 30 day “grace period” cardholders continue to login to website, redeem points etc. – and can opt back in. Once 30 days have passed record is moved so cardholder no longer has access to account and website.

Benefits

Static benefits

Static benefits are a type of offers added and fully managed in CMS. Benefits are always active and their main goal is to display descriptions.

Offers

RPM is using Personalized Card Links Offers (PCLO) to provide possibility for cardholders to accrue additional points per specific merchant offers.

Cashback Offers

Cashback Offers are provided to users based on transactions made at participating merchants with Mastercard card and MRS points earned from this spend due to MRS Always-On Promotions  configured for all cards (except Business). Cashback means points that can be converted into money back collected/provided by the merchant on cardholder’s virtual account and can be later redeemed for specific catalog item or redeemed as cash. In addition to MRS Always-On Promotions the Program will have the PCLO offers configured per merchant to allow accruing additional points for user based on their transaction activity at these merchants. 

Generic offer refers to standalone MRS offer without matching with PCLO offer. It can be set-up separately in CMS. 

Household

Householding functionality enables consolidation of all cards of selected user (only within one program) or account. The household is allowed between different accounts of same user.

This can be achieved and set up in MRS via MRS APIs:

  1.  moveAccountToExistingHousehold WS – will allow to put one account under a HH of another account.
    • Request fields:
      • accountId - the MRS internal Account ID for the Customer's Account to be added to HH (can be extracted from getCustomerAccount WS, getPointDetails WS responses).
      • householdId     - unique ID for a Household in MRS, an internal value assigned to the household, when a Customer is enrolled; this will be the household that the account will be moved into (can be extracted from getCustomerAccount WS, getPointDetails WS responses).
    • Response field:
      • newHouseholdId - Unique ID for a Household in MRS; if successful, this will be the same householdId value that was specified in the request.
  2.  removeAccountFromHousehold WS – will allow to take out the account from HH;
    • Request fields:
      • accountId - the MRS internal Account ID for the Customer's Account to be removed from HH (can be extracted from getCustomerAccount WS, getPointDetails WS responses).
      • householdId     - unique ID for a Household in MRS, an internal value assigned to the household, when a Customer is enrolled; this will be the household that the account will need to be removed from (can be extracted from getCustomerAccount WS, getPointDetails WS responses).
    • Response field:
      • newHouseholdId - Unique ID for a Household in MRS; if successful, this will be the new householdId value that will be assigned for accountId removed.
  3.  updateHouseholdRole WS – will update the Role of account in HH (Primary Redeemer, Redeemer or Non-Redeemer, if applicable; by default – all Non-Redeemer Roles need to be updated with Redeemer by Verestro).
    • Request fields:
      • householdId    - unique ID for a Household in MRS; this is the household that will have its redeemer roles managed (can be extracted from getCustomerAccount WS, getPointDetails WS responses).
      • roleId    - a code that defines the Customer’s redeemer role, within the household. Valid values are:
        • P - Primary Redeemer,
        • R - Redeemer,
        • N - Non-Redeemer.
      • childCustomerId - the internal MRS Customer ID of the customer that is having their redeemer role updated.
    • Response field:
      • success - his field will contain “true” if the Redeemer Status update was successful or “false” if the Redeemer Status update was not successful.

Priceless Specials Webview

Overview

This documentation describe integration into Priceless Specials platform using few services provided by Verestro.

We should highlight few main products:

API Domain

All methods are available on below URL except initialization method.

Endpoint URLs:

Stage: https://rpm-management.upaidtest.pl/,

Prod: https://rpm.secure-verestro.com/.

Security and authentication

For backend-backend communication, it is required to attach appropriate certificates to the requests sent. This applies to:

Method issuer/initialize_sdk does not require certificate.

Certificate generation process.

First, the Partner needs generate a CSR (Certificate Signing Request).

The command to generate the CSR:

openssl req -new -newkey rsa:4096 -keyout client.key -out client.csr -nodes -subj '/CN=bankname cert/emailAddress=rpm@bankname.pl'

Once the CSR is generated, it should be passed to Verestro. Verestro will sign the CSR and provide x509 certificates based on it:

JWS tokens must have additional header:

Name

Description

x5c

Parameter contains the X.509 certificates chain (RFC7515#section-4.1.6)

PAN hash generating

PAN hash is an identifier in the Partner-Verestro communication and specifies the card for which the action should be performed.

It is used in:

PAN hash generation process:

Hash value is as SHA-256 HMAC, please see links below for more details:

RFC: https://tools.ietf.org/html/rfc4868#page-3,

Wiki: https://en.wikipedia.org/wiki/HMAC.

Test and prod value of key used to calculate HMAC will be delivered by Verestro at the later stage of integration process.

To validate your implementation please check plain and hashed values below:

Plaintext (HEX)

Hash

5555444433332222

4f64c445c859f7e53209e0091a5faef7e8b3ebbad899fbf8c74df09a6bfe5646

6984576897634895763948576

4b2eab65ab16183fa6ac8a8b12ad690890db98c5ce20e6d56aa037b723bbe84

someTestValue398048096859607

29596a78a7382e90159d8ec78a8d37baff57d05f676c0607dd7fb24b0396270ce

Registration flow

Registration method are used to add the user and his cards to the MRS system and create an account on the Priceless Spiecials platform. Registration is possible without providing an email address, in which case the user will have to verify it in first log in.

Card status

This endpoint returns information about card and consents status in MRS. If the card does not exist in the system, then the API returns: code 404.

Headers:

Name

Value

Accept

application/json

Content-Type

application/json

Request Details:

HTTP GET/company/card_agreements_status/{panHash}

Responses

Status, Body

Description

HTTP_200, SUCCES

{

  "termsAndCondition": true,

  "disclosureOfPersonalData": true,

  "processingPersonalData": true,

  "marketingInfoEmail": true,

  "marketingInfoPhone": true,

  "errorMessage": null

}

Success.

HTTP_200, SUCCESS

{

  "termsAndCondition": null,

  "disclosureOfPersonalData": null,

  "processingPersonalData": null,

  "marketingInfoEmail": null,

  "marketingInfoPhone": null,

  "errorMessage": "CARD_IS_INACTIVE"

}

Card is inactive in MRS System.

HTTP_200, SUCCES

{

  "termsAndCondition": true,

  "disclosureOfPersonalData": true,

  "processingPersonalData": true,

  "marketingInfoEmail": true,

  "marketingInfoPhone": true,

  "errorMessage": "USER_EMAIL_NOT_VERIFIED"

}

User didn’t confirm email address.

HTTP_404

The card does not exist in system.

Add User with Cards

Supported methods

User add - POST company/enroll.

Data structure

For POST methods request body should contain JSON with combination of objects mentioned below.

Request

Field

Required

Type

Additional information

requestId

No

String

External User Identifier provided by client. It can be used as an identifier in system (in standard UUID4).

firstName

Yes

String


lastName

Yes

String


phoneNumber

No

String

Should be passed with prefix.

email

No

String


zipCode

No, recommended

String, optional

format: NN-NNN.

birthDate

No, recommended

String, optional

format: YYYY-MM-DD.

cards

Yes

Array

Array of Card Objects.


encryptedNumberCard


Yes

String

Encrypted PAN JWE.


programId

No

String



programIdentifier

No

String



termsAndCondition


Yes

Boolean

true or false.


disclosureOfPersonalData


Yes

Boolean

true or false.


processingPersonalData

Yes

Boolean

true or false.


marketingInfoEmail


Yes

Boolean

true or false.


marketingInfoPhone


Yes

Boolean

true or false.

Example:

{
   "requestId":"123e4567-e89b-12d3-a456-426614174000",
   "firstName":"John",
   "lastName":"Smith",
   "phoneNumber":"+48777666555",
   "email":"john.smith@gmail.com",
   "zipCode":"25-345",
   "birthDate":"1998-12-12",
   "cards":[
      {  
        "encryptedNumberCard":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJlbmNyeXB0ZWROdW1iZXJDYXJkIjoiNTEzODQzMDMxMjA0MjA0MCJ9",
         "programId":345353,
         "termsAndCondition":true,
         "disclosureOfPersonalData":true,
         "processingPersonalData":true,
         "marketingInfoEmail":true,
         "marketingInfoPhone":true
      }
   ]
}

Responses for Partners that use PAN (primary account number) as BCN (bank customer number)

Status, Body

Description

HTTP_201, SUCCESS

Success (email/userId passed in a request).


HTTP_201, SUCCESS

{
 ”requestId”: "123e4567-e89b-12d3-a456-426614174000"

}

Success (email/userId passed in a request).

requestid returned to add new cards if user does not verify email address.

HTTP_201, SUCCESS

{

  "requestId": "123e4567-e89b-12d3-a456-426614174000",

  "failedPanHashes": [

    {

      "panHash": "a7a89543br958437543bf984375bc3498nvuiey74783"

    }

  ]

}

Passed card/cards failed during adding to MRS system.


HTTP_400: CARD_ALREADY_EXIST

{

  "failedPanHashes": [

    {

      "panHash": "a7a89543br958437543bf984375bc3498nvuiey74783"

    }

  ]

}

Passed value is not unique in system.

HTTP_400:  INVALID_VALUE_CARD

Passed Card value is invalid.

HTTP_400:  INVALID_VALUE_EMAIL

Passed email is invalid.

HTTP_400:  INVALID_VALUE_BIRTH_DATE

Passed Birth date is invalid.

HTTP_400: CARDS_LIMIT_EXCEEDED


Too many passed Cards. Limit 10 cards.

HTTP_403: ACCESS_DENIED


Method is not available.

HTTP_401: INVALID_CERTIFICATE


Passed certificate is invalid.

Responses for banks that use clientId as BCN (bank customer number)

Status, Body

Description

HTTP_201, SUCCESS

{

“clientId”: “PXPYVJ2HZTW0CK0G4840K4WGGOWOKO”

}

Success (email/userId passed in a request).


HTTP_201, SUCCESS

{
“clientId”:“PXPYVJ2HZTW0CK0G4840K4WGGOWOKO”,

”requestId”: "123e4567-e89b-12d3-a456-426614174000"

}

Success (email/userId passed in a request).

requestid returned to add new cards if user does not verify email address.

HTTP_201, SUCCESS

{

  "clientId":"PXPYVJ2HZTW0CK0G4840K4WGGOWOKO ",

  "requestId": "123e4567-e89b-12d3-a456-426614174000",

  "failedPanHashes": [

    {

      "panHash": "a7a89543br958437543bf984375bc3498nvuiey74783"

    }

  ]

}

Passed card/cards failed during adding to MRS system.


HTTP_400: CARD_ALREADY_EXIST

{

  "failedPanHashes": [

    {

      "panHash": "a7a89543br958437543bf984375bc3498nvuiey74783"

    }

  ]

}

Passed value is not unique in system.

HTTP_400:  INVALID_VALUE_CARD

Passed Card value is invalid.

HTTP_400:  INVALID_VALUE_EMAIL

Passed email is invalid.

HTTP_400:  INVALID_VALUE_BIRTH_DATE

Passed Birth date is invalid.

HTTP_400: CARDS_LIMIT_EXCEEDED

Too many passed Cards. Limit 10 cards.

HTTP_403: ACCESS_DENIED

Method is not available.

HTTP_401: INVALID_CERTIFICATE

Passed certificate is invalid.

Add Card to existing account

Supported methods

User add - POST company/add_card.

Data structure

For POST methods request body should contain JSON with combination of objects mentioned below.

Request

Field

Required

Type

Additional information

email

No

String

Email or userId is mandatory.

userId

No

String

Email or userId is mandatory.

cards

Yes

Array

Array of Card Objects.


encryptedNumberCard


Yes

Sting

Encrypted PAN JWE.


programId

No

String



programIdentifier

No

String



termsAndCondition


Yes

Boolean

true or false.


disclosureOfPersonalData


Yes

Boolean

true or false.


processingPersonalData

Yes

Boolean

true or false.


marketingInfoEmail


Yes

Boolean

true or false.


marketingInfoPhone


Yes

Boolean

true or false.

Example:

{
   "email":"john.smith@gmail.com",
   "cards":[
      {
		 "encryptedNumberCard":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJlbmNyeXB0ZWROdW1iZXJDYXJkIjoiNTEzODQzMDMxMjA0MjA0MCJ9",
         "programId":345353,
         "termsAndCondition":true,
         "disclosureOfPersonalData":true,
         "processingPersonalData":true,
         "marketingInfoEmail":true,
         "marketingInfoPhone":true
      }
   ]
}

Responses for banks that use PAN (primary account number) as BCN (bank customer number)

Status, Body

Description

HTTP_201, SUCCES

Success.

HTTP_201, SUCCESS

{

  "failedPanHashes": [

    {

      "panHash": "a7a89543br958437543bf984375bc3498nvuiey74783"

    }

  ]

}

Passed card/cards failed during adding to MRS system.


HTTP_400: CARD_ALREADY_EXIST

{

  "failedPanHashes": [

    {

      "panHash": "a7a89543br958437543bf984375bc3498nvuiey74783"

    }

  ]

}

Passed value is not unique in system.

Request is rejected, no cards have been added to the system.

HTTP_400:  INVALID_VALUE_CARD

Passed Card value is invalid.

HTTP_400:  INVALID_VALUE_EMAIL

Passed email is invalid.

HTTP_400:  INVALID_VALUE_USERID

Passed userId is invalid

HTTP_400: CARDS_LIMIT_EXCEEDED


Too many passed Cards. Limit 10 cards.

HTTP_403: ACCESS_DENIED


Method is not available.

HTTP_401: INVALID_CERTIFICATE


Passed certificate is invalid.

Responses for banks that use clientId as BCN (bank customer number)

Status, Body

Description

HTTP_200, SUCCES

{

“clientId” : “asdh-adss-sada-sadss”

}

Success.

HTTP_200, SUCCESS

{

  "clientId": "asdh-adss-sada-sadss",

  "failedPanHashes": [

    {

      "panHash": "a7a89543br958437543bf984375bc3498nvuiey74783"

    }

  ]

}

Passed card/cards failed during adding to MRS system.


HTTP_400: CARD_ALREADY_EXIST

{

  "failedPanHashes": [

    {

      "panHash": "a7a89543br958437543bf984375bc3498nvuiey74783"

    }

  ]

}

Passed value is not unique in system.

Request is rejected, no cards have been added to the system.

HTTP_400:  INVALID_VALUE_CARD

Passed Card value is invalid.

HTTP_400:  INVALID_VALUE_EMAIL

Passed email is invalid.

HTTP_400:  INVALID_VALUE_USERID

Passed userId is invalid

HTTP_400: CARDS_LIMIT_EXCEEDED


Too many passed Cards. Limit 10 cards.

HTTP_403: ACCESS_DENIED


Method is not available.

HTTP_401: INVALID_CERTIFICATE


Passed certificate is invalid.

Download key to encrypt PAN

Supported methods

Download key – HTTP GET /company/enrollment/public_key.

Data structure

Body of this method should be empty.

Responses

Status, Body

Description

HTTP_200, SUCCESS

{

”publicKey” :  "LS0tLS1CRUdJTiBQVUJMSUMgS0VZLS0tLS0KTUlJQ0lqQU5CZ2txaGtpRzl3MEJBUUVGQUFPQ0FnOEFNSUlDQ2dLQ0FnRUFwTS9IamdEZHlXUXVVRWhRNkV2MgpHVGx5SnlrcHBUdU1jODFxTSt1Mm03ZDFVdnpHNXdUT1k3OVZVWGdDdFBJMkNXZ05BcXo0aGk4Ymp4WjhOSi9UCjRoMzhya2xoSWh2anJqQ0w0NUlESUVqOTlmREt1R1IySzBkQlY4eDhjT2drL09jaUhqblFTVytoL05RTFRpTHIKTHkzbzV0dDhOaVNvWVJuTjlmZEo3cytaRjdFdU1kMkhuMm1iSkVOS2MwYXRXekZtZkFQbnM4SmRVWWdNWWQxSgpsbll0cXdXVWdGYUxnVUplaDhyZGRrd3lqeHdUZVZ5M0lFQ1hYMHNMcWIwTTZ2NURFWGk5Y1ZVV09PT0FUSG1pCng0a2dreUNESG9uN3FZNjFaZEhQdVlSOFRDbXoxaW9sOGpLNkJZTUdlZjFsb01Qem9XVTVPeHFRTjVCMUJrdVMKOWJJUFZTZFlUYTdRanB5aGRHbGhSeWRrNFNVYmFTR2d2cXc1N01VRXJkZ2NKOW4rV2hPNUorc0VOclpOSFZhdQo1czlCaytiRlZuQXltZEtldEdQZzVtZC94Ulo0NzVwQ1FPVXR5UUErNnduSitONTlWZlJnTlNvaDhKK2lnYkhRCmJ2YTNqcjFqKzA1dkw1V1JhNnR1SzRoeTBQQ29JRUtYZGNUTk1uZjdDa3dVUlFsaTlVdEJqOVo5bHozL0VBTy8KWll5cnlxOWJqN0J0cTRMU0llNFR2K2c2NDg4bXVXMENnSGlQRDJGV3NsWUdMcGQ2V3JvQlR0ZCtCajhhUk5jMQo5YXFmcE1DTmZBdUJIMm5Lc1ZITkxJRnlrbEY3TktVVGRxcm8vcnBKUEFidFJJb0YvK3JtcUtHUVh2L0duSWQyCjN3SzNhMDUrNnZZeXhmcXNldUtUWGNNQ0F3RUFBUT09Ci0tLS0tRU5EIFBVQkxJQyBLRVktLS0tLQo="

}

Success. Base 64 encrypted.

Connection to SDK and widgets

Initialization

To connect you need to send HTTP POST request to /initialize_sdk endpoint with required parameters. To choose what front-end way want to load, you need to provide widget_type parameter that determines also required parameters.

You can also add the parameter “redirect”: false, which is optional – the default value is true. That causes that you are not redirected, but you receive a response 201 with the body (in this case, you have to redirect manually):

{

  "redirectUrl": "https://something.com"

}

Endpoint URLs:

Stage: https://rpm.upaidtest.pl/issuer,

Prod: https://rpm.upaid.pl/issuer.

Headers:

Name

Value

Accept

application/json

Content-Type

application/json

cURL example:

curl -X POST "http://rpm.upaidtest.pl/issuer/initialize_sdk" -H "Accept: application/json" -H "Content-Type: application/json" -d "{ \"initializeSDKToken\": \"eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ0cnVzdGVkSWRlbnRpdHlUb2tlbiI6ImV5SmhiR2NpT2lKU1V6STFOaUlzSW5nMVl5STZXeUpOU1VsRk4zcERRMEYwWTBORFVVUkpiR1ZOYkVwS09FVnpWRUZPUW1kcmNXaHJhVWM1ZHpCQ1FWRnpSa0ZFUW1KTlVYTjNRMUZaUkZaUlVVZEZkMHBSVkVSRlZVMUNTVWRCTVZWRlEwRjNUR0pYUmpaaU0yUndXbGRPY21GWFZYaEZWRUZRUW1kT1ZrSkJZMDFEUm1Sb1kyNU9ObGxZWkdoTlVUUjNSRUZaUkZaUlVVdEVRVlpXWTBkR2NGcEVSVlJOUWtWSFFURlZSVU4zZDB0VFZsRm5WVzA1ZG1SRFFrUlJWRUZsUm5jd2VVMUVRVEJOYWtsNFRrUkJNRTVVWkdGR2R6QXdUVVJCTUUxVVkzaE9SRUV3VGxSa1lVMUNaM2hHYWtGVlFtZE9Wa0pCVFUxRVZsWlJVVlZzUlV4V1FrSlZiRkpQVWxaSmQyZG5TV2xOUVRCSFExTnhSMU5KWWpORVVVVkNRVkZWUVVFMFNVTkVkMEYzWjJkSlMwRnZTVU5CVVVSS2RXcHJTa0p2WjFoR1NFbHFVSEZEVUhGclRtY3ZRbnB1TkRWVFZIaFFTVFoyVm5kdk1YSktkV2cxT0RoT1RqZGxNa2cxT1dVNVRWUkNUbXRpWVRJMFFuUjZhMlJUY1U5VVJuZFhZV0pZTlVvclYyMW1UbnBuU3pkV1UwZG5TMDlYTVRBMVowZDNUM1pQV1RKcFUwSlhka3BDVTNKRlZuTkNhVWhuY1U0NVZtcDBVMWt5YTBZNGFFeHRRM1F6U21Odk1YVjBRVTF5UzB4SVUxRlNUbkV2VVhGbmVXWnZOVXRpVXpkT2R6YzJTblJTT0V4QmRsWndTUzhyVDI1bmRUWkhVblJIZDBNemRUTnhia05qZVZKU055dDVNSHBKUm5waU1YSm5SV3hNVkVzNFJXWjJVMlo2WW1NMVdFOXhUMjF3WkdjMUwzVlNTRXA1U25aRFQwTk9jRVp2V0M5YVNIaHpWMmR1TmtweFlqQk9SVXRtY21WcmFERlRNbGRVYkhSRWQwaGlhR0pNZDBOb05HVXlhMDU0TDFaeUwwbFNaRFp3TlhGQmRpdHVZMVl4YVZwVWJXcENRMlZ4Y0hwUk5XczFSalJLVlcxb2RrdzFRVzFPY1d0b01GRkVaR1ZvYTNKc1YwNU5RM0JXZVZCaGJFRlJWWGd5VmxaWFNsRjJSMHcwWlZCUmIxUmhSVkk1VDJ4YVlVZFZaV0psZGxFM2RrMXBTRXRaWmpCV05Hb3lPWGM0WmxSNFNXMUtTREJLTTJOSlEwaHZiVU00Y2xoMlpHWjZRVzlyWVdOT1QwTlJPV2w0WldGaWREY3ZTMjFYVkhkYWRHWllUamxwYXpSRVFUZExVbkprSzFWU1VHbzFkRkJaV21WQ2FIaGhlVTF0ZVc0dlNsUlRaVVZYS3l0WGNXeGhSR3gxVUd0MFdrbEpNVzEwTVhCVWMxVlBjekpwZURoa2VuQjBNMUkzYTBNNVJIVjBUVWxhU0VVMU4ycGtSV0YxTm1SWE4zUklhMGRGUjFWUlNtaHZjbkZpVVdaNVFYbGxNMkZGTUdKalozUnBWV3R0VlM4elMwRjVXRzU0ZG14d1prZGxTaTkwYmpGTmNVbHhXR2x1YUhCQk1UUk9haTh5YVRBM05XYzJVSEF2Ym5KVVQyRkNjRmdyU3paMGNGUlFjemRaYUc1SVNIUnhSRE5CTUdsdmMyWjROWFZ0VVVsRVFWRkJRazFCTUVkRFUzRkhVMGxpTTBSUlJVSkRkMVZCUVRSSlEwRlJRbXRsUWxVNE5tZERXbkp2TUM5b1dIUk9RUzlQYTFSdFZWWm9ObWh5WmxNck5tUlFOME12VG1wd1FXRmplR3BQWmtFdkx6Umlja3BLUVhGcU4wbElNVGxPWTJabVQwVkdNVTByYzI1TWJHWldOMU50T1RSblJ6WjNaRGc1U0RWUE9UZzNOVXA1ZUd4dmFXSk5UemN6TTNsVmIwWk5XVXN6VjJWTFIzaEJaekZhYjBGSVlXRTFNMlJ5VEU5bVQwYzJOMjlDWjNKME1EUnllSFZzZVZCcFZXbHFjemxMYzBzM1RVNXBNbFpSUlRKRVZXWmpRWE5xSzI1ak1WTjVXa3hCUVZoWFRtSTRiV2RPYm5aUVdVSnlaRFk1Wm1KblpuVTFjVXRPTmk5cGVWSTRPVVJyVVd0WE1YTjJjWE56YWtnM1IxcFFRbTV0UkN0eVlrSldWMkozTTB0M1NqSjFTR1pVZDNkNVVtTXdaRmxpWkRkM1l6TmtOVVZEUjBOemFVbHNSa2RrVTNWVUsyaE1WazVVU21GVFNWZHFhVzVoV1RWYU9WVlBTMk12ZWtSMU1IUlpPVVIyV0ZWcWJVeExlamhsZDB0dVR6RjZSVWN4ZVVSUlQwOWpVRXBuYjJwU2FrOXBRa1l5V0dzNGVtazNjMFp0VWpkeE9HWkVkR3hDZGxob09IaFhjWEIwZVhKUVlVZElhMWhMV2xsUVNuSXliRll3UjBKaE5pdHRUVWhqWkdaSVVXTkpTQzlhS3poU2JEbDVUemx1ZEdGd2VGWnNlVVpuYVdGbk9WWmpVa1JTYmsxeE5GRm1ia1JOV1VSWlEzcERRV1pQT0VwYWNXZG1iVzlXUldWNVV6RmxPSFpaWlhGc2VFa3ZjbmR5TjAxd2RYTXplblZYWmtablNUVldiMEpJY20xNWIwNTRkMkppVWxCdVQxY3hibWxVU2tRNWRFRldUemw2U0ZVM1pIbE5WbHBETkhKc2RIVTNjRU4xUnk5RldtczVOMjQyV2xwTlRVbzJNbU00WjJwUlpIbHVRMk4xUm1OdU5FWXlURVpUT1doelltZFpMMFpRTnpKSWMwazBPR1o2WkcxemNtVnJjMHhwTjBRekswTmhlRzF6WlhoTGFWZDZSakYwUWxnMk5GWjFWMGc1VEdoWGMybDFMM0JJT1ZkUmQwSldNWHBJTW5vclpIVlhaemgzS3pOaWVUVm5QVDBpWFgwLlcxMC5DblRISmpoRkRCekhYY0I3TjZsNFMtMS02Wk9TVngzc1hsRkg4TnV0T3dVY2p0Zmk4VE01SUtSaFlGMElFVWFDTjAxU1hHdGdzY3VJOGZ3ampPVVNleW5Ub1lhN2xRXzB4aHF1V0Y2aWZBNnRBTFBWVDFZa0VoaHRTT293Y3hWUVc1aF9yRU9QbmxLWmFTR2QzQ21WdU02dkdodFVsdWh5UXpRakloTFhTaHBpQllPLThSaG14dnI2Ykc5QXA3WVlyRGV5YWg0clY2T1F0ek9GNkhONUM4ZUFlYmRvMVExcVQxQ2pUWUVTQVR4NElmREpfRVhLejg4ZE1aWEV1Nk5ZWXEwZ0RGbGpqa3VIMUxCTzlDb2ZRbDY4NGpJSkFpeDFTVFVoS3R1M0Z5RWt0Uy1Wd05jMWZBb3RLZEV2VkxNZ0o5ZEpmSFdOempoNEVrSlVxU1ltTE45OHVBNklYSnhONk0wLURoUW0yNW83M3Q2Y19ZZjEwbXhvWDFIRFFsZGk5WXI3c1NaMGVRSy1Oc2F6MjlSMkxZMHhNMnFneVBnRUlCZFp6TE95M0JJbmw3NF9yeU5VSHFwWF9oUk9Md2JpUW5CLUVjT1ZWVnQ4SzZ4bDBmRDM4YU5IaGVJUVd3TjJhbmFWUFNsNXZkalF0R2tuUThFV3Y3bHZ1d0xSUThuSlp4Ukg0akdnMjRBV1hLY1BsNDJyejhWLWJSQmNhcVpIMDFPMjJ1OEFOaXN1MDlTSXY0aGFtekdFaklEVERjNGR5VUNTRTk0bmlqU0NadkRUVXY3RFEzd0dUaVJzZ1BJSjExOHpueS1EZk9xaDVSWHcxUS1LVzBSd3lkZFVsM3dlX1VjcEM0TkdWYkwzWFIwTDFqVHVIWWJYZkh2aTlMd1k2RlJYU2tEN2VtcyIsInBhbkhhc2giOiJhNjU4ODM1ZDEwZWVjMTQ3YjJiNDFhMWYwZmJiMjg0YWNkMjZiZTExZTkzYmQwNTVkYWQwZTQ1MzE5NWViNjhiIiwib3MiOiJ3aW5kb3dzIiwiZGV2aWNlSWQiOiJjdXN0b21lci1pZC0yMDAwIiwicmV0dXJuVXJsIjoiaHR0cDovL3d3dy5leGFtcGxlLmNvbS9yZXR1cm4iLCJrZWVwU2Vzc2lvblVybCI6Imh0dHA6Ly93d3cuZXhhbXBsZS5jb20va2VlcF9zZXNzaW9uX2hhc2giLCJ3aWRnZXRUeXBlIjoiZnVsbCIsImNvbXBhbnlJZCI6InRlc3RJc3N1ZXIiLCJleHAiOiIxNjEwOTY5MjczOTE0In0.R-BGPxI_zaVs20eISQVgxtBLeDZkI0mAFvQSRLAISb8\"}"

Parameters:

Name

Required

Type

Description

initializeSDKToken

yes

string

JWT token signed by private key delivered by Partner.

redirect

no

bool

The default is redirect true. When you set it as false, you will receive a response 201.

Token payload data:

Name

Required

Type

Description

trustedIdentityToken

yes

string

Trusted identity token.

panHash

yes

string

PAN hash – described in 3.2.

deviceId

yes

string

Unique ID of device. Base64 encoded. It is a string of numbers and letters that identifies every individual device. It is generated on the device and can be retrieved by any app session with the same way. It should be generated with various parameters like, serial number, os version, screen information, device build, device number, battery information, so it can provide uniquity from each device.

os

yes

string

One of: "android", "ios", "linux", "macos", "windows".

publicKey

no

string

This is public key from device biometrics authentication module. Base64 encoded.

returnUrl

yes – for WEB integration

string

Url which will allow to return form RPM to External Issuer System. Recommended in web integration.

errorUrl

no

string

Url which will allow to redirect, in case of any errors. Recommended in web integration.

Planned for the future.

logOutUrl

no

string

Url which will be triggered when log out will appear. Recommended in web integration. If this parameter is not present, user will set default login page of program!

Planned for the future.

keepSessionUrl

yes – for WEB integration

string

Value signed by EIS, it allows RPM to periodically extend user session in EIS. EIS should be able to validate if it is properly sign with their key.

widgetType

yes

string

One of: "full", "goal". Default: "goal".

This value tells which frontend should be loaded.

"full" - Full SDK will be loaded, that allows you to use all functionalities.

"goal" - Selected goal widget will be loaded.

companyId

yes

string

For example: “citi”.

exp

yes

String

Expiration time (seconds since unix epoch).

additionalItems

no

array

Additional items for the particular cardholder.

The additional Items is an array of objects:

Name

Required

Type

Description

id

yes

string

The ID of selected item type. (From GET /company/available_item_types).

count

optional

int

The count, default: 1.

Goal Widget communication

Initialization                                                      

To initialize Priceless Specials web SDK within mobile application, it is required to make POST request to RPM backend (API) with parameters (section 3.3). Make sure that parameter widget_type is set to "goal".

Example POST request body:

{       

initializeSDKToken: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6InRlc3QiLCJpYXQiOjE1MTYyMzkwMjJ9.tRF6jrkFnCfv6ksyU-JwVq0xsW3SR3y5cNueSTdHdAg

}

JavaScript events for mobile applications

For getting proper messages on error or session expiration from widget you need to implement:

Android

Android.showMessage(message);

 Android developers must binding javascript code to android code using @JavascriptInterface annotation. More info here.

iOS

window.webkit.messageHandlers.payment.postMessage({ status: message });

More info here.

Partner can react on those in various ways that suits given use case or interface.

Events list

There are some rare cases that error will occur, here are list of most common:

WEB application

If there is an error, and returnUrl is set, app will redirect to returnUrl so partner can react.

If there is no returnUrl, error page will be displayed.

Initialization of Priceless Specials Webview

Solution is prepared to open in webview and should be implemented in a way, where no iframe is used at all!

Please make sure support for local storage and cookies is enabled.

Base flow:

Native SDK opens Priceless Specials Webview by POST request, like described below.

To initialize Priceless Specials Webview within mobile application, it is required to make POST request to RPM backend (API) with parameters (section 3.3). Make sure that parameter widgetType is set to "full".

Example POST request body:

{       

initializeSDKToken: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6InRlc3QiLCJpYXQiOjE1MTYyMzkwMjJ9.tRF6jrkFnCfv6ksyU-JwVq0xsW3SR3y5cNueSTdHdAg

}

Partner will perform POST action /initialize_sdk with parameters as described above.

It will trigger communication between WEB APP and RPM API to log in user by provided trusted identity. 

Closing of the session

Integration with Web application

In this type, if parameter returnUrl is present, in GUI customer will see button to go   back, and will be redirected to returnUrl.

Integration with Mobile application

In mobile integration, parent mobile app can close web view at any time, but in case of some errors or loosing session, WEB APP will trigger JavaScript events to inform webview about it.

Session support mechanism

Only for WEB flow!

Partner should share endpoint, that will allow to extend user session, so if user will come back to issuer service, it should be still logged in.

This endpoint should be able to validate, if it is secure to extend user session, so keepSessionUrl should be signed by issuer.

WEB APP will periodically call this endpoint (Request GET) to avoid session timeout on issuer side.  After user decide to return, WEB APP will log user out and redirect to partner site (returnUrl).

SDK Customization

Font styles and colors

Priceless Specials SDK allows to customize some parts of application layout:

Card selection screen

During the integration process, the partner may choose to enable/disable the card selection screen.

This functionality is enabled by default.

Additional API endpoints

Endpoints that are not required. They are used to get additional information from the system via the API and allow additional functionalities.

The more information about API specifications is here.

Enrollment Widget

This document is intended for Mastercard partners willing to integrate their mobile applications or website solutions with Mastercard Reward System using Enrollment Website/Widget tool provided by Verestro.

The document is designed to cover the following fundamentals:

Abbreviations:

AES – Advanced Encryption Standard ,

API – Application Programming Interface,

MRS - The Mastercard Rewards System - the platform from Mastercard dedicated to deliver loyalty solutions for customers,

PCI DSS - Payment Card Industry Data Security Standard.

Overview

Online Enrollment Capability (Enrollment Website/Widget) is a tool that can be integrated with Merchants, Issuers or other Clients and allows secure registration of cardholder PAN (and PII data, if applicable) into the MRS system. In addition to card enrollment (and PII, if applicable) into MRS, it also allows to perform certain  card management activities (optional), including unenrollment and card replacements.

The Enrollment Capability (Enrollment Website/Widget) designed by Verestro supports all key web-browsers (see further in the document) and has mobile responsive design, as well as can be embedded into mobile applications (WebView). Also, it can be customized & localized per specific Client/Country (with unique URL) and enabled upon specific request from Mastercard.

Verestro is using MRS API v.2.0 to facilitate operation of Enrollment Capability (Enrollment Website/Widget). The Enrollment Capability will be hosted in Poland (EU) in Verestro PCI DSS certified environment (hosting center).

Limited PII data elements, stored in Verestro database are encrypted using AES 256 encryption standard. PAN is not stored in Verestro database at any time.

High Level Description of Flow and Requirements

Enrollment

Initialization Process

In order to start using Verestro solution, each Client is required to be setup in the Verestro back-end system. The Client setup process includes assignment of unique Client ID, Program ID, and Security Key exchange process.

In order to initialize Enrollment Website/Widget capability, Client will be required to trigger a dedicated URL provided by Verestro with parameters included into signed request described in 3.2 “Initialization process” (HTTP POST action /company/non_auth_initialize request with JWT token (RFC 7519) which contains valid payload data). For any new registration, payload should contain valid actionCode parameter that is equal to “N” value for new customer/card enrollments.

Please note – Client is required to authenticate/verify the customer and submit valid Customer ID in the initialization request to Verestro. If the Client does not provide Customer ID during the initialization of enrollment, Verestro will generate a Customer ID on behalf of the Client. In such case, Verestro will provide back to the Client the assigned Customer ID value and will display assigned value to the customer. The Customer ID enables further card management purposes such as e.g. opt-out) but is not a default option and will require additional security measures on Verestro side (including Re-captcha and/or 3DS process).

Upon successful validation on Verestro side, the Website/Widget is displayed, where user can enter the following data:

The PAN during customer’s input in Website/Widget is validated using Luhn algorithm in real-time (in the browser). If successful Luhn check is passed in the browser, Verestro will encrypt the PAN using MC public key (see full process in section Security 3.3) and will pass the encrypted card information into MRS. After successful MRS enrollment, MRS will supply back to Verestro successful enrollment notification with Account Ref ID or RANAC (unique ID assigned by MRS per card) for further card management activities.

In addition, Verestro will be required to immediately feedback the enrollment result with assigned values to the Client (Customer ID, Account Ref ID or RANAC, additional values if required). Partner can use the one of initialization parameters (ranac_url) to send a specific endpoint to which Verestro will send RANAC after successful enrollment.

3DS authentication (optional)

Optionally, Verestro allows to trigger 3DS 2.0 authentication after submission of the registration data. If the card authentication is successful, the card enroll is performed into MRS.

This case must enable the decryption of the card on the API side.

Un-Enrollment User Flow

In order to initialize the Enrollment Website/Widget to execute un-enrollment, Client will be required to trigger dedicated URL provided by Verestro with required parameters included into signed request described in 3.2 “Initialization process”. In this case actionCode parameter should contain “C” value and Customer ID value is always required.

Verestro system will perform a search of Account Ref ID or RANAC assigned to Customer ID in Verestro database (decrypt stored values) and will trigger updateCustomerAccount MRS API with “CANCELLED” status. Upon successful un-enrollment in MRS, Verestro will immediately feedback the result of un-enrollment to the Client.

After X days from the status change to Canceled, the record with the any associated PII data (including Customer ID, Account Ref ID or RANAC, others) will be completely removed (deleted) from Verestro database. Please note – if there are multiple cards under single Customer ID, Verestro will be required to search Account Ref ID or RANAC having last 4 digits of card to perform card un-enrollment under associated Customer ID (only Account Ref ID or RANAC will be purged upon cancelation of card).

X – it is parameter configurable per Client/Program (e.g. 30 days).

Replacement User Flow

In order to initialize the Enrollment Website/Widget to execute replacement, Client will be required to trigger dedicated URL provided by Verestro with required parameters included into signed request described in 3.2 “Initialization process”. In this case actionCode parameter should contain “R” value and Customer ID is always required.Verestro system finds the cards assigned to this Customer ID in Verestro database and display the cards list in the following format:

- 1234 XXXX XXXX 1234

User can select the card he wants to replace and enters a new PAN.

Upon selection of card to replace, Verestro will propose to enter a new PAN. Verestro will capture & validate a new card number (in browser) and will trigger the new card enrollment into MRS (2.1 Enrollment). Upon successful enrollment of the new card, the cancelation of the old card will be triggered by Verestro into MRS (sequence will be followed). If by any reason, the card enrollment of the new card is not successful, Verestro will not delete the old card and will inform Client about the unsuccessful replacement attempt.

Verestro will immediately feedback the results of replacement including Customer ID, new Account Ref ID or RANAC (additional data if any) to the Client and confirm the successful replacement of old card.

After X days from the replacement, the record with the any associated PII data (including Customer ID, Account Ref ID or RANAC, others) will be completely removed (deleted) from Verestro database. X – it is parameter configurable per Client/Program (e.g. 30 days).

Widget Customization & Localization

Some parts of Enrollment Capability (Enrollment Website/Widget) can be customized per each integrating partner:

Supported format is: PNG. Supported proportion is 21:9 with transparent background. Minimum height is 100px.

Supported format is: PNG Supported resolution is: Full HD (1920px x 1080px)

The client will receive a translation file in JSON format, example below.

{

   "register":{
      "header":"Mastercard - Rewards",
      "tittle":"Registration",
      "accept_terms":"Accept Terms&Conditions",
      "userData":{
         "card_number":"Your card number",
         "first_name":"First name",
         "last_name":"Last name",
         "email":"E-mail"
      },
      "optional":"optional",
      "confirm":"Confirm"
   },
   "error":{
      "title":"Something went wrong...",
      "info_first_part":"Your card does not belong to the program. Read more about how to join the program.",
      "info_second_part":"Incident identifier: "
   },
   "success":{
      "title":"Success!",
      "info":"Your card has been attached to the program."
   },
   "read_more":"Read more"
}