Overview - Coupon, Voucher and Gift Card Service

Step-by-step

There are a number of components and subcomponents which ensure that CVS transactions can successfully be completed:

Component	Description
CVS	A wiBlox Coupon Voucher service that allows a distribution channel to issue and manage tokens for mobile discounts (coupons or vouchers) and gift cards against a channel and campaign with advanced redemption rules, which can then be distributed to end-users to be redeemed in real-time as tender for retail payment transactions at a point-of-sale (POS) terminal. CVS provides a powerful Issuer REST API for the issuing and management of coupon, voucher and gift card tokens. The CVS Issuer API also allows a view of campaign and store related information to display on the distribution channel.
wiCode Platform	A mobile transaction platform that provides robust high performance mobile transactional and token management interfaces for switching and processing retail mobile transactions that empowers the redemption of value from CVS campaigns and other value store providers like mobile wallets at a various retail point-of-sale (POS).
Web Portal	A friendly and secure web portal that enables the creation of discount campaigns with redemption logic that could include advanced discount criteria based on the basket value, products purchased, store, distribution channel, timing and user profile.
User	An end-user of a mobile channel (App or USSD subscriber) that receives distributed mobile tokens to redeem value (discount or gift-card value) at a retail POS.
Distribution Channel	A distribution channel is a client system that issues and distributes mobile tokens representative of discount (or gift card) campaign(s) linked to a user with certain redemption rules to use as tender during POS transactions.
POS	Point-of-sale terminal that performs real-time transactions, typically in a traditional retail store. A retailer POS that is enabled on the wiCode platform can allow the redemption of CVS coupon, voucher and gift card tokens as part of the payment process.

Coupons and Vouchers

wiBlox enabled Coupons and Vouchers can be used to redeem discounts at a point of sale (POS) terminal in real-time (typically in-store) through the wiCode Platform.

The wiBlox Coupon Voucher Service (CVS) allows a campaign owner (e.g. Brand or Retailer) to use a friendly and secure web portal to create discount campaigns with redemption logic that could include advanced discount criteria based on the basket value, products purchased, store and user profile.
Coupons or Vouchers (and a representative token of the linked discount campaign(s)) first need to be issued from the service by the distribution channel or system via a powerful Issuer REST API and then distributed to the user to present as mobile tender at the POS at transaction time. The CVS Issuer API also allows a view of campaign and store related information to display on the distribution channel.
At transaction time, the POS passes the user’s token and transactional information to CVS via the wiCode platform. The transactional information gets interrogated by the CVS rules engine to determine if and how much discount is approved to the POS for the transactional tender.
Campaigns can optionally be configured to send redemption information to a remote system via a redemption callback. This notification can be consumed by the distributing system in order to enhance the user experience.

At a technical level, Coupon or Voucher integrations are mainly concerned with the issuing and distribution of tokens for redemption (#2) and not the redemption itself, unless the channel requires to be notified of successful redemption transactions via the redemption callback (#4).

Gift cards

CVS can also enable the redemption of “multi-redeem” giftcards at a point of sale (POS) terminal in real-time (typically in-store) through the wiCode Platform.

CVS allows a campaign owner (e.g. Brand or Retailer) to use a friendly and secure web portal to create giftcard campaigns with redemption logic that could include advanced redemption criteria based on the basket value, products purchased, store and user profile.
A token linked to the user’s giftcard(s) first need to be issued from the service by the distribution channel or system via a powerful Issuer REST API and then distributed to the user to present as mobile tender at the POS at transaction time. The CVS Issuer API also allows a view of campaign and store related information as well as a giftcard balance to display on the distribution channel.
At transaction time, the POS passes the user’s token and transactional information to CVS via the wiCode platform. The transactional information gets interrogated by the CVS rules engine to determine the amount to be approved or declined to the POS for the transactional tender.
Campaigns can optionally be configured to send redemption information to a remote system via a redemption callback. This notification can be consumed by the distributing system in order to enhance the user experience.

CVS Web Portal

The web portal interface is the client-facing interface where the Campaign rules and the Campaign analytics are loaded and reflected, respectively.

A snapshot of the CVS Web Portal login screen.

QA URL

To access the portal, simply open this URL in your browser.

Guide

To learn how the wiGroup CVS Web Portal works, and how to setup your own campaigns. Download the Guide here

CVS Issuer REST API

The CVS Issuer API is the underlying interface for all of wiGroup’s Coupon, Voucher, and Gift card related integrations. It is the simplest and most direct way to issue Coupons, Vouchers and Gift cards from wiGroup.

Each CVS Issuer API method is accompanied by a table of fields.

Each method tabulates the available HTTP verb along with the list of parameters that they accept.
A bold field in the Request column indicates that it’s mandatory.
A ✓ in the Request column of an operation denotes a field available in the request message.
A ✓ in the Response column of an operation denotes its presence in the response payload.
GET methods never have a body. All parameters are sent through as part of the URL as query parameters, e.g. {root}/{resource}?parameter=value.
POST/PUT methods always have a body. All request parameters are sent through as part of a JSON object in the body. There is one exception to this rule when issuing a coupon. The issueWiCode parameter must be sent through as a query parameter as it does not form part of the resource.
DELETE methods don’t have query parameters or a body. It only takes in a URL parameter which is the resource id to delete, e.g. {root}/{resource}/{id}

Date format

A strict ISO 8601 date format is followed for dates. In Java a date can be formatted in the ISO 8601 format with the following snippet:

Monetary format

Monetary amounts are both accepted and returned in cents.

Paginated collections

All of the RESTful Web Service calls that return collections accept the following query parameters:

Parameter	Type	Description
pageSize	Integer (Default 20)	The max number of items returned per page.
pageOffset	Integer (Default 0)	Zero‐based page offset into the list of all results.
orderBy	String	A field by which to order the list (when ordering on the collection is available).
orderDirection	String (Default “ASC”)	The order direction (when ordering on the list is available).

The following fields are returned in a paging object in the response of collection requests:

Parameter	Type	Description
orderBy	String	The field by which the list was ordered.
orderDirection	String	The order direction.
pageSize	Integer	The max number of items returned per page.
pageOffset	Integer	Zero‐based page offset into the list of all results.
numItemsOnPage	Integer	The number of items returned on the current page.
numItemsInTotal	Integer	Total number of items found for the current set of constraints.
numPages	Integer	The total number of pages found.

API credentials

This section provides interface definitions to allow for implementation on various platforms and in different programming languages. Note that:

Our APIs were designed using the RESTful architectural style.
Request and response bodies are formatted as JSON exclusively.
Variables are indicated between angle brackets and the pound sign, e.g. {variable}.
Different request -‐ response combinations are explored using ‘Cases’.

API references

Once the CVS campaigns have been created via the CVS Web Portal and signed-off, the CVS RESTful web service endpoints may be accessed by utilising the following WADL ({endpointURL}):

Test credentials

All calls to the wiCode platform or to CVS must contain the issuing channel credentials in the header of the API call. Table 2 contains a set of VSP-specific API credentials that may be used to authenticate all API calls made to CVS and wiPlatform.

API ID	API Password
{apiID}	{apiPassword}

Test API credentials are provided by the wiGroup integration team, and can thereafter be accessed via the CVS Portal. CVS portal login credentials will also be provided by the wiGroup integration team.

/couponcampaigns

This request returns a list of active campaigns which are linked to the specific channel (issuer interface). By default only campaigns which still have coupons left to issue will be returned.

GET /couponcampaigns


# Example request

curl "https://za-vsp-int.wigroup.co/cvs-issuer/rest/couponcampaigns" \
  -H "apiId: {apiId}" \
  -H "apiPassword: {apiPassword}" \
  -H "Content-Type: application/json" \
  -X GET

# Example response

{
        "issueFromDate": "2017-09-11T00:00:00+0200",
        "issueToDate": "2017-09-12T23:59:59+0200",
        "redeemFromDate": "2017-09-11T00:00:00+0200",
        "redeemToDate": "2017-09-12T23:59:59+0200",
        "minBasketValue": 0,
        "maxBasketValue": 0,
        "maxRedemptionsPerUserPerDay": 0,
        "id": 48184,
        "name": "% discount",
        "description": "% discount",
        "termsAndConditions": "% discount",
        "createDate": "2017-09-11T11:31:43+0200",
        "requireUserRef": false,
        "allowedUsersRestricted": false,
        "maxNumberPerUser": 1,
        "maxLivePerUser": 0,
        "campaignType": "VOUCHER",
        "minRank": 11,
        "categories": [         {
           "name": "All",
           "id": 782,
           "rank": 11
        }],
        "maxAllowedToIssue": 10,
        "maxAllowedToIssueDaily": 10,
        "maxRedemptionRuleAmount": 100000,
        "discountType": "Percentage",
        "percentageDiscount": 20,
        "totalLive": 0,
        "totalRedeemed": 0,
        "totalExpired": 0,
        "totalIssued": 0,
        "totalIssuedToday": 0,
        "campaignInfo": [         {
           "name": "Adword",
           "value": "%,discount,% discount"
        }],
        "stateId": "A",
        "allowExpiryDateOverride": false,
        "expiryDays": 1096,
        "campaignRedemptionRestrictions":          {
           "redeemabableOnSundays": true,
           "redeemabableOnMondays": true,
           "redeemabableOnTuesdays": true,
           "redeemabableOnWednesdays": true,
           "redeemabableOnThursdays": true,
           "redeemabableOnFridays": true,
           "redeemabableOnSaturdays": true,
           "redemptionFromTime": "00:00",
           "redemptionToTime": "00:00"
        }
     }
  ],
  "paging":    {
     "pageSize": 20,
     "pageOffset": 0,
     "numItemsOnPage": 11,
     "numItemsInTotal": 11,
     "numPages": 1
  },
  "responseCode": "-1",
  "responseDesc": "Success"

This request returns a list of active campaigns which are linked to the specific channel (issuer interface). By default only campaigns which still have coupons left to issue will be returned. If no user reference (userRef) is specified in the request it is possible that there are campaigns which the user has already reached the max allowed per user. When the user tries to issue another on the campaign they will be declined. For a better customer experience we recommend including the user reference in the request. This will hide campaigns which the user cannot issue on. A similar problem occurs when the user has reached the max allowed to be issued, but still has a coupon active for redemption. This campaign will not be included in the campaign list. To include these campaigns the includeRedeemableForUser parameter must be set to true.

Endpoint: {root}/couponcampaigns

Available methods: GET

Parameter	Type	Description	Request	Response
id	Integer	The id of the campaign.	✓	✓
allowExpiryDateOverride	Boolean	Whether the campaign allows the default expiry days to be overwritten on issue.		✓
expiryDays	Integer	The default number of days the coupon will be valid for from issue date. The expiry date will be set to midnight x days from issue date.		✓
adwords	List	List of adwords linked to the campaign. Adwords are special search key words which when setup against a campaign can be used to filter the campaign.	✓	✓
campaignPhase	String	The phase of the campaign. TODAY (activated today) CURRENT (all active) PENDING (pending activation)	✓
campaignType	String	The campaign type. COUPON VOUCHER COUPONVOUCHER	✓	✓
categoryIds	List	A list of category id’s. It will return campaigns which match any of the categories supplied.	✓
merchantId	Integer	A merchant id to filter campaigns on.	✓
provinceId	Integer	A province id to filter campaigns on.	✓
countryId	Integer	A country id to filter campaigns on.	✓
retailerId	Integer	A retailer id to filter campaigns on.	✓
longitude	Double	A longitude position. Required for distance calculation. Both longitude and latitude need to be specified together.	✓
latitude	Double	A latitude position. Required for distance calculation. Both longitude and latitude need to be specified together.	✓
userRef	String	A unique user reference. When specified only campaigns on which the user can still be issued coupons will be returned.	✓
includeRedeemableForUser	Boolean	Whether to include campaigns which the user has unredeemed coupons/voucher, but cannot get anymore issued. Normally the campaign would drop off the list as soon as the user cannot be issued anymore. Must be used in conjunction with the userRef field	✓
totalViewed	Integer	The total number viewed of the couponCampaign.		✓
issueFromDate	String	The date from which a couponCampaign is allowed to be issued.		✓
issueToDate	String	The date the couponCampaign is allowed to be issued to.		✓
redeemFromDate	String	The date the couponCampaign is allowed to be redeemed from.		✓
redeemToDate	String	The date the couponCampaign is allowed to be redeemed to.		✓
minBasketValue	Integer	The minimum value of the basket allowed to redeem		✓
maxBasketValue	Integer	The maximum value of the basket allowed to redeem		✓
name	String	The name of the couponCampaign.		✓
description	String	The description of the couponCampaign.		✓
termsAndConditions	String	The terms and conditions of the couponCampaign.		✓
imageUrl	String	The image url of the couponCampaign.		✓
createDate	String	The date the couponCampaign was created.		✓
requireUserRef	Boolean	True if a userRef is required for couponCampaign.		✓
allowedUsersRestricted	Boolean	Whether only the users linked to the campaigns are able to view the contents of the campaign.		✓
maxNumberPerUser	Integer	The maximum number allowed per user.		✓
maxRedemptionsPerUserPerDay	Integer	The maximum number of redemption’s per user on the couponCampaign daily.		✓
maxLivePerUser	Integer	The maximum allowed live(issued and not redeemed/expired) per user.		✓
minRank	Integer	The minimum rank of the couponCampaign.		✓
categories	Object	List of category details. Each entry consists of a name (String), id (Long) and rank (Integer).		✓
distance	Double	The distance to the closest merchant.		✓
maxAllowedToIssue	Integer	The maximum allowed to be issued in total.		✓
maxAllowedToIssueDaily	Integer	The maximum allowed to be issued in total daily.		✓
maxRedemptionRuleAmount	Integer	The maximum redemption rule amount.		✓
discountType	String	`Fixed value` or `percentage`.		✓
percentageDiscount	Integer	This parameter is only available for vouchers. If a voucher campaign is a percentage discount, the value will be listed here.		✓
totalLive	Integer	The total live coupons/voucher on the couponCampaign.		✓
totalRedeemed	Integer	The total number redeemed of the couponCampaign.		✓
totalExpired	Integer	The total number expired of the couponCampaign.		✓
totalIssued	Integer	The total number issued (live + redeemed) of the couponCampaign.		✓
totalIssuedToday	Integer	The total number issued daily of the couponCampaign.		✓
campaignInfo	Object	List of campaign info details. Each entry consists of a campaign name (String) and a campaign info value (String).		✓
stateId	String	The current state of the coupon. A (Active) D (Deactivated) E (Expired) R (Redeemed)		✓
campaignRedemptionRestrictions	Long	This rule states on which days the reward can be reedemed. If restrictions exist for a specific day, the value of the parameter will be “FALSE”		✓

GET /couponcampaigns/{campaignId}


# Example request

curl "https://za-vsp-int.wigroup.co/cvs-issuer/rest/couponcampaigns/{campaignId}" \
  -H "apiId: {apiId}" \
  -H "apiPassword: {apiPassword}" \
  -H "Content-Type: application/json" \
  -X GET

# Example response

{
  "couponCampaigns": [ {
    "allowExpiryDateOverride": false,
    "expiryDays":0,
    "totalViewed": 0,
    "issueFromDate": "2015-05-21T00:00:00+0200",
    "issueToDate": "2015-11-21T23:59:59+0200",
    "redeemFromDate": "2015-05-21T00:00:00+0200",
    "redeemToDate": "2015-11-21T23:59:59+0200",
    "minBasketValue": 0,
    "maxBasketValue": 0,
    "maxRedemptionsPerUserPerDay": 0,
    "id": 4449,
    "name": "Coupon R5",
    "description": "Coupon R5",
    "termsAndConditions": "VSP T&Cs",
    "imageURL": "http://goo.gl/Zodst9",
    "createDate": "2015-05-21T07:14:01+0200",
    "requireUserRef": false,
    "allowedUsersRestricted": false,
    "maxNumberPerUser": 0,
    "maxLivePerUser": 0,
    "campaignType": "COUPON",
    "minRank": 3,
    "categories": [ {
      "name": "All",
      "id": 807,
      "rank": 3
    }],
    "maxAllowedToIssue": 100000,
    "maxAllowedToIssueDaily": 100000,
    "maxRedemptionRuleAmount": 500,
    "discountType": "Percentage",
    "percentageDiscount": 20,
    "totalLive": 1,
    "totalRedeemed": 37,
    "totalExpired": 1,
    "totalIssued": 38,
    "totalIssuedToday": 4,
    "campaignInfo": [ {
      "name": "Adword",
      "value": "Integration,Gift,Card,R5,Integration Gift Card R5"
    }],
    "stateId": "A"
  }],
  "paging":
  {
    "pageSize": 20,
    "pageOffset": 0,
    "numItemsOnPage": 1,
    "numItemsInTotal": 1,
    "numPages": 1
  },
  "responseCode": "-1",
  "responseDesc": "Success"
}

When a specific campaign’s details are required rather than pulling the entire campaign list down, this endpoint can be used to retrieve the single campaign’s details.

Endpoint: {root}/couponcampaigns/{campaignId}

Available methods: GET

Parameter	Type	Description	Request	Response
campaignId	Integer	The id of the campaign.	✓	✓
allowExpiryDateOverride	Boolean	Whether the campaign allows the default expiry days to be overwritten on issue.		✓
expiryDays	Integer	The default number of days the coupon will be valid for from issue date. The expiry date will be set to midnight x days from issue date.		✓
totalViewed	Integer	The total number viewed of the couponCampaign.		✓
issueFromDate	String	The date from which a couponCampaign is allowed to be issued.		✓
issueToDate	String	The date the couponCampaign is allowed to be issued to.		✓
redeemFromDate	String	The date the couponCampaign is allowed to be redeemed from.		✓
redeemToDate	String	The date the couponCampaign is allowed to be redeemed to.		✓
minBasketValue	Integer	The minimum value of the basket allowed to redeem		✓
maxBasketValue	Integer	The maximum value of the basket allowed to redeem		✓
name	String	The name of the couponCampaign.		✓
description	String	The description of the couponCampaign.		✓
termsAndConditions	String	The terms and conditions of the couponCampaign.		✓
imageUrl	String	The image url of the couponCampaign.		✓
createDate	String	The date the couponCampaign was created.		✓
requireUserRef	Boolean	True if a userRef is required for couponCampaign.		✓
allowedUsersRestricted	Boolean	Whether only the users linked to the campaigns are able to view the contents of the campaign.		✓
maxNumberPerUser	Integer	The maximum number allowed per user.		✓
maxRedemptionsPerUserPerDay	Integer	The maximum number of redemption’s per user on the couponCampaign daily.		✓
maxLivePerUser	Integer	The maximum allowed live(issued and not redeemed/expired) per user.		✓
minRank	Integer	The minimum rank of the couponCampaign.		✓
categories	Object	List of category details. Each entry consists of a name (String), id (Long) and rank (Integer).		✓
distance	Double	The distance to the closest merchant.		✓
maxAllowedToIssue	Integer	The maximum allowed to be issued in total.		✓
maxAllowedToIssueDaily	Integer	The maximum allowed to be issued in total daily.		✓
maxRedemptionRuleAmount	Integer	The maximum redemption rule amount.		✓
discountType	String	`Fixed value` or `percentage`.		✓
percentageDiscount	Integer	This parameter is only available for vouchers. If a voucher campaign is a percentage discount, the value will be listed here.		✓
totalLive	Integer	The total live coupons/voucher on the couponCampaign.		✓
totalRedeemed	Integer	The total number redeemed of the couponCampaign.		✓
totalExpired	Integer	The total number expired of the couponCampaign.		✓
totalIssued	Integer	The total number issued (live + redeemed) of the couponCampaign.		✓
totalIssuedToday	Integer	The total number issued daily of the couponCampaign.		✓
campaignInfo	Object	List of campaign info details. Each entry consists of a campaign name (String) and a campaign info value (String).		✓
stateId	String	The current state of the coupon. A (Active) D (Deactivated) E (Expired) R (Redeemed)		✓

GET /couponcampaigns/{campaignId}/skus


# Example request

curl "https://za-vsp-int.wigroup.co/cvs-issuer/rest/couponcampaigns/{campaignId}/skus" \
  -H "apiId: {apiId}" \
  -H "apiPassword: {apiPassword}" \
  -H "Content-Type: application/json" \
  -X GET

# Example response

{
  "responseCode": "-1",
  "responseDesc": "Success!",
  "skus": [
    {
      "sku": "string",
      "value": 0,
      "brand": "string",
      "product": "string",
      "size": "string"
    }
  ]
}

If the campaign type is COUPON, the campaign will have SKUs linked to it. This endpoint can be used to retrieve the list of SKUs linked to the campaign.

Endpoint: {root}/couponcampaigns/{campaignId}/skus

Available methods: GET

Parameter	Type	Description	Request	Response
campaignId	Integer	The id of the campaign.	✓	✓
skus	Array	List of skus. Each sku object in the array consists of a sku (string), the sku value (integer), the sku brand (string), the sku product (string) and the product size (string)		✓

/coupons

The fundamental difference between a wiGroup Coupon and Voucher is that a Coupon is associated with a particular SKU (or set of SKUs) being in the basket, while a voucher is merely a fixed discount amount, or percentage discount amount off the total basket amount processed during tender.

The issuing and redemption of wiGroup Coupons and Vouchers are identical when utilising the CVS Issuer API.

POST /coupons

# Example request

curl "https://za-vsp-int.wigroup.co/cvs-issuer/rest/coupons?issueWiCode=true" \
  -H "apiId: {apiId}" \
  -H "apiPassword: {apiPassword}" \
  -H "Content-Type: application/json" \
  -X POST \
  -d '{
       "campaignId": "9000",
       "userRef": "VSP_User_Id_001",
       "mobileNumber": "string",
       "smsMessage": "string",
       "sendSMS": boolean
     }'

# Example response

{  
  “coupon”: {
    “id”: 20,
    “userRef”: "VSP_User_Id_001",
    “campaignId”: 9000,
    “campaignName”: "VSPTestCouponCampaign",
    “campaignType”: "COUPON",
    “termsAndConditions”: "VSP T&Cs",
    “createDate”: "2015-05-15T15:10:07+0200",
    “description”: "R5.00 off SKU 1234",
    “redeemFromDate”: "2015-05-15T15:10:07+0200",
    “redeemToDate”: "2015-08-22T23:59:59+0200",
    “wiCode”: 1234567,
    “voucherAmount”: 500,
    “wiQr”: 1234567
  },
  “responseCode”: "-1",
  “responseDesc”: "Success"
}

This resource can be used to issue new coupons (coupon/voucher). Issuing a Coupon or Voucher is a straight forward API call. Two parameters must be supplied: campaignID and userRef. Each time this API is called a Coupon or Voucher is issued against the userRef and the campaignID.

Endpoint: {root}/coupons

Available methods: POST

Parameter	Type	Description	Request	Response
issueWiCode	Boolean (query parameter)	Whether to issue a wiCode linked to the coupon for single redemption. Default it is set to false.	✓
campaignId	Integer	The id of the campaign to issue against.	✓	✓
userRef	String	A unique user reference as on the issuer channel system. This reference will be used to restrict user limits on campaigns.	✓	✓
mobileNumber	String	The mobile number. The mobile number must be presented in International format.	✓	✓
smsMessage	String	The message to override original sms message with. Used in request only. The following hash-tag’s can be used: #WICODE (The wiCode), #MOBISITE (Will add a link to a generic mobisite for QR display.), #BALANCE (The value in Rand.) and #EXPIRY (Expiry date yyyy/mm/dd).	✓
sendSMS	Boolean	Indicates whether an SMS must be sent on issue or not.	✓	✓
additionalInfo	String	Any additional information the channel would like to store against the coupon can be placed in this list. It can then be retrieved by getting the coupon details when needed.		✓
serviceProviderId	Integer	If the campaign has an Airtime Reward linked to it the channel can provide the airtime service provider id. If no provider id specified, the system will try and issue against the most obvious airtime provider. If it fails it will try all others. Slightly slower than specifying the correct provider upfront.	✓	✓
id	Integer	The id of the coupon.		✓
campaignName	String	The name of the campaign.		✓
campaignType	String	The type of campaign. COUPON VOUCHER		✓
termsAndConditions	String	The terms and conditions of the coupon.		✓
numExpiryDays	Integer	The number of expiry days. Used in request only.	✓
createDate	String	The date the couponCampaign was created.		✓
description	String	A description of the campaign.		✓
imageURL	String	The image url of the coupon.		✓
redeemFromDate	String	From which date the coupon can be redeemed.		✓
redeemToDate	String	Until when the coupon is redeemable.		✓
wiCode	String	The wiCode linked to the user token.		✓
voucherAmount	Integer	The possible coupon redemption amount.		✓
wiQR	String	The wiCode linked to the user token.		✓

GET /coupons/{id}

# Example request

curl "https://za-vsp-int.wigroup.co/cvs-issuer/rest/coupons/{id}" \
  -H "apiId: {apiId}" \
  -H "apiPassword: {apiPassword}" \
  -H "Content-Type: application/json" \
  -X GET

# Example response

{
  “coupon“: {
    “id“: 171117,
    "userRef": "string",
    "mobileNumber": "string",
    “campaignId“: 4449,
    “campaignName“: "Integration Coupon R5",
    “campaignType“: "COUPON",
    “termsAndConditions“: "Integration Coupon R5",
    “createDate“: "2015-05-21T09:11:32+0200",
    “description“: "Integration Coupon R5",
    “imageUrl“: "http://qa.wigroup.co/wigroup/image_uploads/2015-05-21_071108.PNG",
    “redeemFromDate“: "2015-05-21T00:00:00+0200",
    “redeemToDate“: "2015-11-21T23:59:59+0200",
    “wiCode“: "902430319",
    "redeemedAmount": 100,
    “voucherAmount“: 500,
    “stateId“: "R",
    “redeemedDate“: "2015-05-21T09:13:17+0200"
  },
  “responseCode": "-1",
  “responseDesc“: "Success"
}

This call can be used to obtain information about a wiGroup Coupon or Voucher. The Coupon/Voucher ID is specified as a path parameter in this case.

Endpoint: {root}/coupons/{id}

Available methods: GET

Parameter	Type	Description	Response
id	Integer	The id of the coupon.	✓
userRef	String	A unique user reference as on the issuer channel system. This reference will be used to restrict user limits on campaigns.	✓
mobileNumber	String	The users mobile number, if available.	✓
campaignId	Integer	The id of the campaign to issue against.	✓
campaignName	String	The name of the campaign.	✓
campaignType	String	The type of campaign. COUPON VOUCHER	✓
termsAndConditions	String	The terms and conditions of the coupon.	✓
createDate	String	The date the couponCampaign was created.	✓
description	String	A description of the campaign.	✓
imageURL	String	The image url of the coupon.	✓
redeemFromDate	String	From which date the coupon can be redeemed.	✓
redeemToDate	String	Until when the coupon is redeemable.	✓
wiCode	String	The wiCode linked to the user token.	✓
redeemedAmount	Integer	The amount redeemed on the coupon.	✓
voucherAmount	Integer	The possible coupon redemption amount.	✓
stateId	String	The current state of the coupon. A (Active) D (Deactivated) E (Expired) R (Redeemed)	✓
redeemedDate	String	The date on which the coupon was redeemed (if it was expired).	✓
expiredDate	String	The on which the coupon expired.	✓

DELETE /coupons/{id}

# Example request

curl "https://za-vsp-int.wigroup.co/cvs-issuer/rest/coupons/{id}" \
  -H "id: {id}" \
  -H "apiId: {apiId}" \
  -H "apiPassword: {apiPassword}" \
  -H "Content-Type: application/json" \
  -X DELETE

# Example response

{
  “responseCode”: "-1",
  “responseDesc”: "Success"
}

This call can be used to expire (delete) a wiGroup Coupon or Voucher. The Coupon/Voucher ID is specified as a header parameter in this case. The funds will be returned to the campaign.

Endpoint: {root}/coupons/{id}

Available methods: DELETE

/coupontransactions

GET /coupontransactions


# Example request

curl "https://za-vsp-int.wigroup.co/cvs-issuer/rest/coupontransactions" \
  -H "apiId: {apiId}" \
  -H "apiPassword: {apiPassword}" \
  -H "Content-Type: application/json" \
  -X GET

# Example response

{
  “couponTransactions“: [ {
    “id“: 123499,
    “transactionId“: 101694,
    “couponId“: 183980,
    “wiCode“: "528626479",
    “userRef“: "VSP_User_Id_001",
    “merchantId“: 1050,
    “merchantName“: "Test Merchant",
    “retailerId“: 10,
    “retailerName“: "YourRetailer",
    “processedAmount“: 2500,
    “transactionDate“: "2015-07-23T14:07:24+0200",
    “interfaceIssuerId“: "AAIssuer",
    “issuerId“: 128,
    “stateId“: "S"
  }],
  “paging“:
  {
    “pageSize“: 20,
    “pageOffset“: 0,
    “numItemsOnPage“: 1,
    “numItemsInTotal“: 1,
    “numPages“: 1
  },
  “responseCode“: "-1",
  “responseDesc“: "Success"
}

This endpoint can be used to retrieve all coupon related transactions. If no filters are specified it will return all coupon transactions ordered by date.

Endpoint: {root}/coupontransactions

Available methods: GET

Parameter	Type	Description	Request	Response
transactionId	Integer	The top level transaction id. All transactions are linked to a high level transaction. The high level transaction groups multiple coupon transactions as well as gift card transactions	✓	✓
userRef	String	If the user reference is specified on transactions linked to the user will be returned.	✓	✓
couponId	Integer	To filter on specific coupon Id.	✓	✓
wiCode	String	The wiCode linked to the user token.		✓
campaignId	Integer	Filter transactions for specific campaign.	✓	✓
dateFrom	String	The date from which to return transactions.	✓
dateTo	String	The date to which to return transactions.	✓
id	Integer	The coupon transaction id.		✓
merchantId	Integer	The merchant id.		✓
merchantName	String	The merchant name.		✓
retailerId	Integer	The retailer id.		✓
retailerName	String	The retailer name.		✓
processedAmount	Integer	The processed amount.		✓
transactionDate	String	The transaction date.		✓
interfaceIssuerId	String	The id of the interface issuer.		✓
issuerId	String	The id of the issuer.		✓
stateId	Integer	The current transaction state. N (New) P (Processing) F (Failed) SPR (Successful pending recon) S (Successful) RV (Reversed)		✓

GET /coupontransactions/{id}


# Example request

curl "https://za-vsp-int.wigroup.co/cvs-issuer/rest/coupontransactions/{id}" \
  -H "apiId: {apiId}" \
  -H "apiPassword: {apiPassword}" \
  -H "Content-Type: application/json" \
  -X GET

# Example response

{
  “couponTransactions“: [ {
    “id“: 123499,
    “transactionId“: 101694,
    “couponId“: 183980,
    “wiCode“: "528626479",
    “userRef“: "VSP_User_Id_001",
    “merchantId“: 1050,
    “merchantName“: "Test Merchant",
    “retailerId“: 10,
    “retailerName“: "YourRetailer",
    “processedAmount“: 2500,
    “transactionDate“: "2015-07-23T14:07:24+0200",
    “interfaceIssuerId“: "AAIssuer",
    “issuerId“: 128,
    “stateId“: "S"
  }],
  “paging“:
  {
    “pageSize“: 20,
    “pageOffset“: 0,
    “numItemsOnPage“: 1,
    “numItemsInTotal“: 1,
    “numPages“: 1
  },
  “responseCode“: "-1",
  “responseDesc“: "Success"
}

This resource returns a specific coupon transaction.

Endpoint: {root}/coupontransactions/{id}

Available methods: GET

Parameter	Type	Description	Request	Response
id	Integer	The coupon transaction id.	✓	✓
transactionId	Integer	The top level transaction id. All transactions are linked to a high level transaction. The high level transaction groups multiple coupon transactions as well as gift card transactions		✓
couponId	Integer	To filter on specific coupon Id.		✓
wiCode	String	The wiCode linked to the user token.		✓
userRef	String	If the user reference is specified on transactions linked to the user will be returned.		✓
merchantId	Integer	The merchant id.		✓
merchantName	String	The merchant name.		✓
retailerId	Integer	The retailer id.		✓
retailerName	String	The retailer name.		✓
processedAmount	Integer	The processed amount.		✓
transactionDate	String	The transaction date.		✓
interfaceIssuerId	String	The id of the interface issuer.		✓
issuerId	String	The id of the issuer.		✓
stateId	Integer	The current transaction state. N (New) P (Processing) F (Failed) SPR (Successful pending recon) S (Successful) RV (Reversed)		✓

/giftcardcampaigns

This request returns a list of active campaigns which are linked to the specific channel (issuer interface).

GET /giftcardcampaigns


# Example request

curl "https://za-vsp-int.wigroup.co/cvs-issuer/rest/giftcardcampaigns" \
  -H "apiId: {apiId}" \
  -H "apiPassword: {apiPassword}" \
  -H "Content-Type: application/json" \
  -X GET

# Example response

{
  “giftcardCampaigns“: [ {
    “minValueAllowedToIssue“: 500,
    “maxValueAllowedToIssue“: 500,
    “totalAmountIssued“: 500,
    “totalAmountRedeemed“: 6000,
    “id“: 4420,
    “name“: "Gift Card R5",
    “description“: "Gift Card R5",
    “termsAndConditions“: "VSP T&Cs",
    “imageURL”: "http://goo.gl/Zodst9",
    “createDate“: "2015-05-21T07:14:01+0200",
    “requireUserRef“: false,
    “allowedUsersRestricted“: false,
    “maxNumberPerUser“: 0,
    “maxLivePerUser“: 0,
    “campaignType“: "GIFTCARD",
    “minRank“: 2,
    “categories“: [   {
      “name“: "All",
      “id“: 807,
      “rank“: 3
    }],
    “totalLive“: 1,
    “totalRedeemed“: 6000,
    “totalExpired“: 1,
    “totalIssued“: 14,
    “campaignInfo“: [{
      “name“: "Adword",
      “value“: "Integration,Gift,Card,R5,Integration Gift Card R5"
    }],
    “stateId“: "A",
    "allowExpiryDateOverride": false,
    "expiryDays": 1095
  }],
  “paging“:   {
    “pageSize“: 20,
    “pageOffset“: 0,
    “numItemsOnPage“: 1,
    “numItemsInTotal“: 1,
    “numPages“: 1
  },
  “responseCode“: "-1",
  “responseDesc“: "Success"
}

This endpoint returns all the active Gift Card campaigns which can be issued against. A campaign can be issued against if it has the required min float and the user has not yet reached the max allowed per user limit.

Available methods: GET

All requested parameters, except the API credentials, are query parameters.

Parameter	Type	Description	Request	Response
id	Integer	The id of the campaign.	✓	✓
adwords	List	List of adwords linked to the campaign. Adwords are special search key words which when setup against a campaign can be used to filter the campaign.	✓
categoryIds	List	A list of category id’s. It will return campaigns which match any of the categories supplied.	✓
merchantId	Integer	A merchant id to filter campaigns on.	✓
provinceId	Integer	A province id to filter campaigns on.	✓
countryId	Integer	A country id to filter campaigns on.	✓
retailerId	Integer	A retailer id to filter campaigns on.	✓
longitude	Double	A longitude position. Required for distance calculation. Both longitude and latitude need to be specified together.	✓
latitude	Double	A latitude position. Required for distance calculation. Both longitude and latitude need to be specified together.	✓
userRef	String	A unique user reference. When specified only campaigns on which the user can still be issued coupons will be returned.	✓
includeRedeemableForUser	Boolean	Whether to include campaigns which the user has unredeemed coupons/voucher, but cannot get anymore issued. Normally the campaign would drop off the list as soon as the user cannot be issued anymore. Must be used in conjunction with the userRef field	✓
minValueAllowedToIssue	Integer	The minimum value of a giftcard that can be issued.		✓
maxValueAllowedToIssue	Integer	The maximum value of a giftcard that can be issued.		✓
totalAmountIssued	Integer	The total amount(cent) issued to giftcards.		✓
totalAmountRedeemed	Integer	The total amount(cent) redeemed on campaign.		✓
allowedExpiryDateOverride	Boolean	Whether the expiry date may be override		✓
name	String	The name of the giftcard campaign.		✓
description	String	The description of the giftcard campaign.		✓
termsAndConditions	String	The terms and conditions of the giftcard campaign.		✓
imageUrl	String	The image url of the giftcard campaign.		✓
createDate	String	The date the giftcard campaign was created.		✓
requireUserRef	Boolean	True if a userRef is required for giftcard campaign.		✓
allowedUsersRestricted	Boolean	Whether only the users linked to the campaigns are able to view the contents of the campaign.		✓
maxLivePerUser	Integer	The maximum allowed live(issued and not redeemed/expired) per user.		✓
maxNumberPerUser	Integer	The maximum number allowed per user.		✓
campaignType	String	The campaign type. GIFTCARD		✓
minRank	Integer	The minimum rank of the giftcard campaign.		✓
categories	Object	List of category details. Each entry consists of a name (String), id (Integer) and description (Long).		✓
distance	Double	The distance to the closest merchant.		✓
totalExpired	Integer	The total number of giftcards expired.		✓
totalIssued	Integer	The total number of giftcards issued (live + redeemed).		✓
totalLive	Integer	The total number of live (active) giftcards.		✓
totalRedeemed	Integer	The total number of giftcards redeemed.		✓
campaignInfo	Object	List of campaign info details. Each entry consists of a campaign name (String) and a campaign info value (String).		✓
stateId	String	The current state of the giftcard. A (Active) D (Deactivated) E (Expired) R (Redeemed fully)		✓
allowExpiryDateOverride	Boolean	Whether the campaign allowes the default expiry days to be overwritten on issue.		✓
expiryDays	Integer	The default number of days the coupon will be valid for from issue date. The expiry date will be set to midnight x days from issue date.		✓

GET /giftcardcampaigns/{id}


# Example request

curl "https://za-vsp-int.wigroup.co/cvs-issuer/rest/giftcardcampaigns/{id}" \
  -H "apiId: {apiId}" \
  -H "apiPassword: {apiPassword}" \
  -H "Content-Type: application/json" \
  -X GET

# Example response

{
  “giftcardCampaigns“: [ {
    “minValueAllowedToIssue“: 500,
    “maxValueAllowedToIssue“: 500,
    “totalAmountIssued“: 500,
    “totalAmountRedeemed“: 6000,
    “id“: 4420,
    “name“: "Gift Card R5",
    “description“: "Gift Card R5",
    “termsAndConditions“: "VSP T&Cs",
    “imageURL”: "http://goo.gl/Zodst9",
    “createDate“: "2015-05-21T07:14:01+0200",
    “requireUserRef“: false,
    “allowedUsersRestricted“: false,
    “maxNumberPerUser“: 0,
    “maxLivePerUser“: 0,
    “campaignType“: "GIFTCARD",
    “minRank“: 2,
    “categories“: [ {
      “name“: "All",
      “id“: 807,
      “rank“: 3
    }],
    “totalLive“: 1,
    “totalRedeemed“: 6000,
    “totalExpired“: 1,
    “totalIssued“: 14,
    “campaignInfo“: [{
      “name“: "Adword",
      “value“: "Integration,Gift,Card,R5,Integration Gift Card R5"
    }],
    “stateId“: "A",
    "allowExpiryDateOverride": false,
    "expiryDays": 1095
  }],
  “paging“:
  {
    “pageSize“: 20,
    “pageOffset“: 0,
    “numItemsOnPage“: 1,
    “numItemsInTotal“: 1,
    “numPages“: 1
  },
  “responseCode“: "-1",
  “responseDesc“: "Success"
}

private static final String cvs_URI = "https://za-vsp-int.wigroup.co/cvs-issuer/rest/";

private static void getGiftCardCampaigns() throws JSONException {
  JSONObject jsonReply = null;
  String path = "giftcardcampaigns/" + id;
    // Construct and create web resource call
  Client client = Client.create(clientConfig);
  webResource = client.resource(cvs_URI).path(path);
  ClientResponse response = webResource.type(MediaType.APPLICATION_JSON)
    .header("apiId", cvsApiId)
    .header("apiPassword", cvsApiPasswd)
    .get(ClientResponse.class);
  try {
    jsonReply = new JSONObject(response.getEntity(String.class));
    JSONArray couponCampaigns = jsonReply.getJSONArray("giftcardCampaigns");
    System.out.println("Response from cvs: " + jsonReply);        
    for(int i=0 ; i< couponCampaigns.length(); i++){    
      JSONObject jsonObject = couponCampaigns.getJSONObject(i);  
      System.out.println("Name " + i + ": " + jsonObject.getString("name"));
    }
  }
  catch (ClientHandlerException | UniformInterfaceException e) {
    System.err.println("Some exception caught while performing getGiftCardCampaigns call " + e);
  }
}

Available methods: GET

Parameter	Type	Description	Request	Response
id	Integer	The id of the campaign.	✓	✓
minValueAllowedToIssue	Integer	The minimum value of a giftcard that can be issued.		✓
maxValueAllowedToIssue	Integer	The maximum value of a giftcard that can be issued.		✓
totalAmountIssued	Integer	The total amount(cent) issued to giftcards.		✓
totalAmountRedeemed	Integer	The total amount(cent) redeemed on campaign.		✓
allowedExpiryDateOverride	Boolean	Whether the expiry date may be override		✓
name	String	The name of the giftcard campaign.		✓
description	String	The description of the giftcard campaign.		✓
termsAndConditions	String	The terms and conditions of the giftcard campaign.		✓
imageUrl	String	The image url of the giftcard campaign.		✓
createDate	String	The date the giftcard campaign was created.		✓
requireUserRef	Boolean	True if a userRef is required for giftcard campaign.		✓
allowedUsersRestricted	Boolean	Whether only the users linked to the campaigns are able to view the contents of the campaign.		✓
maxLivePerUser	Integer	The maximum allowed live(issued and not redeemed/expired) per user.		✓
maxNumberPerUser	Integer	The maximum number allowed per user.		✓
campaignType	String	The campaign type. GIFTCARD		✓
minRank	Integer	The minimum rank of the giftcard campaign.		✓
categories	Object	List of category details. Each entry consists of a name (String), id (Integer) and description (Long).		✓
distance	Double	The distance to the closest merchant.		✓
totalExpired	Integer	The total number of giftcards expired.		✓
totalIssued	Integer	The total number of giftcards issued (live + redeemed).		✓
totalLive	Integer	The total number of live (active) giftcards.		✓
totalRedeemed	Integer	The total number of giftcards redeemed.		✓
campaignInfo	Object	List of campaign info details. Each entry consists of a campaign name (String) and a campaign info value (String).		✓
stateId	String	The current state of the giftcard. A (Active) D (Deactivated) E (Expired) R (Redeemed fully)		✓
allowExpiryDateOverride	Boolean	Whether the campaign allowes the default expiry days to be overwritten on issue.		✓
expiryDays	Integer	The default number of days the coupon will be valid for from issue date. The expiry date will be set to midnight x days from issue date.		✓

/giftcards

This resource is used to issue a giftcard. Depending on how the campaign is setup by the campaign owner, the channel can set the balance and expiry date of the giftcard. A giftcard can be redeemed multiple times.

POST /giftcards


# Example request

curl "https://za-vsp-int.wigroup.co/cvs-issuer/rest/giftcards?issueWiCode=true" \
  -H "apiId: {apiId}" \
  -H "apiPassword: {apiPassword}" \
  -H "Content-Type: application/json" \
  -X POST \
  -d '{
       "campaignId": "9000",
       "balance": "2000"
       "userRef": "VSP_User_Id_001",
       "mobileNumber": "string",
       "numExpiryDays": 3,
       "smsMessage": "Dear Customer. You have #BALANCE value to spend. wiCode: #WICODE. Expires: #EXPIRY.",
       "sendSMS": boolean,
       "sendFollowUpSMS": boolean,
       "stateId": "A"
     }'

# Example response

{
  “giftcard”: {
    “id”: 20,
    “campaignId”: 9000,
    “interfaceIssuerId”: "TestChannel",
    “issuerId”: 94,
    “userRef”: "VSP_User_Id_001",
    “mobileNumber”: "string",
    “sendSMS”: boolean,
    “sendFollowUpSMS”: boolean,
    “issuedAmount”: 2000,
    “redeemedAmount”: 0,
    “expiredAmount”: 0,
    “balance”: 2000,
    “createDate”: "2015-03-13T15:10:07+0200",
    “expiryDate”: "2018-03-12T23:59:59+0200",
    “campaignName”: "VSPTestGiftCardCampaign",
    “campaignType”: "GIFTCARD",
    “description”: "Gift Card worth R20.00",
    “imageURL”: "http://goo.gl/Zodst9",
    “termsAndCondition: "VSP T&Cs",
    “stateId”: "A",
    “wicode”: "123456789999"
  },
  “responseCode”: "-1",
  “responseDesc”: "Success"
}

Issuing a Gift card is a simple API call. Three parameters must be supplied: campaignID, balance and userRef. Each time this API is called a Gift card is issued against the userRef and the campaignID. If issueWicode is set to true, a wiCode will be issued for the gift card right away. If not, a wiCode can be issued using the issueGiftCardWicode API call.

A Gift Card can be ISSUED in a De-Activated State, then activated later via the portal or API call.

Endpoint: {root}/giftcards

Available methods: POST

Parameter	Type	Description	Request	Response
issueWiCode	Boolean (query)	True if to issue wicode, otherwise false.	✓
campaignId	Integer	The id of the campaign to issue against.	✓	✓
balance	Integer	The amount to issue on giftcard. The balance needs to be within the min and max boundaries of the campaign and the campaign must have the required float available.	✓	✓
userRef	String	A unique user reference as on the issuer channel system. This reference will be used to restrict user limits on campaigns.	✓	✓
mobileNumber	String	The mobile number. The mobile number must be presented in International format.	✓	✓
smsMessage	String	The message to override original sms message with. Used in request only. The following hash-tag’s can be used: #WICODE (The wiCode), #MOBISITE (Will add a link to a generic mobisite for QR display.), #BALANCE (The value in Rand.) and #EXPIRY (Expiry date yyyy/mm/dd).	✓
sendSMS	Boolean	Indicates whether an SMS must be sent on issue or not.	✓	✓
sendFollowUpSMS	Boolean	Indicates whether a follow-up SMS must be sent if the user partially redeems their gift card.	✓	✓
numExpiryDays	Integer	If allowed by campaign the channel can override the default expiry days. It will still be capped by the default campaign value.	✓
id	Integer	The id of the gift card.		✓
interfaceIssuerId	Integer	The interface issuer id.		✓
issuerId	Integer	The issuer id.		✓
issuedAmount	Integer	The issued amount.		✓
redeemedAmount	Integer	The amount redeemed on the giftcard.		✓
expiredAmount	Integer	The amount expired on the giftcard.		✓
createDate	String	The create date of the giftcard.		✓
expiredDate	String	The on which the gift card expired.		✓
campaignName	String	The name of the campaign.		✓
campaignType	String	The type of campaign. GIFTCARD		✓
description	String	A description of the campaign.		✓
imageUrl	String	The image url of the gift card.		✓
termsAndConditions	String	The terms and conditions of the gift card.		✓
stateId	String	The current state of the giftcard. You can issue a Gift Card in a de-activated state if you set the stateId to “D” in the Request. A (Active) D (Deactivated) E (Expired) R (Redeemed fully)	✓	✓

POST /giftcards/{id}/wicode


# Example request

curl "https://za-vsp-int.wigroup.co/cvs-issuer/rest/giftcards/{id}/wicode" \
  -H "id: {id}" \
  -H "apiId: {apiId}" \
  -H "apiPassword: {apiPassword}" \
  -H "Content-Type: application/json" \
  -X POST

# Example response

{
   "token":    {
      "userRef": "string",
      "wiCode": "123456789999",
      "createDate": "2016-07-06T12:05:10+0200",
      "validTillDate": "2019-07-06T23:59:59+0200",
      "lastModifiedDate": "2016-07-06T12:05:10+0200",
      "stateId": "A"
   },
   "responseCode": "-1",
   "responseDesc": "Success"
}

This resource is used to issue a wicode against giftcard for length of giftcard expiry. A wicode will only be issued if no wicode is linked to giftcard.

Endpoint: {root}/giftcards/{id}/wicode

Available methods: POST

Parameter	Type	Description	Response
userRef	String	A unique user reference as on the issuer channel system. This reference will be used to restrict user limits on campaigns.	✓
wiCode	String	The wiCode.	✓
createDate	String	The create date.	✓
validTillDate	String	The date the wicode is valid to.	✓
lastModifiedDate	String	The last modified date.	✓
stateId	String	The state.	✓

GET /giftcards/{id}


# Example request

curl "https://za-vsp-int.wigroup.co/cvs-issuer/rest/giftcards/{id}" \
  -H "id: {id}" \
  -H "apiId: {apiId}" \
  -H "apiPassword: {apiPassword}" \
  -H "Content-Type: application/json" \
  -X GET

# Example response

{
  “giftcard“: {
    “id“: 615,
    “campaignId“: 4455,
    “interfaceIssuerId“: "SnapAndSaveIssuer",
    “issuerId“: 146,
    “userRef“: "string",
    “mobileNumber“: "string",
    “issuedAmount“: 500,
    “redeemedAmount“: 500,
    “expiredAmount“: 0,
    “balance“: 0,
    “createDate“: "2015-05-25T11:41:51+0200",
    “expiryDate“: "2015-05-25T23:59:59+0200",
    “campaignName“: "Snap and Save Gift Card",
    “campaignType“: "GIFTCARD",
    “description“: "Snap and Save Gift Card",
    “termsAndConditions“: "Snap and Save Gift Card",
    “stateId“: "R",
    "wicode": "1234567"
  },
  “responseCode": "-1",
  “responseDesc": "Success"
}

This call can be used to retrieve (get) a wiGroup Gift Card. The giftcard id is specified as a header parameter in this case.

Endpoint: {root}/giftcards/{id}

Available methods: GET

Parameter	Type	Description	Request	Response
id	Integer	The id of the gift card.	✓	✓
campaignId	Integer	The id of the campaign to issue against.		✓
interfaceIssuerId	Integer	The interface issuer id.		✓
issuerId	Integer	The issuer id.		✓
userRef	String	A unique user reference as on the issuer channel system. This reference will be used to restrict user limits on campaigns.		✓
mobileNumber	String	The users mobile number, if available.		✓
issuedAmount	Integer	The issued amount.		✓
redeemedAmount	Integer	The amount redeemed on the giftcard.		✓
expiredAmount	Integer	The amount expired on the giftcard.		✓
balance	Integer	The amount to issue on giftcard. The balance needs to be within the min and max boundaries of the campaign and the campaign must have the required float available.		✓
createDate	String	The create date of the giftcard.		✓
expiredDate	String	The on which the gift card expired.		✓
campaignName	String	The name of the campaign.		✓
campaignType	String	The type of campaign. GIFTCARD		✓
description	String	A description of the campaign.		✓
imageUrl	String	The image url of the gift card.		✓
termsAndConditions	String	The terms and conditions of the gift card.		✓
stateId	String	The current state of the giftcard. A (Active) D (Deactivated) E (Expired) R (Redeemed fully)		✓

DELETE /giftcards/{id}


# Example request

curl "https://za-vsp-int.wigroup.co/cvs-issuer/rest/giftcards/{id}" \
  -H "id: {id}" \
  -H "apiId: {apiId}" \
  -H "apiPassword: {apiPassword}" \
  -H "Content-Type: application/json" \
  -X DELETE

# Example response

{
  “responseCode”: "-1",
  “responseDesc”: "Success"
}

This call can be used to expire (delete) a wiGroup Gift Card. The giftcard id is specified as a header parameter in this case.

Endpoint: {root}/giftcards/{id}

Available methods: DELETE

/giftcardtransactions

GET /giftcardtransactions


# Example request

curl "https://za-vsp-int.wigroup.co/cvs-issuer/rest/giftcardtransactions" \
  -H "apiId: {apiId}" \
  -H "apiPassword: {apiPassword}" \
  -H "Content-Type: application/json" \
  -X GET

# Example response

{
  “giftcardTransactions“: [ {
    “id“: 123499,
    “transactionId“: 101694,
    “giftcardId“: 183980,
    “userRef“: "VSP_User_Id_001",
    “merchantId“: 1050,
    “merchantName“: "Test Merchant",
    “retailerId“: 10,
    “retailerName“: "YourRetailer",
    “processedAmount“: 2500,
    “transactionDate“: "2015-07-23T14:07:24+0200",
    “interfaceIssuerId“: "AAIssuer",
    “issuerId“: 128,
    “stateId“: "S"
  }],
  “paging“:
  {
    “pageSize“: 20,
    “pageOffset“: 0,
    “numItemsOnPage“: 1,
    “numItemsInTotal“: 1,
    “numPages“: 1
  },
  “responseCode“: "-1",
  “responseDesc“: "Success"
}

This endpoint can be used to retrieve all giftcard related transactions. If no filters are specified it will return all giftcard transactions ordered by date.

Endpoint: {root}/giftcardtransactions

All request parameters, except the API credentials, are query parameters.

Available methods: GET

Parameter	Type	Description	Request	Response
transactionId	Integer	The top level transaction id. All transactions are linked to a high level transaction. The high level transaction groups multiple giftcard transactions as well as gift card transactions	✓	✓
userRef	String	If the user reference is specified on transactions linked to the user will be returned.	✓	✓
giftcardId	Integer	To filter on specific giftcard Id.	✓	✓
campaignId	Integer	Filter transactions for specific campaign.	✓	✓
dateFrom	String	The date from which to return transactions.	✓
dateTo	String	The date to which to return transactions.	✓
id	Integer	The giftcard transaction id.		✓
merchantId	Integer	The merchant id.		✓
merchantName	String	The merchant name.		✓
retailerId	Integer	The retailer id.		✓
retailerName	String	The retailer name.		✓
processedAmount	Integer	The processed amount.		✓
transactionDate	String	The transaction date.		✓
interfaceIssuerId	String	The id of the interface issuer.		✓
issuerId	String	The id of the issuer.		✓
stateId	Integer	The current transaction state. N (New) P (Processing) F (Failed) SPR (Successful pending recon) S (Successful) RV (Reversed)		✓

GET /giftcardtransactions/{id}


# Example request

curl "https://za-vsp-int.wigroup.co/cvs-issuer/rest/giftcardtransactions/{id}" \
  -H "apiId: {apiId}" \
  -H "apiPassword: {apiPassword}" \
  -H "Content-Type: application/json" \
  -X GET

# Example response

{
  “giftcardTransactions“: [ {
    “id“: 123499,
    “transactionId“: 101694,
    “giftcardId“: 183980,
    “userRef“: "VSP_User_Id_001",
    “merchantId“: 1050,
    “merchantName“: "Test Merchant",
    “retailerId“: 10,
    “retailerName“: "YourRetailer",
    “processedAmount“: 2500,
    “transactionDate“: "2015-07-23T14:07:24+0200",
    “interfaceIssuerId“: "AAIssuer",
    “issuerId“: 128,
    “stateId“: "S"
  }],
  “paging“:
  {
    “pageSize“: 20,
    “pageOffset“: 0,
    “numItemsOnPage“: 1,
    “numItemsInTotal“: 1,
    “numPages“: 1
  },
  “responseCode“: "-1",
  “responseDesc“: "Success"
}

This resource returns a specific the giftcard transaction.

Endpoint: {root}/giftcardtransactions/{id}

Available methods: GET

Parameter	Type	Description	Request	Response
id	Integer	The top level transaction id. All transactions are linked to a high level transaction. The high level transaction groups multiple giftcard transactions as well as gift card transactions.	✓	✓
userRef	String	If the user reference is specified on transactions linked to the user will be returned.		✓
giftcardId	Integer	To filter on specific giftcard Id.		✓
campaignId	Integer	Filter transactions for specific campaign.		✓
dateFrom	String	The date from which to return transactions.		✓
dateTo	String	The date to which to return transactions.		✓
id	Integer	The giftcard transaction id.		✓
merchantId	Integer	The merchant id.		✓
merchantName	String	The merchant name.		✓
retailerId	Integer	The retailer id.		✓
retailerName	String	The retailer name.		✓
processedAmount	Integer	The processed amount.		✓
transactionDate	String	The transaction date.		✓
interfaceIssuerId	String	The id of the interface issuer.		✓
issuerId	String	The id of the issuer.		✓
stateId	Integer	The current transaction state. N (New) P (Processing) F (Failed) SPR (Successful pending recon) S (Successful) RV (Reversed)		✓

/campaigns

GET /campaigns/{campaignId}/metadata


# Example request

curl "https://za-vsp-int.wigroup.co/cvs-issuer/rest/campaigns/{campaignId}/metadata" \
  -H "apiId: {apiId}" \
  -H "apiPassword: {apiPassword}" \
  -H "Content-Type: application/json" \
  -X GET

# Example response

{
  "campaignsMetadata": [
  {
    "name": "Kauai",
    "value": "Smoothie"
  },
  {
    "name": "Kauai",
    "value": "Food"
  }],
  "paging":    {
       "pageSize": 20,
       "pageOffset": 0,
       "numItemsOnPage": 2,
       "numItemsInTotal": 2,
       "numPages": 1
    },
    "responseCode": "-1",
    "responseDesc": "Success",
    "httpStatusCode": 200
 }

This API call can be used to retrieve all metadata entries linked to the given campaign.

Meta-data is additional information stored against the campaign by the Campaign Owner. This is configured during campaign setup. Typical use cases would be to store an external system campaign identifier or to store additional tags against the campaign to help the application group campaigns.

Endpoint: {root}/campaigns

Available Methods: GET

Parameter	Type	Description	Request	Response
campaignId	Integer	Filter metadata for specific campaign.	✓
name	String	The name of the key value pair.		✓
value	String	The value of the key value pair.		✓

/users

POST /user/{userRef}/token

Case 1 – Single Gift Card and Two Vouchers:


# Example request

curl "https://za-vsp-int.wigroup.co/cvs-issuer/rest/user/{userRef}/token" \
  -H "apiId: {apiId}" \
  -H "apiPassword: {apiPassword}" \
  -H "Content-Type: application/json" \
  -X POST
  -d '{
       “giftcardIds”: [“20”],
       “couponIds”: [“55”, “56”],
       “campaignType”: “VOUCHER”,
       "mobileNumber": "string"
     }'

# Example response

{
  token: {
    “userRef”: "VSP_User_Id_001",
    “mobileNumber”: "string",
    “campaignType”: "VOUCHER",
    “wiCode”: "1122345",
    “wiQR”: "1122345",
    “couponIds”:
    [
      55,
      56
    ],
    “giftcardIds”:
    [
      20
    ],
    “createDate”: "2015-03-13T14:22:52+0200",
    “validTillDate”: "2015-03-14T23:59:59+0200",
    “lastModifiedDate”: "2015-03-13T14:27:08+0200",
    “stateId”: "A"
    },
  “responseCode”: "-1",
  “responseDesc”: "Success"
}

Case 2 – Set of Gift Cards, a Two Coupons and a Voucher:


# Example request

curl "https://za-vsp-int.wigroup.co/cvs-issuer/rest/user/{userRef}/token" \
  -H "apiId: {apiId}" \
  -H "apiPassword: {apiPassword}" \
  -H "Content-Type: application/json" \
  -X POST
  -d '{
       “giftcardIds”: [“20”, “21”, “22”],
       “couponIds”: [“101”, “102”, “55”],
       “campaignType”: “COUPONVOUCHER”,
       "mobileNumber": "string"
     }'

# Example response

{
  token: {
    “userRef”: "VSP_User_Id_001",
    “mobileNumber”: "string"
    “campaignType”: "COUPONVOUCHER",
    “wiCode”: "6786789",
    “wiQR”: "6786789",
    “couponIds”:
    [
      55,
      101,
      102
    ],
    “giftcardIds”:
    [
      20,
      21,
      22
    ],
    “createDate”: "2015-03-13T14:22:52+0200",
    “validTillDate”: "2015-03-14T23:59:59+0200",
    “lastModifiedDate”: "2015-03-13T14:27:08+0200",
    “stateId”: "A"
    },
  “responseCode”: "-1",
  “responseDesc”: "Success"
}

Case 3 – Coupon (all Coupons across any campaigns available to the userRef):


# Example request

curl "https://za-vsp-int.wigroup.co/cvs-issuer/rest/user/{userRef}/token" \
  -H "apiId: {apiId}" \
  -H "apiPassword: {apiPassword}" \
  -H "Content-Type: application/json" \
  -X POST
  -d '{
       “couponCampaignIds”: [“-1”],
       “campaignType”: “COUPON”,
       "mobileNumber": "string"
     }'

# Example response

{
  token: {
    “userRef”: "VSP_User_Id_001",
    “mobileNumber”: "string"
    “campaignType”: "COUPON",
    “wiCode”: "3334567",
    “wiQR”: "3335678",
    “couponCampaignIds”:
    [
      -1
    ],
    “createDate”: "2015-03-13T14:22:52+0200",
    “validTillDate”: "2015-03-14T23:59:59+0200",
    “lastModifiedDate”: "2015-03-13T14:27:08+0200",
    “stateId”: "A"
    },
  “responseCode”: "-1",
  “responseDesc”: "Success"
}

To redeem coupons or giftcards not issued with their own wiCode a user token must be created. This token specifies what must considered on redemption. The token will be valid for up to 48 hours (today and tomorrow). A token can only be used for one transaction. The data linked to the token can be changed at any stage by recreating the token. To create the token you need to specify what to redeem. There are three lists which define what to redeem (couponCampaignIds, couponIds, giftcardIds), at least one must be specified. During redemption the system will first redeem against the couponCampaignIds list, then the couponIds, and finally the giftcardIds list. This is so that discounts are redeemed first, then vouchers/coupons issued to the user and then finally it will deduct the remaining value from the giftcards. If the list is not specified the redemption step for that list will be skipped. If you want to redeem against anything in that list rather than specify specific Ids, you can specify the wildcard [‑1] as the only value in the list. If you want to limit the list, you must specify the specific ids to take into account.

The primary function of setUserToken is to reserve a Token against a specific user. Its secondary function is to associate the Token with a CVS item, i.e. Gift Card or Coupon. Depending on the body parameters provided, setUserToken allows a great deal of flexibility in the way discounts are redeemed. This adds internal complexity to CVS, but simplifies the redemption process for client applications.

It is assumed that when a user registers on the VSP they are assigned a unique identifier, e.g. “VSP_User_001”, this identifier should be sent across by the VSP application servers to CVS as the userRef parameter. When the setUserToken call is made a Token is issued against this userRef.

When a User Token is created the IDs must be specified of the Coupons, Vouchers and Gift Cards that is required to be processed. The Campaign IDs may alternatively also be specified. A single ID may be specified or multiple IDs may be provided in the form of an array consisting of the IDs in String format. In the case where all issued Coupons, Vouchers or Gift Cards are issued against the user must be redeemed, [“-1”], should be presented in the JSON body of the request.

Furthermore, a Campaign Type has to be provided, which must be either: “COUPON”, “VOUCHER” or “COUPONVOUCHER”. The Campaign Type COUPONVOUCHER captures both Coupons and Vouchers issued against the user. The Campaign Type will have no effect on the redemption of issued Gift Cards – it will only have an impact on Coupons and Vouchers.

Endpoint: {root}/users/{userRef}/token

Available methods: POST

Parameter	Type	Description	Request	Response
userRef	String	A unique user reference as on the issuer channel system. This reference will be used to restrict user limits on campaigns.	✓	✓
mobileNumber	String	The mobile number. The mobile number must be presented in International format.	✓	✓
couponCampaignIds	Array[String], null if none, [“-1”] if all campaigns	The list of coupon campaign id’s which during redemption phase will be issued to the user and redeemed.	✓	✓
couponIds	Array[String], null if none, [“-1”] if all campaigns	The list of coupon id’s already issued to the user to redeem if possible.	✓	✓
giftcardIds	Array[String], null if none, [“-1”] if all campaigns	The list of giftcard id’s already issued to the user to redeem if possible.	✓	✓
campaignType	String	The campaign type issued against for couponCampaignIds list or couponIds list. COUPON VOUCHER COUPONVOUCHER	✓	✓
wiCode	String	The wiCode linked to the user token.		✓
wiQR	String	The wiCode linked to the user token.		✓
createDate	String	The date token was created.		✓
validTillDate	String	The date the wiCode will be valid to.		✓
lastModifiedDate	String	The date last modified.		✓
redeemedAmount	Integer	The amount redeemed on the coupon.		✓
stateId	String	The current state of the giftcard. A (Active) D (Deactivated) E (Expired) R (Redeemed)		✓

GET /user/{userRef}/token


# Example request

curl "https://za-vsp-int.wigroup.co/cvs-issuer/rest/user/{userRef}/token" \
  -H "apiId: {apiId}" \
  -H "apiPassword: {apiPassword}" \
  -H "Content-Type: application/json" \
  -X GET

# Example response

{
  token: {
    “userRef”: "VSP_User_Id_001",
    "mobileNumber": "string",
    “campaignType”: "VOUCHER",
    “wiCode”: "1122345",
    “wiQR”: "1122345",
    “couponIds”:
    [
      55,
      56
    ],
    “giftcardIds”:
    [
      20
    ],
    “createDate”: "2015-03-13T14:22:52+0200",
    “validTillDate”: "2015-03-14T23:59:59+0200",
    “lastModifiedDate”: "2015-03-13T14:27:08+0200",
    “stateId”: "A"
    },
  “responseCode”: "-1",
  “responseDesc”: "Success"
}

A token can also be retrieved.

Endpoint: {root}/users/{userRef}/token

Available methods: GET

Parameter	Type	Description	Request	Response
userRef	String	A unique user reference as on the issuer channel system. This reference will be used to restrict user limits on campaigns.	✓	✓
mobileNumber	String	The users mobile number, if available.		✓
couponCampaignIds	Array[String], null if none, [“-1”] if all campaigns	The list of coupon campaign id’s which during redemption phase will be issued to the user and redeemed.		✓
couponIds	Array[String], null if none, [“-1”] if all campaigns	The list of coupon id’s already issued to the user to redeem if possible.		✓
giftcardIds	Array[String], null if none, [“-1”] if all campaigns	The list of giftcard id’s already issued to the user to redeem if possible.		✓
campaignType	String	The campaign type. COUPON VOUCHER COUPONVOUCHER		✓
wiCode	String	The wiCode linked to the user token.		✓
wiQR	String	The wiCode linked to the user token.		✓
createDate	String	The date token was created.		✓
validTillDate	String	The date the wiCode will be valid to.		✓
lastModifiedDate	String	The date last modified.		✓
redeemedAmount	Integer	The amount redeemed on the coupon.		✓
stateId	String	The current state of the giftcard. A (Active) D (Deactivated) E (Expired) R (Redeemed)		✓

DELETE /user/{userRef}/token


# Example request

curl "https://za-vsp-int.wigroup.co/cvs-issuer/rest/user/{userRef}/token" \
  -H "apiId: {apiId}" \
  -H "apiPassword: {apiPassword}" \
  -H "Content-Type: application/json" \
  -X DELETE

# Example response

{
  “responseCode”: "-1",
  “responseDesc”: "Success"
}

A token can also be expired for safety should the user no longer want to transact.

Endpoint: {root}/users/{userRef}/token

Available methods: DELETE

GET /users/{userRef}/transactions


# Example request

curl "https://za-vsp-int.wigroup.co/cvs-issuer/rest/users/{userRef}/transactions" \
  -H "apiId: {apiId}" \
  -H "apiPassword: {apiPassword}" \
  -H "Content-Type: application/json" \
  -X GET

# Example response

{  
  “transactions”: {[
    “id“: 101694,
    “wiCode“: "528626479",
    “userRef“: "VSP_User_Id_001",
    “merchantId“: 1050,
    “merchantName“: "Test Merchant",
    “retailerId“: 10,
    “retailerName“: "wiGroup Retailer",
    “processedAmount“: 2500,
    “numberOfCoupons“: 1,
    “numberOfGiftcards“: 0,
    “totalCouponProcessedAmount“: 2500,
    “totalGiftcardProcessedAmount“: 0,
    “transactionDate“: "2015-07-23T14:07:24+0200",
    “interfaceIssuerId“: "VSPIssuer",
    “issuerId“: 128,
    “stateId“: "S"
  }]
  ,
  “paging“:    {
    “pageSize“: 10,
    “pageOffset“: 0,
    “numItemsOnPage“: 1,
    “numItemsInTotal“: 1,
    “numPages“: 1
  },
  “responseCode”: "-1",
  “responseDesc”: "Success"
}

This resource denotes the top level transactions for a specific user. It will indicate how many coupon and giftcard transactions was processed on the transaction.

Endpoint: {root}/users/{userRef}/transactions

Available methods: GET

All request parameters, except the API credentials, are query parameters.

Parameter	Type	Description	Request	Response
userRef	String	The user reference to filter on.	✓	✓
wiCode	String	To filter transaction on specific wiCode.	✓	✓
dateFrom	String	The date from which to return transactions.	✓
dateTo	String	The date to which to return transactions.	✓
id	Integer	The transaction id.		✓
merchantId	Integer	The merchant id.		✓
merchantName	String	The merchant name.		✓
retailerId	Integer	The retailer id.		✓
retailerName	String	The retailer name.		✓
processedAmount	Integer	The total processed amount for all linked coupon and giftcard transactions.		✓
numberOfCoupons	Integer	The number of coupons redeemed on transaction.		✓
numberOfGiftcards	Integer	The number of giftcards redeemed on transaction.		✓
totalCouponProcessedAmount	Integer	The total processed amount from coupon redemptions.		✓
totalGiftcardProcessedAmount	Integer	The total processed amount from giftcard redemptions.		✓
transactionDate	String	The transaction date.		✓
interfaceIssuerId	Integer	The transaction id.		✓
issuerId	Integer	The id of the issuer.		✓
stateId	String	The current transaction state. N (New) P (Processing) F (Failed) SPR (Successful pending recon) S (Successful)		✓

GET /users/{userRef}/coupons


# Example request

curl "https://za-vsp-int.wigroup.co/cvs-issuer/rest/users/{userRef}/coupons" \
  -H "apiId: {apiId}" \
  -H "apiPassword: {apiPassword}" \
  -H "Content-Type: application/json" \
  -X GET

# Example response

{
  “coupon“: [ {
    “id“: 171117,
    “userRef“: “VSP_User_Id_001“,
    “mobileNumber“: “string“,
    “campaignId“: 4449,
    “campaignName“: "Integration Coupon R5",
    “campaignType“: "COUPON",
    “termsAndConditions“: "Integration Coupon R5",
    “createDate“: "2015-05-21T09:11:32+0200",
    “description“: "Integration Coupon R5",
    “redeemFromDate“: "2015-05-21T00:00:00+0200",
    “redeemToDate“: "2015-11-21T23:59:59+0200",
    “wiCode“: "902430319",
    “redeemedAmount“: 500,
    “voucherAmount“: 500,
    “stateId“: "E",
    “redeemedDate“: "2015-05-21T09:13:17+0200"
  }],
  “responseCode": "-1",
  “responseDesc“: "Success"
}

This resource can be used to retrieve a list of coupons linked to a specific user.

Endpoint: {root}/users/{userRef}/coupons

Available methods: GET

All request parameters, except the API credentials, are query parameters.

Parameter	Type	Description	Request	Response
userRef	String	A unique user reference as on the issuer channel system. This reference will be used to restrict user limits on campaigns.	✓	✓
campaignId	Integer	The id of the campaign to issue against.	✓	✓
campaignType	String	The type of campaign. COUPON VOUCHER	✓	✓
stateId	String	The current state of the coupon. A (Active) D (Deactivated) E (Expired) R (Redeemed)	✓	✓
merchantId	Integer	A merchant id to filter campaigns on.	✓
subdivisionId	String	A subdivision id to filter campaigns on.	✓
retailerId	Integer	A retailer id to filter campaigns on.	✓
latitude	Double	A latitude position. Required for distance calculation. Both longitude and latitude need to be specified together.	✓
longitude	Double	A longitude position. Required for distance calculation. Both longitude and latitude need to be specified together.	✓
mobileNumber	String	The users mobile number, if available		✓
id	Integer	The transaction id.		✓
campaignName	String	The name of the campaign.		✓
termsAndConditions	String	The terms and conditions of the coupon.		✓
createDate	String	The date the couponCampaign was created.		✓
description	String	A description of the campaign.		✓
redeemFromDate	String	From which date the coupon can be redeemed.		✓
redeemToDate	String	Until when the coupon is redeemable.		✓
wiCode	String	The wiCode linked to the user token.		✓
redeemedAmount	Integer	The amount redeemed on the coupon.		✓
voucherAmount	Integer	The possible coupon redemption amount.		✓
redeemedDate	String	Date on which the coupon was redeemed.		✓

GET /users/{userRef}/giftcards


# Example request

curl "https://za-vsp-int.wigroup.co/cvs-issuer/rest/users/{userRef}/giftcards" \
  -H "apiId: {apiId}" \
  -H "apiPassword: {apiPassword}" \
  -H "Content-Type: application/json" \
  -X GET

# Example response

{  
  “giftcard”: {
    “id”: 20,
    “campaignId”: 9000,
    “userRef”: "VSP_User_Id_001",
    "mobileNumber": "string",
    “issuedAmount”: 2000,
    “redeemedAmount”: 0,
    “expiredAmount”: 0,
    “balance”: 2000,
    “createDate”: "2015-03-13T15:10:07+0200",
    “expiryDate”: "2018-03-12T23:59:59+0200",
    “campaignName”: "VSPTestGiftCardCampaign",
    “campaignType”: "GIFTCARD",
    “description”: "Gift Card worth R20.00",
    “imageURL”: "http://goo.gl/Zodst9",
    “termsAndCondition: "VSP T&Cs",
    “stateId”: "A"
  },
  “responseCode”: "-1",
  “responseDesc”: "Success"
}

This resource can be used to retrieve a list of coupons linked to a specific user.

Endpoint: {root}/users/{userRef}/coupons

Available methods: GET

Parameter	Type	Description	Request	Response
userRef	String	A unique user reference as on the issuer channel system. This reference will be used to restrict user limits on campaigns.	✓	✓
campaignId	Integer	The id of the campaign to issue against.	✓	✓
stateId	String	The current state of the giftcard. A (Active) D (Deactivated) E (Expired) R (Redeemed fully)	✓	✓
merchantId	Integer	A merchant id to filter campaigns on.	✓
mobileNumber	String	The mobile number. The mobile number must be presented in International format.		✓
subdivisionId	String	A subdivision id to filter campaigns on.	✓
retailerId	Integer	A retailer id to filter campaigns on.	✓
latitude	Double	A latitude position. Required for distance calculation. Both longitude and latitude need to be specified together.	✓
longitude	Double	A longitude position. Required for distance calculation. Both longitude and latitude need to be specified together.	✓
mobileNumber	String	The mobile number.		✓
id	Integer	The id of the gift card.		✓
campaignId	Integer	The id of the campaign to issue against.		✓
issuedAmount	Integer	The issued amount.		✓
redeemedAmount	Integer	The amount redeemed on the giftcard.		✓
expiredAmount	Integer	The amount expired on the giftcard.		✓
balance	Integer	The amount to issue on giftcard. The balance needs to be within the min and max boundaries of the campaign and the campaign must have the required float available.		✓
createDate	String	The create date of the giftcard.		✓
expiredDate	String	The on which the gift card expired.		✓
campaignName	String	The name of the campaign.		✓
campaignType	String	The type of campaign. GIFTCARD		✓
description	String	A description of the campaign.		✓
imageUrl	String	The image url of the coupon.		✓
termsAndConditions	String	The terms and conditions of the coupon.		✓

GET /users/{userRef}/pans


# Example request

curl "https://za-vsp-int.wigroup.co/cvs-issuer/rest/users/{userRef}/pans" \
  -H "apiId: {apiId}" \
  -H "apiPassword: {apiPassword}" \
  -H "Content-Type: application/json" \
  -X GET

# Example response

{
  "responseCode": "string",
  "responseDesc": "string",
  "userGroupPan": {
    "pan": "string",
    "userRef": "string",
    "interfaceIssuerGroupId": "string",
    "interfaceIssuerId": "string",
    "createDate": "2016-07-06T07:53:18.628Z",
    "lastModifiedDate": "2016-07-06T07:53:18.628Z",
    "interfaceGroupId": "string"
  }
}

Get user pan.

Endpoint: {root}/users/{userRef}/pans

Available methods: GET

Parameter	Type	Description	Request	Response
userRef	String	A unique user reference as on the issuer channel system. This reference will be used to restrict user limits on campaigns.	✓	✓
pan	String	The pan.		✓
interfaceIssuerGroupId	String	The id of the interface issuer group.		✓
createDate	String	The create date of the pan.		✓
lastModifiedDate	String	The last modified date.		✓

/retailers

GET /retailers


# Example request

curl "https://za-vsp-int.wigroup.co/cvs-issuer/rest/retailers" \
  -H "apiId: {apiId}" \
  -H "apiPassword: {apiPassword}" \
  -H "Content-Type: application/json" \
  -X GET

# Example response

{
  retailers: [ {
    “createDate“: "2013-03-19T07:34:02+0200",
    “id“: 1050,
    “name“: "Test Retailer",
    “description“: "The best tester",
    “logoURL“: "www.testurl.com/image.png"
  }],
  “responseCode“: "-1",
  “responseDesc“: "Success"
}

Returns a list of the retailers linked to active campaigns on the channel.

Endpoint: {root}/retailers

Available methods: GET

Parameter	Type	Description	Request	Response
campaignId	Integer (query)	If specified it will return a list of retailers linked to the campaign.	✓
createDate	String	The date the retailer was created.		✓
id	Integer	The id of the retailer.		✓
name	String	The name of the retailer.		✓
description	String	A description of the retailer.		✓
logoURL	String	The retailer logo URL.		✓

/merchants

GET /merchants


# Example request

curl "https://za-vsp-int.wigroup.co/cvs-issuer/rest/merchants" \
  -H "apiId: {apiId}" \
  -H "apiPassword: {apiPassword}" \
  -H "Content-Type: application/json" \
  -X GET

# Example response

{
  merchants: [ {
    “createDate“: "2013-03-19T07:34:02+0200",
    “id“: 1050,
    “name“: "Test Merchant",
    “provinceDesc“: "Eastern Cape",
    “provinceId“: 1,
    “stateId“: "A",
    “retailerId“: 10,
    “retailerName“: "wiGroup Retailer",
    “latitude“: -33.932308,
    “longitude“: 18.467464,
    “distance“: 0
      }
  }],
  “hasNextPage“: false,
  “numOfPages“: 1,
  “numItemsOnPage“: 2,
  “numItemsInTotal“: 2,
  “order“: {},
  “pageSize“: 20,
  “pageOffset“: 0,
  “responseCode“: "-1",
  “responseDesc“: "Success"
}

This resource denotes the collection of all merchants linked to active campaigns on the channel.

Endpoint: {root}/merchants

Available Methods: GET

Parameter	Type	Description	Request	Response
campaignId	Integer	Filter transactions for specific campaign.	✓
retailerId	Integer	The retailer id.	✓	✓
id	Integer	The id of the merchant.		✓
name	String	The name of the merchant.		✓
provinceDesc	String	Description of the merchant province.		✓
provinceId	Integer	The id of the merchant province.		✓
stateId	String	The current state of the giftcard. A (Active) D (Deactivated)		✓
retailerId	Integer	The retailer id.		✓
retailerName	String	The retailer name.		✓
longitude	Double	A longitude position. Both longitude and latitude need to be specified together.		✓
latitude	Double	A latitude position. Both longitude and latitude need to be specified together.		✓
distance	Double	The distance to the closest merchant.		✓

/transactions

Coupon, voucher and gift card transactions may be queried.

GET /transactions


# Example request

curl "https://za-vsp-int.wigroup.co/cvs-issuer/rest/transactions" \
  -H "apiId: {apiId}" \
  -H "apiPassword: {apiPassword}" \
  -H "Content-Type: application/json" \
  -X POST

# Example response

{  
  “transactions”: {[
    “id“: 101694,
    “wiCode“: "528626479",
    “userRef“: "VSP_User_Id_001",
    “merchantId“: 1050,
    “merchantName“: "Test Merchant",
    “retailerId“: 10,
    “retailerName“: "wiGroup Retailer",
    “processedAmount“: 2500,
    “numberOfCoupons“: 1,
    “numberOfGiftcards“: 0,
    “totalCouponProcessedAmount“: 2500,
    “totalGiftcardProcessedAmount“: 0,
    “transactionDate“: "2015-07-23T14:07:24+0200",
    “interfaceIssuerId“: "VSPIssuer",
    “issuerId“: 128,
    “stateId“: "S"
  }]
  ,
  “paging“:    {
    “pageSize“: 10,
    “pageOffset“: 0,
    “numItemsOnPage“: 1,
    “numItemsInTotal“: 1,
    “numPages“: 1
  },
  “responseCode”: "-1",
  “responseDesc”: "Success"
}

This resource denotes the top level transactions. It will indicate how many coupon and giftcard transactions was processed on the transaction.

Endpoint: {root}/transactions

Available methods: GET

Parameter	Type	Description	Request	Response
userRef	String	The user reference to filter on.	✓	✓
wiCode	String	To filter transaction on specific wiCode.	✓	✓
dateFrom	String	The date from which to return transactions.	✓
dateTo	String	The date to which to return transactions.	✓
id	Integer	The transaction id.		✓
merchantId	Integer	The merchant id.		✓
merchantName	String	The merchant name.		✓
retailerId	Integer	The retailer id.		✓
retailerName	String	The retailer name.		✓
processedAmount	Integer	The total processed amount for all linked coupon and giftcard transactions.		✓
numberOfCoupons	Integer	The number of coupons redeemed on transaction.		✓
numberOfGiftcards	Integer	The number of giftcards redeemed on transaction.		✓
totalCouponProcessedAmount	Integer	The total processed amount from coupon redemptions.		✓
totalGiftcardProcessedAmount	Integer	The total processed amount from giftcard redemptions.		✓
transactionDate	String	The transaction date.		✓
interfaceIssuerId	Integer	The transaction id.		✓
issuerId	Integer	The id of the issuer.		✓
stateId	String	The current transaction state. N (New) P (Processing) F (Failed) SPR (Successful pending recon) S (Successful)		✓

GET /transactions/{id}


# Example request

curl "https://za-vsp-int.wigroup.co/cvs-issuer/rest/transactions/{id}" \
  -H "apiId: {apiId}" \
  -H "apiPassword: {apiPassword}" \
  -H "Content-Type: application/json" \
  -X POST

# Example response

{  
  “transactions”: {[
    “id“: 101694,
    “wiCode“: "528626479",
    “userRef“: "VSP_User_Id_001",
    “merchantId“: 1050,
    “merchantName“: "Test Merchant",
    “retailerId“: 10,
    “retailerName“: "wiGroup Retailer",
    “processedAmount“: 2500,
    “numberOfCoupons“: 1,
    “numberOfGiftcards“: 0,
    “totalCouponProcessedAmount“: 2500,
    “totalGiftcardProcessedAmount“: 0,
    “transactionDate“: "2015-07-23T14:07:24+0200",
    “interfaceIssuerId“: "VSPIssuer",
    “issuerId“: 128,
    “stateId“: "S"
  }]
  ,
  “paging“:    {
    “pageSize“: 10,
    “pageOffset“: 0,
    “numItemsOnPage“: 1,
    “numItemsInTotal“: 1,
    “numPages“: 1
  },
  “responseCode”: "-1",
  “responseDesc”: "Success"
}

This endpoint will return a specific high level transaction’s details.

Endpoint: {root}/transactions/{id}

Available methods: GET

Parameter	Type	Description	Request	Response
id	Integer	The transaction id.		✓
wiCode	String	To filter transaction on specific wiCode.	✓	✓
userRef	String	The user reference to filter on.	✓	✓
merchantId	Integer	The merchant id.		✓
merchantName	String	The merchant name.		✓
retailerId	Integer	The retailer id.		✓
retailerName	String	The retailer name.		✓
processedAmount	Integer	The total processed amount for all linked coupon and giftcard transactions.		✓
numberOfCoupons	Integer	The number of coupons redeemed on transaction.		✓
numberOfGiftcards	Integer	The number of giftcards redeemed on transaction.		✓
totalCouponProcessedAmount	Integer	The total processed amount from coupon redemptions.		✓
totalGiftcardProcessedAmount	Integer	The total processed amount from giftcard redemptions.		✓
transactionDate	String	The transaction date.		✓
interfaceIssuerId	Integer	The transaction id.		✓
issuerId	Integer	The id of the issuer.		✓
stateId	String	The current transaction state. N (New) P (Processing) F (Failed) SPR (Successful pending recon) S (Successful)		✓

Redemption callback

The redemption callback URL provides the wiPlatform with a means of notifying third parties that a redemption has occurred. Whenever a transaction containing a redemption request is successfully processed by the wiCode platform, a redemption callback will be POSTed to the configured callback URL.

Redemption Callback failure

To facilitate synchronization, the wiPlatform has a built-in finite redemption callback retry policy. This is enables better state synchronization by minimizing the number of redemption callback failures. If, for some reason, no response is received across all redemption callback requests, a redemption fallback policy must be followed.

Webhook URL

Each redemption notification will include three key parameters: itemId, processedAmount, and totalProcessed. The itemId corresponds to the ID of the coupon, or giftcard that was redeemed. The processedAmount corresponds to the monetary value of the redemption, i.e. the value of the coupon or the value of the giftcard that was spent. totalProcessedAmount is the sum of the processed amount across all redemptions in the transaction.

The redemption callback should be built using RESTful JSON programming language.


# Example request

{
 "id" : 115796,
 "userRef" : "0813584314",
 "basketId" : "wiPOS--2016-07-06 08:34:18",
 "storeId" : 1050,
 "totalProcessedAmount" : 1200,
 "createDate" : "2016-07-06T10:34:20+0200",
 "wiCode" : "4461707",
 "interfaceIssuerId" : "your_qa_channel",
 "wiTrxId" : "48711",
 "redemption" : [{
   "id" : 173608,
   "processedAmount" : 300,
   "createDate" : "2016-07-06T10:34:20+0200",
   "type" : "COUPON",
   "itemId" : 219086,
   "campaignId" : 5943,
   "wiCode" : "4461707"
  }, {
   "id" : 173609,
   "processedAmount" : 400
   "createDate" : "2016-07-06T10:34:20+0200",
   "type" : "COUPON",
   "itemId" : 219087,
   "campaignId" : 5915,
   "wiCode" : "4461707"
  }, {
   "id" : 173610,
   "processedAmount" : 500,
   "createDate" : "2016-07-06T10:34:20+0200",
   "type" : "COUPON",
   "itemId" : 219088,
   "campaignId" : 5905,
   "wiCode" : "4461707"
  }
 ]
}

# Example response

HTTP 200 (OK)

Endpoint: {your_webhook_url}/

Parameter	Type	Description
id	Integer	Unique identifier of the redemption callback.
userRef	String	Unique identifier of the user (against which the Gift Card is issued).
basketId	String	Unique identifier of the basket.
storeId	Integer	Unique identifier of a store. Once-off provided by wiGroup.
totalProcessedAmount	Integer	Sum of the processedAmount across each redemption.
createDate	String	The date on which the transaction was created.
wiCode	String	Number of digits for the desired wiCode.
wiTrxId	String	Unique Transaction Identifier for wiCode platform.
interfaceIssuerId	String	The channel which issued the wiCode for redemption.

Redemption object

Parameter	Type	Description
id	Integer	Unique identifier of the redemption.
processedAmount	Integer	Value of the redemption.
createDate	String	The date of redemption of the item.
type	String	COUPON, VOUCHER or GIFTCARD.
itemId	Integer	Unique identifier of the item. E.g. Gift Card Id.
campaignId	Integer	Campaign against which the item was issued.

Response Codes

Every response contains responseCode and responseDesc fields. These indicate whether the request was successful or failed. The only successful is denoted by a value of -1. All other response codes indicate failed requests. The table below denotes all possible response codes.

Response Code	Response Description
-1	Successful
1000	Interface Authentication Failed. Account does not exist.
1001	Interface Authentication Failed. Invalid password.
1002	Interface Authentication Failed. Interface account not activated.
1003	Interface Authentication Failed. Issuer account not activated.
1004	Issuer Webuser Authentication Failed. Account does not exist.
1005	Issuer Webuser Authentication Failed. Invalid password.
1006	Issuer Webuser Authentication Failed. Issuer webuser not activated.
1007	Issuer Webuser Authentication Failed. Issuer webuser not linked to interface issuer.
1008	Interface Authentication Failed. Credentials missing.
1200	Campaign does not exist.
1201	Campaign is not active.
1202	Campaign not yet active for issuing vouchers.
1203	Campaign issuing window closed. No more vouchers can be issued.
1204	Campaign has reached its max available.
1205	The campaign requires an user id to issue voucher to.
1206	Campaign not linked to channel.
1207	Campaign not linked to channel.
1208	No more coupons available.
1209	User has reached the maximum allowed live coupons per user on campaign.
1210	User has reached the maximum allowed coupons per user on campaign.
1211	Campaign is open to selected users only.
1212	There is no SMS account linked. Cannot issue SMS voucher.
1213	No more coupons available for today.
1214	This is not a coupon campaign.
1215	Transaction coupon does not exist.
1216	Coupon does not exist.
1250	Invalid voucher phase specified. Must be LIVE, REDEEMED, or EXPIRED.
1251	Invalid campaign type specified.
1300	No valid wiCodes found.
1301	Could not link voucher infos.
1303	Invalid wiCode.
1304	No vouchers found for User.
1305	Invalid campaign type specified.
1306	Another request issued at the same time. Failing call.
1306	Required field missing
1307	Required field in voucherInfo missing
1308	Coupon does not exist.
1309	Coupon cannot be expired as it has already been redeemed.
1310	Coupon already expired.
1311	You must specify something to redeem.1312 User does not have a valid token.
1312	User does not have a valid token.
1500	Invalid campaign phase specified. Must be CURRENT, TODAY, PENDING.
1501	Invalid campaign type specified.
1550	Latitude and Longitude values are required in order to sort by distance.
1600	Invalid channel group id specified.
2100	Invalid wicode
2303	Mobile Number not Registered
7100	This is not a giftcard campaign.
7101	Amount to issue exceeds available float for campaign.
7102	Amount to issue exceeds maximum allowable amount to issue.
7103	Amount to issue is less than minimum allowable amount to issue.
7104	The campaign requires an user id to issue giftcard to.
7105	No more giftcard available.
7106	User has reached the maximum allowed giftcards per user on campaign.
7107	Giftcard does not exist.
7108	Giftcards cannot be issued with SMS.
7109	The campaign does not allow channel to specify expiry days.
7110	The campaign does not allow the requested expiry days.
7111	Amount to issue invalid.

Conclusion and notes

This document provides sufficient context of the wiCode CVS API document [1], although is not intended as a comprehensive introduction to CVS for extensive implementation. This document is rather intended as an additional addendum to the the wiCode CVS API document [1] containing the most relevant (and often most-consumed) web-service calls that wiGroup’s CVS has to offer. Please direct any queries with regards to the implementation to your wiGroup account manager or integration specialist.

References

wiGroup APIs CVS 2.9 RESTful, PDF document.
wiGroup CVS Web Portal Guide, PDF document.

FAQ’s

Where can I find my testing API credentials?

Log into the Web Portal as the Channel Owner, go the the Channels section. The Interface ID and password are your API ID and password. You can have multiple channels inside the same channel group.

These are issued to you by the wiGroup integrations team. When your solution has passed integrations testing, and is promoted into the production environment, you will receive an email with your login credentials.

How do I get my campaigns signed-off in the QA environment?

Make sure your have signed off the campaign as the Campaign Owner via the Web Portal, and then Simply email your integrations specialist to sign it off.

What parameters get sent with the redemption callback?

Please refer to the redemption callback section.

How do I set the expiry time for a coupon/voucher on issue?

When making the POST /coupons call use the numExpiryDays parameter to set the number of expiry days. This option will only work if the option for a channel to override the coupon expiry was enable during campaign creation.

Why do I only see 20 giftcards on the GET /giftcards/{id} API call when I know the user has 50?

If you wish to see an extended list of gift cards set the pageSize parameter to a number that you want, default is 20.

What are the content parameters to use when created a custom SMS message with the API call?

When issuing a gift card with an sms message, you can include the following parameters in the message. #WICODE #BALANCE #EXPIRY #MOBISITE.

What is the deference between an Open and a Merged wiCodes.

An open wiCode is campaign specific, issuing the user coupons from all campaigns assigned to that channel. A merged wicode is coupons specific, a token will be created incorporating all tokens that have been issued to the user by the channel group.

I am issuing coupons but I am not receiving a wiCode with them.

You need need to set the issueWicode parameter to true when doing the POST /coupon call.

Overview - Coupon, Voucher and Gift Card Service

Coupons and Vouchers

Gift cards

CVS Web Portal

QA URL

Guide

CVS Issuer REST API

Date format

Monetary format

Paginated collections

API credentials

API references

Test credentials

/couponcampaigns

GET /couponcampaigns

GET /couponcampaigns/{campaignId}

GET /couponcampaigns/{campaignId}/skus

/coupons

POST /coupons

GET /coupons/{id}

DELETE /coupons/{id}

/coupontransactions

GET /coupontransactions

GET /coupontransactions/{id}

/giftcardcampaigns

GET /giftcardcampaigns

GET /giftcardcampaigns/{id}

/giftcards

POST /giftcards

POST /giftcards/{id}/wicode

GET /giftcards/{id}

DELETE /giftcards/{id}

/giftcardtransactions

GET /giftcardtransactions

GET /giftcardtransactions/{id}

/campaigns

GET /campaigns/{campaignId}/metadata

/users

POST /user/{userRef}/token

GET /user/{userRef}/token

DELETE /user/{userRef}/token

GET /users/{userRef}/transactions

GET /users/{userRef}/coupons

GET /users/{userRef}/giftcards

GET /users/{userRef}/pans

/retailers

GET /retailers

/merchants

GET /merchants

/transactions

GET /transactions

GET /transactions/{id}

Redemption callback

Redemption Callback failure

Webhook URL

Redemption object

Response Codes

Conclusion and notes

References

FAQ’s

Where can I find my testing API credentials?

Where do I get my Web Portal login credentials?

How do I get my campaigns signed-off in the QA environment?

What parameters get sent with the redemption callback?

How do I set the expiry time for a coupon/voucher on issue?

Why do I only see 20 giftcards on the GET /giftcards/{id} API call when I know the user has 50?

What are the content parameters to use when created a custom SMS message with the API call?

What is the deference between an Open and a Merged wiCodes.

I am issuing coupons but I am not receiving a wiCode with them.