Gift Card Issuing

Issue gift cards for 100+ South African brands

Issue Gift Card via SMS/WhatsApp

Quick Start

Yoyo handles delivery - just provide a mobile number

How it works

1Call the Issue Gift Card API with campaign ID, balance, and mobile number
2Yoyo creates the gift card and generates a unique wiCode
3Yoyo automatically delivers the gift card via SMS or WhatsApp
4Customer receives the wiCode and can redeem at any integrated merchant

Issue Gift Card via SMS/WhatsApp

# Issue Gift Card and send via configured channel (SMS or WhatsApp)
curl -X POST "https://za-vsp-int.wigroup.co/cvs-issuer/rest/giftcards?issueWiCode=true" \
  -H "apiId: {apiId}" \
  -H "apiPassword: {apiPassword}" \
  -H "Content-Type: application/json" \
  -d '{
    "campaignId": 9000,
    "balance": 10000,
    "userRef": "your_customer_reference_number",
    "mobileNumber": "+27821234567",
    "smsMessage": "Your gift card code is ready!",
    "sendSMS": true
}'

Example Response

{
  "giftcard": {
    "id": 20,
    "campaignId": 9000,
    "interfaceIssuerId": "TestChannel",
    "issuerId": 94,
    "userRef": "VSP_User_Id_001",
    "mobileNumber": "string",
    "sendSMS": true,
    "sendFollowUpSMS": false,
    "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",
    "termsAndConditions": "VSP T&Cs",
    "stateId": "A",
    "wicode": "123456789999"
  },
  "responseCode": "-1",
  "responseDesc": "Success"
}

Note: The communication channel (SMS or WhatsApp) is configured at the system level, not per-request. Set sendSMS: true to trigger delivery via your configured channel. WhatsApp requires additional META configuration. The userRef field is mandatory for tracking.

Distribute and View in Your Own App

Get the wiCode, display the balance, and track usage

How it works

1Call the Issue Gift Card API with campaignId, balance, userRef, and stateId
2Receive the wiCode and gift card ID in the response
3Display the gift card in your app with balance information
4Use the Get Gift Card API to check remaining balance

Issue Gift Card for Custom Distribution

# Issue wiCode only — no message sent
curl -X POST "https://za-vsp-int.wigroup.co/cvs-issuer/rest/giftcards?issueWiCode=true" \
  -H "apiId: {apiId}" \
  -H "apiPassword: {apiPassword}" \
  -H "Content-Type: application/json" \
  -d '{
    "campaignId": "9000",
    "balance": "2000",
    "userRef": "VSP_User_Id_001",
    "stateId": "A"
}'

Use Cases

Display balance in your mobile app
Corporate gift card programs
Reward and incentive platforms

Response Fields

wicode - The redemption code
balance - Remaining value in cents
id - Gift card ID

Get Available Campaigns

Retrieve a list of active gift card campaigns available to your channel. Use this to display available gift card options to your users.

GET /giftcardcampaigns

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

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,
    "stateId": "A",
    "allowExpiryDateOverride": false,
    "expiryDays": 1095
  }],
  "paging": {
    "pageSize": 20,
    "pageOffset": 0,
    "numItemsOnPage": 1,
    "numItemsInTotal": 1,
    "numPages": 1
  },
  "responseCode": "-1",
  "responseDesc": "Success"
}

Get Gift Card Details

Retrieve details of a specific gift card including current balance, redeemed amount, and expiry date.

GET /giftcards/{giftcardId}

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

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"
}

Get User's Gift Cards

Retrieve all gift cards linked to a specific user reference.

GET /users/{userRef}/giftcards

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

Example Response

{
  "responseCode": "-1",
  "responseDesc": "Success",
  "httpStatusCode": 200,
  "giftcardList": [{
    "id": 288647,
    "campaignId": 4455,
    "interfaceIssuerId": "paytecSnapAndSaveIssuertest",
    "issuerId": 856,
    "userRef": "SnapAndSave",
    "issuedAmount": 6000,
    "redeemedAmount": 2200,
    "expiredAmount": 0,
    "balance": 3800,
    "breakageValue": 0,
    "createDate": "2024-01-30T15:36:03+0200",
    "expiryDate": "2027-02-22T23:59:59+0200",
    "campaignName": "SnapAndSave gift card campaign",
    "campaignType": "GIFTCARD",
    "description": "SnapAndSave gift card campaign",
    "imageUrl": "0",
    "termsAndConditions": "SnapAndSave gift card campaign",
    "stateId": "D",
    "redeemFromTime": "00:00",
    "redeemToTime": "00:00",
    "isRedeemableOnSundays": true,
    "isRedeemableOnMondays": true,
    "isRedeemableOnTuesdays": true,
    "isRedeemableOnWednesdays": true,
    "isRedeemableOnThursdays": true,
    "isRedeemableOnFridays": true,
    "isRedeemableOnSaturdays": true
  }],
  "paging": {
    "orderBy": "ID",
    "orderDirection": "DESC",
    "pageSize": 20,
    "pageOffset": 0,
    "numItemsOnPage": 1,
    "numItemsInTotal": 1,
    "numPages": 1
  }
}

Get Transaction History

Retrieve all transactions related to a specific gift card for reporting and reconciliation.

GET /giftcardtransactions

curl -X GET "https://za-vsp-int.wigroup.co/cvs-issuer/rest/giftcardtransactions?giftcardId={id}" \
  -H "apiId: {apiId}" \
  -H "apiPassword: {apiPassword}"

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"
}

Expire/Delete Gift Card

Expire a gift card and return any remaining balance to the campaign float.

DELETE /giftcards/{giftcardId}

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

Example Response

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

Redemption Callback

Yoyo sends a POST to your webhook URL whenever a redemption completes — successfully or not. This is an outbound notification from Yoyo, not an endpoint you call. Use it to keep your own records in sync without polling.

Webhook URL: One callback URL is configured per VSP. Contact your Yoyo integration manager to set or change it.

POST to your webhook URL

{
  "redemptionId": 1,
  "campaignId": 123,
  "userId": "user456",
  "vspId": 20016,
  "amount": 5000,
  "type": "GIFTCARD",
  "state": "S",
  "transactionId": 431711,
  "createDate": "2024-01-18T14:05:58.009Z"
}

Redemption callback payload fields
Field	Type	Description
`redemptionId`	Integer	Unique identifier for the redemption event
`campaignId`	Integer	Campaign the redemption belongs to
`userId`	String	Customer identifier
`vspId`	Integer	Value Store Provider identifier
`amount`	Integer	Redemption amount in cents (5000 = R50.00)
`type`	String	COUPON, VOUCHER, or GIFTCARD
`state`	String	S (Success), F (Failed), or R (Reversed)
`transactionId`	Integer	Related transaction identifier
`createDate`	String	ISO 8601 timestamp of the redemption

Acknowledge every callback: Respond with 200 OK. If no response is received, Yoyo retries up to 10 times before giving up — after that the notification is not resent, so reconcile any gaps from your own transaction records.

Failed and reversed redemptions are delivered too, so check state before treating a callback as a completed redemption.