Offer

You can retrieve all offers from the offer catalog and redeem and manage individual offer.

The offer objects

There are many pieces of information that can be associated with offers. The variations are virtually limitless and therefore provide great flexibility. Within the Fintiv service a small number of these fields are mandatory for every coupon in the catalog while most of the fields are optional. Also, the Fintiv service describes this information and passes it to the mobile application. How this information is presented to the customer can be varied and totally managed by the consumer application.

Offer object

Attribute	Description
serviceId	Unique identifier for the offer service. The value is found in the Service object in SpService. For offer service published by a couponing service provider, check the service ID whose templateId is ‘COUPON_MARKET’. For offer service published by an account owner, check the service ID whose templateId is ‘COUPON001’.
couponId	Unique identifier of the coupon.
couponName	The simple name of the coupon.
couponDesc	A brief text outlining the offer used in the list view of the offers.
categoryId	ID of the category that the coupon is belonged.
publishDtim	Timestamp that coupon is published. Format is yyyy-MM-dd’T’HH:mm:ssZ yyyy: Year, e.g. 1996 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 Z: RFC 822 time zone, e.g. -0800 e.g. “2019-02-08T14:23:35.443-0500”
templateId	Type of service. Possible values are - COUPON001: Basic coupon. Coupon created by the tenant. - COUPON_MARKET: Market place coupon. Coupon created by coupon issuer in the marketplace
couponImageUrl	URL of detail image of the coupon. Calling this URL returns the actual graphic of detail image to be displayed to the End User for the purpose of visual representation of the coupon.
couponImageThumbUrl	URL of thumbnail image of the coupon. Calling this URL returns the actual graphic of thumbnail image to be displayed to the End User for the purpose of visual representation of the coupon.
couponImageDtim	Timestamp that coupon image is updated. Format is yyyy-MM-dd’T’HH:mm:ssZ yyyy: Year, e.g. 1996 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 Z: RFC 822 time zone, e.g. -0800 e.g. “2019-02-08T14:23:35.443-0500”
couponLongDesc	The full text describing the offer which may include purchase requirements and other terms and conditions
couponState	State of coupon. Possible values are ACTIVE, INACTIVE, REDEEMED, EXPIRED, CREATED, PUBLISHED, UNPUBLISHED, DELETED
brandId	ID of the brand sponsoring the coupon
brandName	The name of the primary brand sponsoring the coupon.
brandImageUrl	URL of image of the brand
brandImageDtim	Timestamp that brand image is updated
distance	Distance between the requested postion and the target location to redeem the offer
issuerId	Identifier of the 3rd party offer issuer or offer distributor
legalStatement	The free form text that describes any rules or legal aspects related to the coupon in order to help the End User
locationList	List of store location that the offer can be reddeemed.
merchants	Stores that the offer can be redeedmed within the radius around location center. Location center is the latitude and logitude of the location requested from the client.
nfcEnabled	Has the value true if the offer supports NFC or the value false if the offer does not support NFC
onlineEnabled	Has the value true if the offer is available online or the value false if the offer is not available online
redeemType	Options include one-time redemption or multiple time redemption. Possible values are - ONETIME - MULTIPLE
redemptionBarcodeType	Type of barcode to redeem the coupon. Possible values are: - UPC_A: 1D Product, UPC-A - UPC_E: 1D Product, UPC-3 - EAN_8: 1D Product, EAN_8 - EAN_13: 1D Product, EAN-13 - UPC_EAN_EXTENSION: 1D Product, UPC EAN Extension - CODE_39: 1D Industrial, Code-39 - CODE_93: 1D Industrial, Code-93 - CODE_128: 1D Industrial, Code-128 - CODABAR: 1D Industrial, Code-128 - ITF: 1D Industrial, ITF - RSS_14: 1D Industrial, RSS-14 - RSS_EXPANDED: 1D Industrial, RSS-Expanded - QR_CODE: 2D, QR Code - DATA_MATRIX: 2D, Data Matrix - AZTEC: 2D, Aztec - PDF_417: 2D, PDF-417 - MAXICODE: 2D, MaxiCode - QRCODE: Deprecated. QR Code for backward compatibility - None: No barcode selected. - UNKNOWN: Unknown
couponInstanceId	Unique identifier of a instance of the coupon which is stored by a user
couponInstanceState	State of coupon instance. Possible values are - CREATED - ACTIVE: Coupon is activated by activateCoupons() - INACTIVE: Coupon is deactivated by deactivateCoupons() - DELETED - REDEEMED - EXPIRED
couponLoyalty	A list of reward loyalty program related with this coupon. Multiple programs can be assigned to a coupon.
Child Attributes Attribute Description loyaltyProgramName The name of the loyalty program associated with the loyalty points awarded. rewardedLoyaltyPointsQty The number of loyalty points the End User is awarded when redeeming this coupon.
expiryDtim	The date on which the coupon expires. Format is yyyy-MM-dd’T’HH:mm:ssZ yyyy: Year, e.g. 1996 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 Z: RFC 822 time zone, e.g. -0800 e.g. “2019-02-08T14:23:35.443-0500”
CouponQualifyingItem	A list of items to be purchased to qualify coupon redemption
Child Attributes Attribute Description qualifyingTradeItemGtin Trade item number that is required to be purchased in order to qualify for the coupon. qualifyingTradeItemQty The amount of a trade item that is required to be purchased in order to qualify for the coupon. qualifyingTradeItemGroup Contains a grouping of trade items within a purchase requirement.
CouponRewardItem	A list of items of the consumer reward related to the coupon
Child Attributes Attribute Description rewardedTradeItemGtin GTIN of the item of the consumer reward rewardedTradeItemQty The number of the item rewarded

Category object

Attribute	Description
categoryId	ID of the category that the coupon is belonged.
categoryName	Name of category
desc	Description of the category

Location object

Attribute	Description
locationId	Unique identifier of location e.g. 8F18CFAF-DF38-4A7E-B541-7031E370ED3D
locationName	Name of location e.g. Burger King Alpharetta
locationDesc	Description of the location
latitude	Latitude of the location e.g. 34.04935
longitude	Longitude of the location e.g. -84.15855
distance	radius from latitude and longitude to find data in the range. Unit is km. e.g. : 1000000
addr1	Street address of the location. e.g. 1601 S MoPac Expy
addr2	Street address of the location.e.g. Suite 200
city	City of the location address e.g. Austin
state	State of the location address e.g. TX
country	Country of the location address e.g.US
zipCode	Zipcode of the location address e.g.78746
openHours	Open house of the location
Child Attributes Attribute Description day MON, TUE, WED, THU, FRI, SAT, SUN open Time the location opens. e.g. 0600 close Time the location closes. e.g. 2300
merchantId	Identifier of the merchant associated with the location
amenity	Amenities the location provides
Child Attributes Attribute Description wifi Whether the location provides WIFI. Possible values are - True: WIFI provided - False: WIFI not provided driveThru Whether the location provides driveThru. Possible values are - True: DriveThru provided - False: DriveThru not provided mobilePay Whether the location provides mobilePay service. Possible values are - True: MobilePay service provided - False: MobilePay service not provided accessibility Whether the location provides accessibility. Possible values are - True: Accessibility provided - False: Accessibility not provided fullService Whether the location provides full service. Possible values are - True: Full service provided - False: Full service not provided specialVenue Whether the location provides special venue. Possible values are - True: Special venue provided - False: Special venue not provided

Merchant object

Attribute	Description
merchantId	Unique identifier of merchant
merchantName	Name of merchant
merchantImageUrl	URL to retrieve merchant logo
merchantDtim	Date and time that merchant registered
nearestStore	Nearest merchant’s store. Returns location object
couponCount	The number of coupon available in this merchant.

APIs

Get coupons

A Get Coupons request takes search conditions input and returns all active coupons for end user view.

Precondition

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

Request

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

Body parameters

Parameters	Type	Required	Note
latitude	double	optional	Latitude to find coupons in the range e.g.34.044454912173904
longitude	double	optional	Longitude to find data in the range e.g.-84.48063315578163
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
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.
categoryIds	String[]	optional	Product category ID of the coupon. This is tenant’s custom configuration. For tenant ‘JANUS’, the following values are configured. - 100: Food and Cooking - 200: Restaurants - 300: Travel - 400: Automotive and Fuel - 500: Family and Living/Home - 600: Culture and Entertainment - 700: Health and Beauty - 800: Electronics and Office - 900: Health Care - 1000: Fashion - 1100: Sports and Fitness
merchantList	String[]	optional	Identifier of merchant where the coupon can be redeemed. e.g.1703276A-3709-45C5-B7EE-F5927D6D9EFA

Example request

curl -X POST " http://api-dev.fintiv.co:8080/offer/v2/getCoupons"
-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":1000000,
"skipRows":0,
"merchantList": [
    "B94F3EE2-EEB1-4EBD-82D2-AB422FDA465A"
  ],
"categoryIds": [
    "200"
  ]
}’

Response

Returns list of coupon objects.
Example response

{
  "result": {
    "code": 0
  },
  "couponList": [
    {
      "couponId": "753FB5CE3585443DB9EF68E21DA2A884",
      "couponName": "Free hashbrowns",
      "couponDesc": "Free hashbrowns with a sandwich purchase",
      "redeemType": "ONETIME",
      "publishDtim": "2018-12-10T08:00:00.000+0000",
      "expiryDtim": "2019-12-24T16:00:00.000+0000",
      "brandId": "B94F3EE2-EEB1-4EBD-82D2-AB422FDA465A",
      "brandName": "Burger King",
      "brandImageUrl": "http://api-dev.fintiv.co:8080/image/store/B94F3EE2-EEB1-4EBD-82D2-AB422FDA465A_xhdpi.png",
      "brandImageDtim": "2018-12-13T14:41:53.000+0000",
      "couponImageUrl": "http://api-dev.fintiv.co:8080/image/coupon/753FB5CE3585443DB9EF68E21DA2A884_detail_xhdpi.png",
      "couponImageThumbUrl": "http://api-dev.fintiv.co:8080/image/coupon/753FB5CE3585443DB9EF68E21DA2A884_list_xhdpi.png",
      "couponImageDtim": "2018-12-13T14:41:53.000+0000",
      "national": false,
      "recommendable": true,
      "featured": false,
      "distance": 29.7,
      "categoryId": "200",
      "nfcEnabled": false,
      "onlineEnabled": false
    },
    {
      "couponId": "816BA38D236244D2853FBB44E9B16526",
      "couponName": "3 Danishes for $5",
      "couponDesc": "3 Danishes for $5",
      "expiryDtim": "2019-12-31T17:00:00.000+0000",
      "brandId": "B94F3EE2-EEB1-4EBD-82D2-AB422FDA465A",
      "brandName": "Burger King",
      "brandImageUrl": "http://api-dev.fintiv.co:8080/image/store/B94F3EE2-EEB1-4EBD-82D2-AB422FDA465A_xhdpi.png",
      "brandImageDtim": "2019-01-08T16:40:19.000+0000",
      "couponImageUrl": "http://api-dev.fintiv.co:8080/image/coupon/816BA38D236244D2853FBB44E9B16526_detail_xhdpi.png",
      "couponImageThumbUrl": "http://api-dev.fintiv.co:8080/image/coupon/816BA38D236244D2853FBB44E9B16526_list_xhdpi.png",
      "couponImageDtim": "2019-01-08T16:40:19.000+0000",
      "recommendable": true,
      "featured": false,
      "distance": 29.7,
      "categoryId": "200",
      "nfcEnabled": false,
      "onlineEnabled": false
    },
    {
      "couponId": "5FE882C2AF724013B3C4202B80EA176C",
      "couponName": "BOGO Donut",
      "couponDesc": "BOGO Donut",
      "expiryDtim": "2019-12-31T19:00:00.000+0000",
      "brandId": "B94F3EE2-EEB1-4EBD-82D2-AB422FDA465A",
      "brandName": "Burger King",
      "brandImageUrl": "http://api-dev.fintiv.co:8080/image/store/B94F3EE2-EEB1-4EBD-82D2-AB422FDA465A_xhdpi.png",
      "brandImageDtim": "2019-01-08T16:40:30.000+0000",
      "couponImageUrl": "http://api-dev.fintiv.co:8080/image/coupon/5FE882C2AF724013B3C4202B80EA176C_detail_xhdpi.png",
      "couponImageThumbUrl": "http://api-dev.fintiv.co:8080/image/coupon/5FE882C2AF724013B3C4202B80EA176C_list_xhdpi.png",
      "couponImageDtim": "2019-01-08T16:40:30.000+0000",
      "recommendable": true,
      "featured": false,
      "distance": 29.7,
      "categoryId": "200",
      "nfcEnabled": false,
      "onlineEnabled": false
    }
  ]
}

Add my coupons

End user can save coupons they like. Supply one or multiple unique coupon IDs that were returned from your previous request.

Precondition

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

Request

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

Body parameters

Parameters	Type	Required	Note
serviceId	string	Optional	Unique identifier for the offer service that the coupon is belonged to. For offer, there may be two services; basic coupon service and marketplace service. * 10515(Basic coupon service) * 10522(Marketplace service)
couponIdList	List<String>	Required	List of unique coupon IDs to be saved
locationIdList	List<String>	Optional	List of unique Identifier of stores which accept the coupon

Example request

curl -X POST " http://api-dev.fintiv.co:8080/offer/v2/addMyCoupons"
-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 ‘{
            "couponIdList": ["816BA38D236244D2853FBB44E9B16526"],
            "locationIdList": ["8F18CFAF-DF38-4A7E-B541-7031E370ED3D"]
        }’

Response

Returns result of request and list of end user’s coupon instances.

Example response

{
  "result": {
    "code": 0
  },
  "couponInstances": [
    {
      "type": "CouponDetails",
      "couponId": "816BA38D236244D2853FBB44E9B16526",
      "couponInstanceId": "8B3A98BB-7EB9-4B31-ACB9-D7000DE2D799",
      "locationCount": 0,
      "redemptionCodeType": 0,
      "redemptionCode": "436346374",
      "redemptionBarcodeType": "QR_CODE"
    }
  ]
}

View my coupons

Retrieves the details of all valid coupons that the end user has saved. Supply search conditions, and the corresponding coupon information will be returned among the ones the end user saved. If you locally store my coupond data in your app, you can sync coupon data using this API.

Precondition

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

Request

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

Body parameters

Parameters	Type	Required	Note
hideExpiredYn	String	Optional	Y returns coupons which have not been expired. N doesn’t check coupon expiry date and time. Default value is Y.

Example request

curl -X POST " http://api-dev.fintiv.co:8080/offer/v2/addMyCoupons"
-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
‘{
           "hideExpiredYn": "N"
}’

Response

Returns list of a coupon object.
Example response

{
  "result": {
    "code": 0
  },
  "couponList": [
    {
      "couponId": "816BA38D236244D2853FBB44E9B16526",
      "couponName": "3 Danishes for $5",
      "couponDesc": "3 Danishes for $5",
      "expiryDtim": "2019-12-31T17:00:00.000+0000",
      "brandId": "B94F3EE2-EEB1-4EBD-82D2-AB422FDA465A",
      "brandName": "Burger King",
      "brandImageUrl": "http://api-dev.fintiv.co:8080/image/store/B94F3EE2-EEB1-4EBD-82D2-AB422FDA465A_xhdpi.png",
      "brandImageDtim": "2019-01-08T16:40:19.000+0000",
      "couponImageUrl": "http://api-dev.fintiv.co:8080/image/coupon/816BA38D236244D2853FBB44E9B16526_detail_xhdpi.png",
      "couponImageThumbUrl": "http://api-dev.fintiv.co:8080/image/coupon/816BA38D236244D2853FBB44E9B16526_list_xhdpi.png",
      "couponImageDtim": "2019-01-08T16:40:19.000+0000",
      "couponLongDesc": "3 Danishes for $5",
      "redemptionCodeType": 0,
      "redemptionCode": "436346374",
      "couponState": "ACTIVE",
      "locationList": [
        {
          "locationId": "8F18CFAF-DF38-4A7E-B541-7031E370ED3D",
          "locationName": "Burger King Alpharetta",
          "latitude": 34.04935,
          "longitude": -84.15855,
          "distance": 0,
          "addr1": "5025 Abbotts Bridge Rd",
          "city": "Alpharetta",
          "state": "GA",
          "country": "US",
          "zipCode": "30005",
          "openHours": [
            {
              "day": "MON",
              "open": "0600",
              "close": "2300"
            },
            {
              "day": "TUE",
              "open": "0600",
              "close": "2300"
            },
            {
              "day": "WED",
              "open": "0600",
              "close": "2300"
            },
            {
              "day": "THU",
              "open": "0600",
              "close": "2300"
            },
            {
              "day": "FRI",
              "open": "0600",
              "close": "2300"
            },
            {
              "day": "SAT",
              "open": "0600",
              "close": "2300"
            },
            {
              "day": "SUN",
              "open": "0600",
              "close": "2300"
            }
          ],
          "merchantId": "B94F3EE2-EEB1-4EBD-82D2-AB422FDA465A",
          "amenity": {
            "wifi": true,
            "driveThru": true,
            "mobilePay": true,
            "accessibility": true,
            "fullService": true,
            "specialVenue": false
          }
        }
      ],
      "recommendable": true,
      "featured": false,
      "categoryId": "200",
      "merchants": [],
      "legalStatement": "For limited time only.",
      "couponInstanceId": "8B3A98BB-7EB9-4B31-ACB9-D7000DE2D799",
      "nfcEnabled": false,
      "onlineEnabled": false,
      "redemptionBarcodeType": "QR_CODE"
    }
  ]
}

Redeem coupons

Notifies the services that the coupon is redeemed to update coupon instance state.

Precondition

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

Request

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

Body parameters

Parameters	Type	Required	Note
serviceId	String	Optional	Unique identifier of coupon service.
redeemCouponList	List	Required	List of information of coupons redeemed.

RedeemCouponList

Parameters	Type	Required	Note
couponId	String	Optional	Unique identifier of the coupon.
couponInstanceId	String	Required	Unique identifier of an instance of the coupon which is stored by a user e.g. B1BE03DD-CAE1-49E4-972A-6B13E7A0CBB4
redeemDtim	date	Optional	Coupon redemption date/time. If value is not set, current date and time is set. Format is yyyy-MM-dd’T’HH:mm:ssZ yyyy: Year, e.g. 1996 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 Z: RFC 822 time zone, e.g. -0800 e.g. “2019-02-08T14:23:35.443-0500”

Example request

curl -X POST " http://api-dev.fintiv.co:8080/offer/v2/reportCouponRedemption"
-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
‘{
           "redeemCouponList":
                       [ {
                                 "couponId":"9D564ADC253046F18341AB78512414FF",
                                 "couponInstanceId" : "71722408-490C-4138-A211-E204BFD9A36B",
                                 "redeemDtim": "2018-05-16T21:25:50.000-0500"
                        } ],
           "serviceId": "10522"
}’

Response

Returns result of request.
Example response

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

Get coupon detail

Retrieves the details of a coupon. Supply the unique coupon ID that was returned from your previous request, and the corresponding coupon information will be returned.

Precondition

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

Request

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

Body parameters

Parameters	Type	Required	Note
serviceId	string	optional	Unique identifier for the offer service.
couponId	double	required	Unique identifier of the coupon.

Example request

curl -X POST "http://api-dev.fintiv.co:8080/offer/v2/getCouponDetail"
-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
‘{
           "couponId": "9D564ADC253046F18341AB78512414FF"
}’

Response

Returns coupon object
Example response

{
  "couponId": "9D564ADC253046F18341AB78512414FF",
  "couponName": "Test coupon 021903",
  "couponDesc": "admin api test coupon",
  "expiryDtim": "2020-02-19T21:03:41.000+0000",
  "brandId": "B94F3EE2-EEB1-4EBD-82D2-AB422FDA465A",
  "brandName": "Burger King",
  "brandImageUrl": "http://api-dev.fintiv.co:8080/image/store/B94F3EE2-EEB1-4EBD-82D2-AB422FDA465A_xhdpi.png",
  "brandImageDtim": "2019-02-19T21:59:39.000+0000",
  "couponImageUrl": "http://api-dev.fintiv.co:8080/image/coupon/9D564ADC253046F18341AB78512414FF_detail_xhdpi.png",
  "couponImageThumbUrl": "http://api-dev.fintiv.co:8080/image/coupon/9D564ADC253046F18341AB78512414FF_list_xhdpi.png",
  "couponImageDtim": "2019-02-19T21:59:39.000+0000",
  "couponLongDesc": "admin api test coupon",
  "recommendable": true,
  "featured": false,
  "distance": 0,
  "categoryId": "200",
  "merchants": [
    {
      "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",
      "merchantDtim": "2018-10-25T14:34:23.000+0000"
    }
  ],
  "legalStatement": "For limited time only",
  "nfcEnabled": false,
  "onlineEnabled": false,
  "result": {
    "code": 0
  }
}

Delete my coupons

A Get Coupons request takes search conditions input and returns all active coupons for end user view.

Precondition

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

Request

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

Body parameters

Parameters	Type	Required	Note
serviced	String	Optional	Unique identifier for the offer service.
couponInstanceIdList	String[]	Required	Unique identifier of an instance of the coupon which is stored by a user e.g. B1BE03DD-CAE1-49E4-972A-6B13E7A0CBB4

Example request

curl -X POST "http://api-dev.fintiv.co:8080/offer/v2/removeMyCoupons"
-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
‘{
           "couponInstanceIdList": ["7E530FA4-C684-4C03-8B11-4B595DB0F6C8"]
}’

Response

Returns result of request.
Example response

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

Recommend coupon

Retrieves the recommendation URL of a coupon. Supply the unique coupon ID that was returned from your previous request, and the recommendation URL of the coupon will be returned. The receiver can download and save the coupon by calling the recommendation URL.

Precondition

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

Request

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

Body parameters

Parameters	Type	Required	Note
serviceId	string	Optional	Unique identifier for the offer service.
couponId	string	Required	Unique identifier of the coupon.

Example request

curl -X POST "http://api-dev.fintiv.co:8080/offer/v2/recommendCoupon"
-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
‘{
           "couponId": "ECBAEFD32C244CB79FD1631881C99D98",
           "serviceId": 10515
}’

Response

Returns URL to download the coupon and result of request

Example response

{
  "result": {
    "code": 0
  },
  "recommendUrl": "http://dev-mcpserver.int.mozido.com/corpay/ci/coupon/v2/share/entry/10522/ECBAEFD32C244CB79FD1631881C99D98"
}

Get coupon categories

Retrieves your pre-defined custom coupon categories. Supply your unique offer service ID that was returned from your previous request, and the coupon categories will be returned.

Precondition

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

Request

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

Body parameters

Parameters	Type	Required	Note
serviceId	String	Required	Unique identifier for the offer service.

Example request

curl -X POST "http://api-dev.fintiv.co:8080/offer/v2/getCouponCategories"
-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
‘{
           "serviceId": "10002"
}’

Response

Returns list of categories.
Example response

{
  "result": {
    "code": 0
  },
  "categoryList": [
    {
      "categoryId": "100",
      "categoryName": "Food and Cooking",
      "desc": "default description"
    },
    {
      "categoryId": "200",
      "categoryName": "Restaurants",
      "desc": "default description"
    },
    {
      "categoryId": "300",
      "categoryName": "Travel",
      "desc": "default description"
    },
    {
      "categoryId": "400",
      "categoryName": "Automotive and Fuel",
      "desc": "default description"
    },
    {
      "categoryId": "500",
      "categoryName": "Family and Living/Home",
      "desc": "default description"
    },
    {
      "categoryId": "600",
      "categoryName": "Culture and Entertainment",
      "desc": "default description"
    },
    {
      "categoryId": "700",
      "categoryName": "Health and Beauty ",
      "desc": "default description"
    },
    {
      "categoryId": "800",
      "categoryName": "Electronics and Office",
      "desc": "default description"
    },
    {
      "categoryId": "900",
      "categoryName": "Health Care",
      "desc": "default description"
    },
    {
      "categoryId": "1000",
      "categoryName": "Fashion",
      "desc": "default description"
    },
    {
      "categoryId": "1100",
      "categoryName": "Sports and Fitness",
      "desc": "default description"
    }
  ]
}

Get coupons redeemable locations

Find all redeemable locations of a coupon. The returned locations can be filtered with 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/offer/{version}/getLocations

Body parameters

Parameters	Type	Required	Note
serviceId	String	Optional	Unique identifier for the offer service.
couponId	String	Conditional	Unique identifier of the coupon to search locations. At least one of latitude, longitude or zipCode is needed to find locations.If merchantIds are in the request, coupondId is not required.
keyword	String	Optional	Search locations whose name has search keyword.
merchantIds	String	Optional	Identifier of merchant where the coupon can be redeemed. e.g. 1703276A-3709-45C5-B7EE-F5927D6D9EFA
latitude	double	Conditional	Latitude to find data in the range. e.g.34.044454912173904
longitude	double	Conditional	Longitude to find locations in the range. e.g.-84.48063315578163
maxDistance	double	Optional	radius from latitude and data to find locations in the range. Unit is km.e.g. 1000000
maxResults	int	Optional	Maximum number of data to be returned.

Example request

curl -X POST "http://api-dev.fintiv.co:8080/offer/v2/getLocations"
-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 ‘{
               "couponId": "438285F3B17E43BBAFE8973B4B7B4F89",
               "latitude": 34.049348,
               "longitude": -84.158622,
               "maxDistance": 5,
               "maxResults": 10
      }’

Response

Returns list of location with detail information and result of request
Example response

{
  "result": {
    "code": 0
  },
  "locationList": [
    {
      "locationId": "1657DEF9-5163-4DC4-A3BD-B80E30ED3ED5",
      "locationName": "Courtyard by Marriott Atlanta Duluth",
      "latitude": 34.049348,
      "longitude": -84.158622,
      "distance": 8.548130107105296e-16,
      "locationImageUrl": "http://api-dev.fintiv.co:8080/image/store/62B57113-34D3-4472-B811-CED3A490ABD8_xhdpi.png",
      "addr1": "3550 Venture Pkwy NW",
      "city": "Duluth",
      "state": "GA",
      "country": "US",
      "zipCode": "30096",
      "merchantId": "62B57113-34D3-4472-B811-CED3A490ABD8",
      "amenity": {
        "wifi": true,
        "driveThru": false,
        "mobilePay": false,
        "accessibility": true,
        "fullService": true,
        "specialVenue": false
      }
    },
    {
      "locationId": "F284B88E-0973-419B-8E2C-735A40B027C1",
      "locationName": "Courtyard by Marriott Atlanta Buford",
      "latitude": 34.049352,
      "longitude": -84.158626,
      "distance": 0.0005776515881442754,
      "locationImageUrl": "http://api-dev.fintiv.co:8080/image/store/62B57113-34D3-4472-B811-CED3A490ABD8_xhdpi.png",
      "addr1": "1405 Mall of Georgia Blvd",
      "city": "Buford",
      "state": "GA",
      "country": "US",
      "zipCode": "30519",
      "merchantId": "62B57113-34D3-4472-B811-CED3A490ABD8",
      "amenity": {
        "wifi": true,
        "driveThru": false,
        "mobilePay": true,
        "accessibility": true,
        "fullService": true,
        "specialVenue": false
      }
    }
  ]
}

Update state of coupon instance for active

Update coupon instance state active. Supply list of end user’s coupon instance ID that were returned from your previous request, and the update result will be returned.

Precondition

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

Request

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

Body parameters

Parameters	Type	Required	Note
serviceId	String	Optional	Unique identifier for the offer service.
couponInstanceIdList	String[]	Required	List of coupon instance IDs to be updated. e.g.["71722408-490C-4138-A211-E204BFD9A36B”]

Example request

curl -X POST "http://api-dev.fintiv.co:8080/offer/v2/deactivateCoupons"
-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 ‘{
           "couponInstanceIdList": ["71722408-490C-4138-A211-E204BFD9A36B" ]
      }’

Response

Returns result of request
Example response

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

Update state of coupon instance for inactive

Update coupon instance state inactive. Supply list of end user’s coupon instance ID that were returned from your previous request, and the update result will be returned.

Precondition

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

Request

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

Body parameters

Parameters	Type	Required	Note
serviceId	String	Optional	Unique identifier for the offer service.
couponInstanceIdList	String[]	Required	List of coupon instance IDs to be updated. e.g.["71722408-490C-4138-A211-E204BFD9A36B”]

Example request

curl -X POST "http://api-dev.fintiv.co:8080/offer/v2/activateCoupons"
-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
‘{
               "couponInstanceIdList": ["71722408-490C-4138-A211-E204BFD9A36B"]
}’

Response

Returns result of request
Example response

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

Get list of merchant

Find sorted merchant 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/offer/{version}/getMerchantList

Body parameters

Parameters	Type	Required	Note
serviceId	string	Optional	Unique identifier for the offer service. e.g. 10517
latitude	double	Required	Latitude to find data in the range. e.g. 34.044454912173904
longitude	double	Required	Longitude to find data in the range. e.g. -84.48063315578163
maxResult	int	Required	Maximum number of data to be returned. Along with skipRows, you can use this for pagination. e.g. 5 returns up to 5 coupons. example: 20
radius	int	Required	radius from latitude and longitude to find coupons in the range. Unit is km. e.g.: 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 maximum number of rows, you can use this for pagination.
sortBy	int	Optional	Define how to sort the returned data. Default is 0. Possible values are 0 to sort data by distance, with the nearest merchant appearing first. 1 to sort data by name, with the A to Z order. 2 to sort data by the number of available in the merchant coupon, with the most merchant appearing first.

Example request

curl -X POST "http://api-dev.fintiv.co:8080/offer/v2/getMerchantList"
-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": 13.3833,
           "longitude": 52.5167,
           "maxResults": 50,
           "radius": 51000,
           "skipRows": 0,
           "sortBy": 0
}’

Response

Returns list of merchants with detail information and request result.
Example response

{
  "result": {
    "code": 0
  },
  "merchantList": [
    {
      "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",
      "merchantDtim": "2018-10-25T14:34:23.000+0000",
      "nearestStore": {
        "locationId": "8F18CFAF-DF38-4A7E-B541-7031E370ED3D",
        "locationName": "Burger King Alpharetta",
        "latitude": 34.04935,
        "longitude": -84.15855,
        "distance": 13030.639719519537,
        "addr1": "5025 Abbotts Bridge Rd",
        "city": "Alpharetta",
        "state": "GA",
        "country": "US",
        "zipCode": "30005",
        "openHours": [
          {
            "day": "MON",
            "open": "0600",
            "close": "2300"
          },
          {
            "day": "TUE",
            "open": "0600",
            "close": "2300"
          },
          {
            "day": "WED",
            "open": "0600",
            "close": "2300"
          },
          {
            "day": "THU",
            "open": "0600",
            "close": "2300"
          },
          {
            "day": "FRI",
            "open": "0600",
            "close": "2300"
          },
          {
            "day": "SAT",
            "open": "0600",
            "close": "2300"
          },
          {
            "day": "SUN",
            "open": "0600",
            "close": "2300"
          }
        ],
        "merchantId": "B94F3EE2-EEB1-4EBD-82D2-AB422FDA465A",
        "amenity": {
          "wifi": true,
          "driveThru": true,
          "mobilePay": true,
          "accessibility": true,
          "fullService": true,
          "specialVenue": false
        }
      },
      "couponCount": 8
    },
    {
      "merchantId": "62B57113-34D3-4472-B811-CED3A490ABD8",
      "merchantName": "Marriott",
      "merchantImageUrl": "http://api-dev.fintiv.co:8080/image/store/62B57113-34D3-4472-B811-CED3A490ABD8_xhdpi.png",
      "merchantDtim": "2018-10-25T14:34:35.000+0000",
      "nearestStore": {
        "locationId": "F284B88E-0973-419B-8E2C-735A40B027C1",
        "locationName": "Courtyard by Marriott Atlanta Buford",
        "latitude": 34.049352,
        "longitude": -84.158626,
        "distance": 13030.644826808648,
        "addr1": "1405 Mall of Georgia Blvd",
        "city": "Buford",
        "state": "GA",
        "country": "US",
        "zipCode": "30519",
        "merchantId": "62B57113-34D3-4472-B811-CED3A490ABD8",
        "amenity": {
          "wifi": true,
          "driveThru": false,
          "mobilePay": true,
          "accessibility": true,
          "fullService": true,
          "specialVenue": false
        }
      },
      "couponCount": 1
    }
  ]
}

Set favorite merchants

Set the list of merchants as the end user’s favorite merchants.

Precondition

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

Request

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

Body parameters

Parameters	Type	Required	Note
serviceId	String	Optional	Unique identifier for the offer service.
merchantIds	String[]	Required	List of merchant IDs [“80277822-10DA-4829-8708-7636DED7944C”]

Example request

curl -X POST "http://api-dev.fintiv.co:8080/offer/v2/setFavoriteMerchant"
-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
‘{
           "merchantIds": [ "80277822-10DA-4829-8708-7636DED7944C"]
}’

Response

Returns result of request
Example response

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

Get favorite merchants

Retrieve the list of end user’s favorite merchants

Precondition

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

Request

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

Body parameters

Parameters	Type	Required	Note
serviceId	String	Optional	Unique identifier for the offer service.

Example request

curl -X POST "http://api-dev.fintiv.co:8080/offer/v2/getFavoriteMerchant"
-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 ‘{}’

Response

Returns list of merchant IDs with result code.
Example response

{
  "result": {
    "code": 0
  },
  "merchantIds": [
    "80277822-10DA-4829-8708-7636DED7944C"
  ]
}

Get my coupon count

Retrieves the number of end user’s saved coupon

Precondition

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

Request

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

Body parameters

Parameters	Type	Required	Note
serviceId	String	Optional	Unique identifier for the offer service.

Example request

curl -X POST "http://api-dev.fintiv.co:8080/offer/v2/getMyCouponCount"
-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 ‘{}’

Response

Returns coupon count with result code.
Example response

{
  "result": {
    "code": 0
  },
  "count": 3
}