Digital Stamp

Objects

Digital stamp card object

Attribute	Description
stampCardId	Unique identifier of the stamp card e.g. 0616DE94-DED7-4D51-B766-2203296654FB
name	Name of the stamp card e.g. Burger King Alpharetta
stampType	Unique identifier of the merchant who issued the membership card. Possible values are - QR: QR Code - NFC: NFC Tag - STAMP: Physical Stamp e.g. QR
stampCount	Number of stamps available in the stamp card. e.g. 5
tnc	Terms and conditions of stamp card program
availableStore	Short description of available store(s) e.g. all gap store
websiteUrl	http://www.google.com
phoneNumber	Customer care phone number e.g. 456-494-4564
information	Detail of the stamp, how to use, etc. e.g. One free beverage after 10 stamps
isPublishToMarket	To publish this stamp card to digital stamp marketplace. Possible values are - Y: This stamp card is published in the digital stamp marketplace. - N: This stamp card is not published in the digital stamp marketplace. e.g. Y
backgroundImageUrl	URL of background image of the stamp card e.g. http://api-dev.fintiv.co:8080/image/stampcard/0616DE94-DED7-4D51-B766-2203296654FB_bg_xhdpi.png
stampAreaImageUrl	URL of stamp image on the stamp card. e.g. http://api-dev.fintiv.co:8080/image/stampcard/0616DE94-DED7-4D51-B766-2203296654FB_stamp_xhdpi.png
rewards	List of rewards associated with the stamp card. See reward object.
merchant	List of merchants associated with the stamp card. See merchant object.
stampStartDate	Start date of the stamp card valid period. Format is yyyy-MM-dd’T’HH:mm:ss.SZ e.g. “2019-02-08T14:23:35.443-0500” yyyy: Year, e.g. 1996 <br>MM: Month in year, e.g. 07 dd: day in month, e.g. 10 HH:hour in day(0-23), e.g.0 mm:Minute in hour, e.g. 30 ss: Second in minute, e.g. 50 S: Millisecond in the minute, e.g. 443 Z: Timezone offset in hours(RFC 822 pattern), e.g. -0800
stampEndDate	End date of the stamp card valid period. Format is yyyy-MM-dd’T’HH:mm:ss.SZ e.g. “2019-02-08T14:23:35.443-0500” yyyy: Year, e.g. 1996 <br>MM: Month in year, e.g. 07 dd: day in month, e.g. 10 HH:hour in day(0-23), e.g.0 mm:Minute in hour, e.g. 30 ss: Second in minute, e.g. 50 S: Millisecond in the minute, e.g. 443 Z: Timezone offset in hours(RFC 822 pattern), e.g. -0800
catalogDescription	Short description of the stamp card. Can be displayed in the catalog as a marketing message e.g. Buy 9 Coffees Get the 10th on us

Reward object

Attribute	Description
rewardId	Unique identifier of the reward provided as an award after end user achieves the goal of the stamp card. e.g. 68B3D3E6-E681-482D-9797-89D517DDA94E
walletId	Your tenant’s ID e.g. JANUS
serviceId	Unique identifier of your subscribing digital stamp card service e.g. 10520
name	Name of the reward program e.g. Burger King’s rewards
threshold	The number of stamps needed to earn this reward. This value is same as the number of stamps in the stamp object. e.g.10
imageUrl	Reward image. e.g. http://api-dev.fintiv.co:8080/image/stampcard/68B3D3E6-E681-482D-9797-89D517DDA94E_reward_xhdpi.png
rewardMessage	Customer message when the customer earned required all stamps and eligible to get the reward. e.g. Congratulations!
rewardDescription	Short description of the reward e.g. Free coffee

Reward instance object

Attribute	Description
rewardInstanceId	Unique identifier of the reward instance which the end user earned after collecting the required stamps. e.g. 71584867-2b99-4d76-b628-dbb8526f66b7
cardInstanceId	End user’s card instance ID e.g. 3ab8fd17-2fb5-468c-9079-dfb887aacc54
status	Status of the reward instance. Possible values are - ACTIVE - REDEEMED - DELETED - EXPIRED
rewardedTime	Date and time that the reward instance is created. Format is yyyy-MM-dd’T’HH:mm:ss.SZ e.g. “2019-02-08T14:23:35.443-0500” yyyy: Year, e.g. 1996 <br>MM: Month in year, e.g. 07 dd: day in month, e.g. 10 HH:hour in day(0-23), e.g.0 mm:Minute in hour, e.g. 30 ss: Second in minute, e.g. 50 S: Millisecond in the minute, e.g. 443 Z: Timezone offset in hours(RFC 822 pattern), e.g. -0800
rewardExpirationDate	Date and time that the reward instance expires. Format is yyyy-MM-dd’T’HH:mm:ss.SZ e.g. “2019-02-08T14:23:35.443-0500” yyyy: Year, e.g. 1996 <br>MM: Month in year, e.g. 07 dd: day in month, e.g. 10 HH:hour in day(0-23), e.g.0 mm:Minute in hour, e.g. 30 ss: Second in minute, e.g. 50 S: Millisecond in the minute, e.g. 443 Z: Timezone offset in hours(RFC 822 pattern), e.g. -0800
reward	Reward object of this reward instance. This object has master information of the reward.

Merchant object

Attribute	Description
merchantId	Unique identifier of the merchant whose stores will be associated with the stamp card. e.g. B94F3EE2-EEB1-4EBD-82D2-AB422FDA465A
merchantName	Name of the merchant e.g. Burger King
merchantImageUrl	URL of merchant logo image e.g. http://api-dev.fintiv.co:8080/image/store/B94F3EE2-EEB1-4EBD-82D2-AB422FDA465A_xhdpi.png
updateDtim	Last update date time of this merchant. Format is yyyy-MM-dd’T’HH:mm:ss.SZ e.g. “2019-02-08T14:23:35.443-0500” yyyy: Year, e.g. 1996 <br>MM: Month in year, e.g. 07 dd: day in month, e.g. 10 HH:hour in day(0-23), e.g.0 mm:Minute in hour, e.g. 30 ss: Second in minute, e.g. 50 S: Millisecond in the minute, e.g. 443 Z: Timezone offset in hours(RFC 822 pattern), e.g. -0800

Digital stamp card instance object

Attribute	Description
stampCardId	Unique identifier of the stamp card e.g. 0616DE94-DED7-4D51-B766-2203296654FB
cardInstanceId	Unique identifier of the end user’s stamp card instance e.g. 0131cef8-56e1-461a-b82b-7e220b925481
currentStamps	The number of stamp the end user collects e.g. 0
totalStamps	Number of stamps available in the stamp card. e.g. 5
issueDate	Date and time that end user created the stamp card instance. Format is yyyy-MM-dd’T’HH:mm:ss.SZ e.g. “2019-02-08T14:23:35.443-0500” yyyy: Year, e.g. 1996 <br>MM: Month in year, e.g. 07 dd: day in month, e.g. 10 HH:hour in day(0-23), e.g.0 mm:Minute in hour, e.g. 30 ss: Second in minute, e.g. 50 S: Millisecond in the minute, e.g. 443 Z: Timezone offset in hours(RFC 822 pattern), e.g. -0800
expirationDate	Date and time that the stamp card expires. Format is yyyy-MM-dd’T’HH:mm:ss.SZ e.g. “2019-02-08T14:23:35.443-0500” yyyy: Year, e.g. 1996 <br>MM: Month in year, e.g. 07 dd: day in month, e.g. 10 HH:hour in day(0-23), e.g.0 mm:Minute in hour, e.g. 30 ss: Second in minute, e.g. 50 S: Millisecond in the minute, e.g. 443 Z: Timezone offset in hours(RFC 822 pattern), e.g. -0800
status	Status of the digital stamp card instance. Possible values are - ACTIVE - REDEEMED - DELETED - EXPIRED

Event object

Attribute	Description
cardInstanceId	Unique identifier of the end user’s stamp card instance. e.g. 0131cef8-56e1-461a-b82b-7e220b925481
eventTime	Date and time that the event occurs. Format is yyyy-MM-dd’T’HH:mm:ss.SZ e.g. “2019-02-08T14:23:35.443-0500” yyyy: Year, e.g. 1996 <br>MM: Month in year, e.g. 07 dd: day in month, e.g. 10 HH:hour in day(0-23), e.g.0 mm:Minute in hour, e.g. 30 ss: Second in minute, e.g. 50 S: Millisecond in the minute, e.g. 443 Z: Timezone offset in hours(RFC 822 pattern), e.g. -0800
eventType	Type of the event. Possible values are - STAMP - REDEEM - REWARD - REMOVE_STAMP - REMOVE_REWARD
stampId	Unique identifier of the reward to be earned by this event.
stampValue	A code to explicitly validate the reward redemption. e.g. GZ23-A457-Z50-E56X-O23G
rewardInstanceId	A code to explicitly validate the reward redemption. e.g. GZ23-A457-Z50-E56X-O23G

APIs

End user adds digital stamp card in his/her wallet

End user adds the stamp card in his/her wallet. Supply the identifier of the stamp card and end user’s stamp card instance will be created

Precondition

Client logged in the service. Refer the section for registration/authentication.

Request

HTTP Method / URL
POST / http://api-dev.fintiv.co:8080/stamp/{version}/addCard

Body parameters

Parameters	Type	Required	Note
stampCardId	String	Required	Unique identifier of the stamp card e.g. 0616DE94-DED7-4D51-B766-2203296654FB

Example request

curl -X POST "http://api-dev.fintiv.co:8080/stampcard/v2/addCard"
-H "accept: application/json;charset=UTF-8"
-H "api-key: <insert your APP Key here>"
-H "authorization: Bearer <insert your bearer token here>"
-H "Content-Type: application/json"
-d ‘{"stampCardId":"1F7C3F59-2478-44DD-8059-6E6969542099"}’

Response

Returns result of the request.
Example response

{
  "result": {
    "code": 0
  }
}

End user retrieves his/her digital stamp card

End user find his/her digital stamp card instances by search conditions.

Precondition

Client logged in the service. Refer the section for registration/authentication.

Request

HTTP Method / URL
POST / http://api-dev.fintiv.co:8080/stamp/{version}/getCards

Body parameters

Parameters	Type	Required	Note
latitude	double	Optional	Latitude to find data in the range example: 34.044454912173904
longitude	double	Optional	Longitude to find data in the range example: -84.48063315578163
radius	double	Optional	radius from latitude and longitude to find data in the range. Unit is km. example: 1000000
sortType	int	Optional	Define how to sort the returned data. Default is 0. Possible values are - 0 to not sort data. - 1 to sort data by merchant name with A to Z order - 2 to sort data by merchant name with Z to A order - 3 to sort data by distance with the nearest location appearing first. - 4 to sort data by distance with the farthest location appearing first. - 5 to sort data by its usage with the most frequently used one first. - 6 to sort data by its usage with the least used one first. - 7 to sort data by the sequence that the end user defined using updateCardSequences()

Example request

curl -X POST "http://api-dev.fintiv.co:8080/stampcard/v2/getCards"
-H "accept: application/json;charset=UTF-8"
-H "api-key: <insert your APP Key here>"
-H "authorization: Bearer <insert your bearer token here>"
-H "Content-Type: application/json"
-d ‘{"latitude":34.044454912173904,"longitude": -84.48063315578163,"radius": 10000,"sortType": 4}’

Response

Returns list of end user’s digital stamp instances.
Example response

{
  "result": {
    "code": 0
  },
  "cards": [
    {
      "cardInstanceId": "0131cef8-56e1-461a-b82b-7e220b925481",
      "stampCardId": "9708557D-73F2-4C5E-AA61-90AE0919B6C1",
      "currentStamps": 0,
      "totalStamps": 0,
      "issueDate": "2019-03-14T13:48:09.094+0000",
      "expirationDate": "2019-07-01T03:59:59.000+0000",
      "status": "ACTIVE"
    },
    {
      "cardInstanceId": "4cd8ef60-719a-43bf-8d91-6c8d4be24a2d",
      "stampCardId": "1F7C3F59-2478-44DD-8059-6E6969542099",
      "currentStamps": 0,
      "totalStamps": 0,
      "issueDate": "2019-03-14T13:44:49.025+0000",
      "expirationDate": "2021-01-01T04:59:59.000+0000",
      "status": "ACTIVE"
    }
  ]
}

Retrieve stamp catalogue

Retrieves list of available stamps in the search conditions.

Precondition

Client logged in the service. Refer the section for registration/authentication.

Request

HTTP Method / URL
POST / http://api-dev.fintiv.co:8080/stamp/{version}/getCatalog

Body parameters

Parameters	Type	Required	Note
serviced	String	Optional	Unique identifier of your subscribing digital stamp service. e.g. 10520
latitude	double	Optional	Latitude to find data in the range example: 34.044454912173904
longitude	double	Optional	Longitude to find data in the range example: -84.48063315578163
radius	double	Optional	radius from latitude and longitude to find data in the range. Unit is km. example: 1000000
skipRows	int	Optional	Starting row of data in the list being requested. For example, 2 is set, the first two rows will be skipped. Along with maxRows, you can use this for pagination.
maxResults	int	Optional	Maximum number of data to be returned. Along with skipRows, you can use this for pagination. e.g. 5 returns up to 5 coupons.
merchantIds	String[]	Optional	Identifier of merchant who associated with the digital stamp service. e.g. 1703276A-3709-45C5-B7EE-F5927D6D9EFA
stampCardId	String	Optional	Identifier of a stamp card

Example request

curl -X POST "http://api-dev.fintiv.co:8080/stampcard/v2/getCatalog"
-H "accept: application/json;charset=UTF-8"
-H "api-key: <insert your APP Key here>"
-H "authorization: Bearer <insert your bearer token here>"
-H "Content-Type: application/json"
-d
‘{
    "latitude": 34.044454912173904,
    "longitude": -84.48063315578163,
    "maxResults": 20,
    "radius": 100000,
    "merchantIds": ["1467250E-1CB1-40F4-85B2-85C5BE4EB0A0"],
    "serviceId":"10520",
    "skipRows": 0,
    "stampCardId":"1F7C3F59-2478-44DD-8059-6E6969542099"
}’

Response

Returns result of the request.
Example response

{
  "result": {
    "code": 0
  },
  "catalog": [
    {
      "stampCardId": "1F7C3F59-2478-44DD-8059-6E6969542099",
      "name": "Coffee House",
      "stampType": "QR",
      "stampCount": 0,
      "phoneNumber": "2024419862",
      "isPublishToMarket": "N",
      "backgroundImageUrl": "http://api-dev.fintiv.co:8080/image/stampcard/1F7C3F59-2478-44DD-8059-6E6969542099_bg_xhdpi.png",
      "stampAreaImageUrl": "http://api-dev.fintiv.co:8080/image/stampcard/1F7C3F59-2478-44DD-8059-6E6969542099_stamp_xhdpi.png",
      "rewards": [
        {
          "rewardId": "F175099B-C54D-4BC8-B567-6DFEADD50ED5",
          "serviceId": "10520",
          "name": "Free Coffee",
          "threshold": 5,
          "imageUrl": "http://api-dev.fintiv.co:8080/image/stampcard/F175099B-C54D-4BC8-B567-6DFEADD50ED5_reward_xhdpi.png",
          "rewardMessage": "Congratulations, this on is on us!",
          "rewardDescription": "Free Coffee"
        }
      ],
      "merchant": {
        "merchantId": "1467250E-1CB1-40F4-85B2-85C5BE4EB0A0",
        "merchantName": "Coffee House",
        "merchantImageUrl": "http://api-dev.fintiv.co:8080/image/store/1467250E-1CB1-40F4-85B2-85C5BE4EB0A0_xhdpi.png",
        "updateDtim": "2018-12-19T17:42:26.000+0000",
        "store": {
          "storeId": "2A439A70-B572-45EF-BE50-2D900E4B64DA",
          "storeName": "Coffee House - Alpharetta",
          "street1": "12600 Deerfield Parkway Suite 425",
          "city": "Alpharetta",
          "state": "Georgia",
          "zip": "30004",
          "country": "US",
          "latitude": 34.089487,
          "longitude": -84.270758,
          "distance": 19.971244473406266
        }
      }
    }
  ]
}

Retrieve all events of the end user’s digital stamp card instance

Supply card instance ID and retrieve all events associated with the card instance.

Precondition

Client logged in the service. Refer the section for registration/authentication.

Request

HTTP Method / URL
POST / http://api-dev.fintiv.co:8080/stamp/{version}/getEventHistory

Body parameters

Parameters	Type	Required	Note
cardInstanceId	String	Required	Unique identifier of the end user’s stamp card instance e.g. 0131cef8-56e1-461a-b82b-7e220b925481

Example request

curl -X POST "http://api-dev.fintiv.co:8080/stampcard/v2/getEventHistory"
-H "accept: application/json;charset=UTF-8"
-H "api-key: <insert your APP Key here>"
-H "authorization: Bearer <insert your bearer token here>"
-H "Content-Type: application/json"
-d ‘{"cardInstanceId":"3ab8fd17-2fb5-468c-9079-dfb887aacc54"}’

Response

Returns list of events.
Example response

{
  "result": {
    "code": 0
  },
  "events": [
    {
      "cardInstanceId": "3ab8fd17-2fb5-468c-9079-dfb887aacc54",
      "eventTime": "2019-03-14T21:32:03.278+0000",
      "eventType": "STAMP",
      "stampId": "450CEE46-4E66-4C37-A095-5C3D7B661A23",
      "stampValue": "GZ23-A457-Z50-E56X-O23G",
      "rewardInstanceId": "68B3D3E6-E681-482D-9797-89D517DDA94E"
    },
    {
      "cardInstanceId": "3ab8fd17-2fb5-468c-9079-dfb887aacc54",
      "eventTime": "2019-03-14T21:30:03.278+0000",
      "eventType": "STAMP",
      "stampId": "450CEE46-4E66-4C37-A095-5C3D7B661A23",
      "stampValue": "GZ23-A457-Z50-E56X-O23G",
      "rewardInstanceId": "68B3D3E6-E681-482D-9797-89D517DDA94E"
    },
    {
      "cardInstanceId": "3ab8fd17-2fb5-468c-9079-dfb887aacc54",
      "eventTime": "2019-03-14T20:30:03.278+0000",
      "eventType": "STAMP",
      "stampId": "450CEE46-4E66-4C37-A095-5C3D7B661A23",
      "stampValue": "GZ23-A457-Z50-E56X-O23G",
      "rewardInstanceId": "68B3D3E6-E681-482D-9797-89D517DDA94E"
    },
    {
      "cardInstanceId": "3ab8fd17-2fb5-468c-9079-dfb887aacc54",
      "eventTime": "2019-03-14T19:30:03.278+0000",
      "eventType": "STAMP",
      "stampId": "450CEE46-4E66-4C37-A095-5C3D7B661A23",
      "stampValue": "GZ23-A457-Z50-E56X-O23G",
      "rewardInstanceId": "68B3D3E6-E681-482D-9797-89D517DDA94E"
    },
    {
      "cardInstanceId": "3ab8fd17-2fb5-468c-9079-dfb887aacc54",
      "eventTime": "2019-03-14T18:30:04.278+0000",
      "eventType": "REWARD",
      "stampId": "450CEE46-4E66-4C37-A095-5C3D7B661A23",
      "stampValue": "GZ23-A457-Z50-E56X-O23G",
      "rewardInstanceId": "71584867-2b99-4d76-b628-dbb8526f66b7"
    },
    {
      "cardInstanceId": "3ab8fd17-2fb5-468c-9079-dfb887aacc54",
      "eventTime": "2019-03-14T18:30:03.278+0000",
      "eventType": "STAMP",
      "stampId": "450CEE46-4E66-4C37-A095-5C3D7B661A23",
      "stampValue": "GZ23-A457-Z50-E56X-O23G",
      "rewardInstanceId": "68B3D3E6-E681-482D-9797-89D517DDA94E"
    },
    {
      "cardInstanceId": "3ab8fd17-2fb5-468c-9079-dfb887aacc54",
      "eventTime": "2019-03-14T17:30:03.278+0000",
      "eventType": "STAMP",
      "stampId": "450CEE46-4E66-4C37-A095-5C3D7B661A23",
      "stampValue": "GZ23-A457-Z50-E56X-O23G",
      "rewardInstanceId": "68B3D3E6-E681-482D-9797-89D517DDA94E"
    }
  ]
}

Retrieve merchants who provides digital stamp service with search conditions

Find sorted merchants by search conditions

Precondition

Client logged in the service. Refer the section for registration/authentication.

Request

HTTP Method / URL
POST / http://api-dev.fintiv.co:8080/stamp/{version}/getMerchants

Body parameters

Parameters	Type	Required	Note
Latitude	double	Optional	Latitude to find coupons in the range example: 34.044454912173904
longitude	double	Optional	Longitude to find coupons in the range example: -84.48063315578163
radius	double	Optional	radius from latitude and longitude to find data in the range. Unit is km. example: 1000000
merchantName	String	Optional	Name of the merchant who provides the digital stamp card service
searchType	int	Optional	Define how to sort the returned data. Default is 0. Possible values are - 0 to return all data. - 1 to sort data by distance, with the nearest merchant appearing first. - 2 to sort data by name, with the A to Z order.

Example request

curl -X POST "http://api-dev.fintiv.co:8080/stampcard/v2/getMerchants"
-H "accept: application/json;charset=UTF-8"
-H "api-key: <insert your APP Key here>"
-H "authorization: Bearer <insert your bearer token here>"
-H "Content-Type: application/json"
-d ‘{
    "latitude": 34.044454912173904,
    "longitude": -84.48063315578163,
    "radius": 10000,
    "searchType": 1
}’

Response

Returns list of merchants.
Example response

{
  "result": {
    "code": 0
  },
  "merchants": [
    {
      "merchantId": "1467250E-1CB1-40F4-85B2-85C5BE4EB0A0",
      "merchantName": "Coffee House",
      "merchantImageUrl": "http://api-dev.fintiv.co:8080/image/store/1467250E-1CB1-40F4-85B2-85C5BE4EB0A0_xhdpi.png",
      "updateDtim": "2018-12-19T17:42:26.000+0000"
    },
    {
      "merchantId": "B94F3EE2-EEB1-4EBD-82D2-AB422FDA465A",
      "merchantName": "Burger King",
      "merchantImageUrl": "http://api-dev.fintiv.co:8080/image/store/B94F3EE2-EEB1-4EBD-82D2-AB422FDA465A_xhdpi.png",
      "updateDtim": "2018-10-25T14:34:23.000+0000"
    }
  ]
}

Retrieve the end user’s rewards

End user earns reward after collecting required stamps. Retrieve end user’s all available rewards.

Precondition

Client logged in the service. Refer the section for registration/authentication.

Request

HTTP Method / URL
POST / http://api-dev.fintiv.co:8080/stamp/{version}/getCouponDetail

Body parameters

Parameters	Type	Required	Note
cardInstanceId	String	Optional	Unique identifier of the end user’s stamp card instance e.g. 0131cef8-56e1-461a-b82b-7e220b925481

Example request

curl -X POST "http://api-dev.fintiv.co:8080/stampcard/v2/getRewards"
-H "accept: application/json;charset=UTF-8"
-H "api-key: <insert your APP Key here>"
-H "authorization: Bearer <insert your bearer token here>"
-H "Content-Type: application/json"
-d ‘{"cardInstanceId":"3ab8fd17-2fb5-468c-9079-dfb887aacc54"}’

Response

Returns list of available rewards earned with the card instance.
Example response

{
  "result": {
    "code": 0
  },
  "rewards": [
    {
      "rewardInstanceId": "71584867-2b99-4d76-b628-dbb8526f66b7",
      "cardInstanceId": "3ab8fd17-2fb5-468c-9079-dfb887aacc54",
      "reward": {
        "rewardId": "68B3D3E6-E681-482D-9797-89D517DDA94E",
        "walletId": "JANUS",
        "serviceId": "10520",
        "name": "Test stamp reward 0301-01",
        "threshold": 5,
        "imageUrl": "http://api-dev.fintiv.co:8080/image/stampcard/68B3D3E6-E681-482D-9797-89D517DDA94E_reward_xhdpi.png",
        "rewardMessage": "reward message test",
        "rewardDescription": "reward description"
      },
      "status": "ACTIVE",
      "rewardedTime": "2019-03-14T17:37:37.103+0000",
      "rewardExpirationDate": "2019-04-13T17:37:37.103+0000"
    }
  ]
}

Get stamp master data of the stamp card

Retrieve stamp master data of the stamp card to add the stamp in the end user’s stamp card instance

Precondition

Client logged in the service. Refer the section for registration/authentication.

Request

HTTP Method / URL
POST / http://api-dev.fintiv.co:8080/stamp/{version}/getStamps

Body parameters

Parameters	Type	Required	Note
stampCardId	String	Required	Unique identifier of the stamp card e.g. 0616DE94-DED7-4D51-B766-2203296654FB

Example request

curl -X POST "http://api-dev.fintiv.co:8080/stampcard/v2/getStamps"
-H "accept: application/json;charset=UTF-8"
-H "api-key: <insert your APP Key here>"
-H "authorization: Bearer <insert your bearer token here>"
-H "Content-Type: application/json"
-d ‘{"stampCardId":"0616DE94-DED7-4D51-B766-2203296654FB"}’

Response

Returns the stamp object.
Example response

{
  "result": {
    "code": 0
  },
  "stamps": [
    {
      "stampId": "450CEE46-4E66-4C37-A095-5C3D7B661A23",
      "stampValue": "GZ23-A457-Z50-E56X-O23G",
      "stampState": "ACTIVE",
      "awardStamps": 0,
      "rewardId": "68B3D3E6-E681-482D-9797-89D517DDA94E",
      "stampEventType": "REDEEM"
    }
  ]
}

End user removes a digital stamp card

Client retrieves list of skins configured in the backend.

Precondition

Client logged in the service. Refer the section for registration/authentication.

Request

HTTP Method / URL
POST / http://api-dev.fintiv.co:8080/stamp/{version}/removeCard

Body parameters

Parameters	Type	Required	Note
cardInstanceId	String	Required	Unique identifier of the end user’s stamp card instance e.g. 0131cef8-56e1-461a-b82b-7e220b925481

Example request

curl -X POST "http://api-dev.fintiv.co:8080/stampcard/v2/removeCard"
-H "accept: application/json;charset=UTF-8"
-H "api-key: <insert your APP Key here>"
-H "authorization: Bearer <insert your bearer token here>"
-H "Content-Type: application/json"
-d ‘{"cardInstanceId":"0131cef8-56e1-461a-b82b-7e220b925481"}’

Response

Returns result of the request.
Example response

{
  "result": {
    "code": 0
  }
}

Add multiple stamp events in end user’s stamp card instance

End user collects multiple stamps on his/her stamp card instance.

Precondition

Client logged in the service. Refer the section for registration/authentication.

Request

HTTP Method / URL
POST / http://api-dev.fintiv.co:8080/stamp/{version}/reportMultiStampEvents

Body parameters

Parameters	Type	Required	Note
events	double	Required	List of event

• Event object

Parameters	Type	Required	Note
cardInstanceId	String	Optional	Unique identifier of the end user’s stamp card instance e.g. 0131cef8-56e1-461a-b82b-7e220b925481
eventId	String	Required	Unique identifier of the event defined by the client for the server to distinguish the request and return the result e.g. eventId0321-011, 1, etc.
eventTime	Date	Required	Date and time that the event occurs. Format is yyyy-MM-dd’T’HH:mm:ss.SZ e.g. “2019-02-08T14:23:35.443-0500” yyyy: Year, e.g. 1996 <br>MM: Month in year, e.g. 07 dd: day in month, e.g. 10 HH:hour in day(0-23), e.g.0 mm:Minute in hour, e.g. 30 ss: Second in minute, e.g. 50 S: Millisecond in the minute, e.g. 443 Z: Timezone offset in hours(RFC 822 pattern), e.g. -0800
eventType	String	Required	Type of the event. Possible values are - STAMP - REDEEM - REWARD - REMOVE_STAMP - REMOVE_REWARD
rewardInstanceId	String	Required	Unique identifier of the reward to be earned by this event.
stampValue	String	Required	A code to explicitly validate the reward redemption. e.g. GZ23-A457-Z50-E56X-O23G

Example request

curl -X POST "http://api-dev.fintiv.co:8080/stampcard/v2/reportMultiStampEvents"
-H "accept: application/json;charset=UTF-8"
-H "api-key: <insert your APP Key here>"
-H "authorization: Bearer <insert your bearer token here>"
-H "Content-Type: application/json"
-d ‘{
"events": [
    {
        "eventId":"1",
        "cardInstanceId":"3ab8fd17-2fb5-468c-9079-dfb887aacc54",
        "eventTime":"2019-03-14T18:30:03.278-0000",
        "eventType":"STAMP",
        "rewardInstanceId":"68B3D3E6-E681-482D-9797-89D517DDA94E",
        "stampValue":"GZ23-A457-Z50-E56X-O23G"
    },
    {
        "eventId":"2",
        "cardInstanceId":"3ab8fd17-2fb5-468c-9079-dfb887aacc54",
        "eventTime":"2019-03-14T19:30:03.278-0000",
        "eventType":"STAMP",
        "rewardInstanceId":"68B3D3E6-E681-482D-9797-89D517DDA94E",
        "stampValue":"GZ23-A457-Z50-E56X-O23G"
    }
]
}’

Response

Returns result of each event request. In the below example, the first event earned the reward so that reward object is also returned
Example response

• When all requests were successful

{
  "result": {
    "code": 0
  },
  "eventResults": [
    {
      "result": {
        "code": 0
      },
      "eventId": "1",
      "cardInstance": {
        "cardInstanceId": "3ab8fd17-2fb5-468c-9079-dfb887aacc54",
        "stampCardId": "0616DE94-DED7-4D51-B766-2203296654FB",
        "currentStamps": 1,
        "totalStamps": 0,
        "issueDate": "2019-03-14T14:19:04.141+0000",
        "updateTime": "2019-03-14T17:37:37.149+0000",
        "expirationDate": "2030-03-14T03:59:59.000+0000",
        "status": "ACTIVE",
        "rewards": []
      },
      "rewards": [
        {
          "rewardInstanceId": "71584867-2b99-4d76-b628-dbb8526f66b7",
          "cardInstanceId": "3ab8fd17-2fb5-468c-9079-dfb887aacc54",
          "reward": {
            "rewardId": "68B3D3E6-E681-482D-9797-89D517DDA94E",
            "walletId": "JANUS",
            "serviceId": "10520",
            "name": "Test stamp reward 0301-01",
            "threshold": 5,
            "imageUrl": "http://api-dev.fintiv.co:8080/image/stampcard/68B3D3E6-E681-482D-9797-89D517DDA94E_reward_xhdpi.png",
            "rewardMessage": "reward message test",
            "rewardDescription": "reward description"
          },
          "status": "ACTIVE",
          "rewardedTime": "2019-03-14T17:37:37.103+0000",
          "rewardExpirationDate": "2019-04-13T17:37:37.103+0000"
        }
      ]
    },
    {
      "result": {
        "code": 0
      },
      "eventId": "2",
      "cardInstance": {
        "cardInstanceId": "3ab8fd17-2fb5-468c-9079-dfb887aacc54",
        "stampCardId": "0616DE94-DED7-4D51-B766-2203296654FB",
        "currentStamps": 1,
        "totalStamps": 0,
        "issueDate": "2019-03-14T14:19:04.141+0000",
        "updateTime": "2019-03-14T17:37:37.149+0000",
        "expirationDate": "2030-03-14T03:59:59.000+0000",
        "status": "ACTIVE",
        "rewards": []
      },
      "rewards": []
    }
  ]
}

• When both successful and failed request exist

{
  "result": {
    "code": 0
  },
  "eventResults": [
    {
      "result": {
        "code": 33003,
        "message": "stamp.multiple.stamp.attempt"
      },
      "eventId": "1"
    },
    {
      "result": {
        "code": 0
      },
      "eventId": "2",
      "cardInstance": {
        "cardInstanceId": "3ab8fd17-2fb5-468c-9079-dfb887aacc54",
        "stampCardId": "0616DE94-DED7-4D51-B766-2203296654FB",
        "currentStamps": 4,
        "totalStamps": 0,
        "issueDate": "2019-03-14T14:19:04.141+0000",
        "updateTime": "2019-03-14T17:46:44.173+0000",
        "expirationDate": "2030-03-14T03:59:59.000+0000",
        "status": "ACTIVE",
        "rewards": [
          {
            "rewardInstanceId": "71584867-2b99-4d76-b628-dbb8526f66b7",
            "cardInstanceId": "3ab8fd17-2fb5-468c-9079-dfb887aacc54",
            "reward": {
              "rewardId": "68B3D3E6-E681-482D-9797-89D517DDA94E",
              "walletId": "JANUS",
              "serviceId": "10520",
              "name": "Test stamp reward 0301-01",
              "threshold": 5,
              "imageUrl": "http://api-dev.fintiv.co:8080/image/stampcard/68B3D3E6-E681-482D-9797-89D517DDA94E_reward_xhdpi.png",
              "rewardMessage": "reward message test",
              "rewardDescription": "reward description"
            },
            "status": "ACTIVE",
            "rewardedTime": "2019-03-14T17:37:37.103+0000",
            "rewardExpirationDate": "2019-04-13T17:37:37.103+0000"
          }
        ]
      },
      "rewards": []
    }
  ]
}

• When all request failed

{
  "result": {
    "code": 0
  },
  "eventResults": [
    {
      "result": {
        "code": 33003,
        "message": "stamp.multiple.stamp.attempt"
      },
      "eventId": "1"
    },
    {
      "result": {
        "code": 33003,
        "message": "stamp.multiple.stamp.attempt"
      },
      "eventId": "2"
    }
  ]
}

Add a stamp event in end user’s stamp card instance

End user collects a stamp on his/her stamp card instance.

Precondition

Client logged in the service. Refer the section for registration/authentication.

Request

HTTP Method / URL
POST / http://api-dev.fintiv.co:8080/stamp/{version}/reportStampEvent

Body parameters

Parameters	Type	Required	Note
cardInstanceId	String	Optional	Unique identifier of the end user’s stamp card instance e.g. 0131cef8-56e1-461a-b82b-7e220b925481
eventTime	Date	Required	Date and time that the event occurs. Format is yyyy-MM-dd’T’HH:mm:ss.SZ e.g. “2019-02-08T14:23:35.443-0500” yyyy: Year, e.g. 1996 <br>MM: Month in year, e.g. 07 dd: day in month, e.g. 10 HH:hour in day(0-23), e.g.0 mm:Minute in hour, e.g. 30 ss: Second in minute, e.g. 50 S: Millisecond in the minute, e.g. 443 Z: Timezone offset in hours(RFC 822 pattern), e.g. -0800
eventType	String	Required	Type of the event. Possible values are - STAMP - REDEEM - REWARD - REMOVE_STAMP - REMOVE_REWARD
rewardInstanceId	String	Required	Unique identifier of the reward to be earned by this event.
stampValue	String	Required	A code to explicitly validate the reward redemption. e.g. GZ23-A457-Z50-E56X-O23G

Example request

curl -X POST "http://api-dev.fintiv.co:8080/stampcard/v2/reportStampEvent"
-H "accept: application/json;charset=UTF-8"
-H "api-key: <insert your APP Key here>"
-H "authorization: Bearer <insert your bearer token here>"
-H "Content-Type: application/json"
-d
‘{
    "cardInstanceId":"3ab8fd17-2fb5-468c-9079-dfb887aacc54",
    "eventTime":"2019-03-14T14:30:03.278-0000",
    "eventType":"STAMP",
    "rewardInstanceId":"68B3D3E6-E681-482D-9797-89D517DDA94E",
    "stampValue":"GZ23-A457-Z50-E56X-O23G"
}’

Response

Returns result of the request.
Example response

{
  "result": {
    "code": 0
  },
  "cardInstance": {
    "cardInstanceId": "3ab8fd17-2fb5-468c-9079-dfb887aacc54",
    "stampCardId": "0616DE94-DED7-4D51-B766-2203296654FB",
    "currentStamps": 1,
    "totalStamps": 0,
    "issueDate": "2019-03-14T14:19:04.141+0000",
    "updateTime": "2019-03-14T14:38:14.570+0000",
    "expirationDate": "2030-03-14T03:59:59.000+0000",
    "status": "ACTIVE",
    "rewards": []
  },
  "rewards": []
}

Updates display sequence of stamp cards

End user defines the display sequence of stamp cards in his/her wallet.

Precondition

Client logged in the service. Refer the section for registration/authentication.

Request

HTTP Method / URL
POST / http://api-dev.fintiv.co:8080/stamp/{version}/updateCardSequences

Body parameters

Parameters	Type	Required	Note
updateCardSeqList	String[]	Required	Unique identifier for the offer service.
Child attribute
cardInstanceId	String	Required	Unique identifier of the end user’s stamp card instance. e.g. 0131cef8-56e1-461a-b82b-7e220b925481
sequence	int	Required	Card display sequence

Example request

curl -X POST "http://api-dev.fintiv.co:8080/stampcard/v2/updateCardSequences"
-H "accept: application/json;charset=UTF-8"
-H "api-key: <insert your APP Key here>"
-H "authorization: Bearer <insert your bearer token here>"
-H "Content-Type: application/json"
-d
‘{
"updateCardSeqList": [
       {"cardInstanceId":"3ab8fd17-2fb5-468c-9079-dfb887aacc54","sequence":3},
       {"cardInstanceId":"4cd8ef60-719a-43bf-8d91-6c8d4be24a2d","sequence": 2},
       {"cardInstanceId":"0131cef8-56e1-461a-b82b-7e220b925481","sequence": 1 }
] }’

Response

Returns result of the request.
Example response

{
  "result": {
    "code": 0
  }
}