Gift Card

Gift Card purchases

Creating Gift Card Platform and SKU configuration

1. Access your application on Kiwi Admin

2. On Monetization side menu, check if you have Gift Card already configured. In case it's not configured, you can add it through the "New Platform" button. Gift Card Platform supports iOS, Android and WEB applications.

3. Gift Card platform doesn't need to configure any platform properties. You can just save it to have it available at the list of monetization platforms.

4. Click "Save" to complete this part of the process.

5. On the platform listing, click on "SKU Configuration" on the actions column for Gift Card.

6. Create a new SKU configuration, by clicking on "New Configuration"

7. Fill the SKU name with a meaningful name of the corresponding Gift Card campaign.

8. Set Share Type to SHARE_ACROSS_PRODUCT.

9. Select the renew period.

10. Select if the SKU has a trial period and enter the trial period in days.

11. Select the currency code for this SKU and enter the price.

12. Gift Card platform offers a "payload" field, which a given app loads custom settings, in JSON format. This field is optional, in case it's needed to fulfill this field, it needs to be under JSON format.

13. Click save to complete the process.

Generating / listing Gift Cards

1. Right After the SKU action, there are two new buttons under the "Actions" column. Generate Gift Cards and List Gift Cards.

2. Click on the Generate Gift Cards Button

3. A window will appears with the following information:

   • Quantity: Number of gift cards limits up to 5 millions gift cards per batch. Default Value is 1.

   • Reserve All Gift Cards: Set all Gift Cards as Available or reserved. Default value is "No", which means all Gift cards generates with the status AVAILABLE. Otherwise, it's set as RESERVED.

   • Expires At: Gift Cards expiration date. Default is NEVER. Otherwise, a date time can be set.

4. Click Save to send a message to trigger the gift cards generation.

5. Right After this process, a batch process will be responsible for generate the gift cards. After that, it sends an email to the requester, containing the generation id and a attached zip file.

6. After the end of Gift Cards generation, an email will arrive with the following format:

   • from: [e-mail]

   • to: your company email

   • Subject: [Kiwi - Gift Cards request is completed. Sku: sku name]

   • Message Body: You can find attached the Gift Cards you have requested. Feel free to talk to the Kiwi team for any assistance you may need. Generation Id: UUID value

   • An email Attachment, under the format: sku_sku name_Generation UUID_generated.csv.zip

   • Inside the zipped file, the csv file has the following format:

   • Gift card Code, AVAILABLE or RESERVED

7. After the Gift Card processing is done, the generated gift cards can be listed at the "List Gift Card Button.

8. Click at the List Gift Card Button

9. A table will be shown with all Gift Cards Generated to the selected SKU. Each gift card item can be inspected / edited through the "Edit" button.

10. Click on the "Edit" button at any generated gift card

    • A window is opened, containing all Gift Card specific information. At this window it's possible to set a Gift Card as AVAILABLE or RESERVED and set an expiration date after the gift card is generated.

11. Click "Save" to persist any gift card edition.

Understanding Gift Card internal Statuses

Every time a gift cars is generated, it supports the following set of statuses:

• AVAILABLE, status = 0

• RESERVED, status = 1

• REDEEMED, status = 2

• EXPIRED, status = 3

• PROCESSING, status = 4

• AVAILABLE: It's the first gift card status. It's useful to generate a gift card and set it on demands as needed. From a business perspective, it's way from Customer Happiness to mark a Gift Card as RESERVED when a given end-user needs a Gift Card to be Redeemed.

• RESERVED: A gift card only can be redeemed if a Gift Card is set to Reserved. It can be done at the beginning of the generation process, setting "Reserve All Gift Cards" before generated them, or editing each gift card manually after the gift card generation is performed.

• REDEEMED: When a gift card is set to RESERVED, it can be Redeemed by the end user through WEB / iOS / Android platforms. After a end-user Redeems a gift card, the status is set to REDEEMED and a subscription will be created to this user after the gift card redeem process.

• EXPIRED: When a Gift Card has an expiration date associated with its generation or when someone manually edits its expiration time, before the REDEEM process it's checked if the gift card is expired or not. It so, the gift card is set to EXPIRED and can't be used to create a subscription anymore.

• PROCESSING: Intermediary status, present between RESERVED / REDEEM status. Useful to mark a gift card is processed, in order to ensure the purchase will be atomically generated by the register process and important if the process crashes at the middle of the process, stating the flow was roughly interrupted.

Redeeming a gift card code and creating a subscription

In order to redeem a gitcard, a POST request must be made to Kiwi Webservice Purchase Giftcard endpoint. The gift card redeem process needs the following input (bold fields are mandatory).

• User Id: user identification (UUID format)

• App Install Id: Installation Id (UUID format)

• Account Id: Account Identification (UUID Format) (sent when is desired that the subscription created is linked to an account)

• Gift Card Code: Code that will be sent by the end-user (udner the format xxx-xxx-xxx, alphanumeric)

• Session Media Info: Optional field, in order to identify media campaigns.

Example of complete input:

{
   "user_id": "9C88CA8F-B1A7-45D9-9D58-C76D00E97C38",
   "app_install_id": "0a420858-0f08-4265-803c-6c20d28117ee",
   "account_uuid": "1ba2ad11-c487-4805-9e69-89e45be8555d",
   "gift_card_code": "HRK-VHB-VQ4",
   "session_media_info":{
       "campaign_id":"123",
       "campaign_network":"1234",
       "raw":"raw"
   }
}

Example of minimal input in order to have a valid subscription:

{
   "user_id": "9C88CA8F-B1A7-45D9-9D58-C76D00E97C38",
   "app_install_id": "0a420858-0f08-4265-803c-6c20d28117ee",
   "gift_card_code": "HRK-VHB-VQ4",
}

Note: the Account Id is optional, but it will generate different SUCCESS statuses, as explained below at the statuses Ids:

From this input, we will have the following output:

• Status: Gift Card Subscription Status

• Message: Meaninful Message Explaining the status

• Subscription: Subscription Information, when the status is SUCCESS or SUCCESS_NOT_LINKED.

Gift Card Subscription statuses:

• SUCCESS(0): Means that the subscription process was successful, linking the current logged account with the created subscription.

• SUCCESS_NOT_LINKED(1): Means that the subscription process was successful, but the current subscription couldn't be linked with an Account Id, probably because the end-user redeemed the Gift Card without any account information (e.g. not signed-in during the Redeem process).

• INVALID_PARAMETERS(2): Means the mandatory parameters are invalid, not following the defined format (e.g. invalid user or app install id format)

• ERROR_INVALID_GIFTCARD(3): Means the gift card somehow is invalid. It can be due several reasons, e.g. invalid gift card format, invalid gift card because it's not present at the database, etc. For each separated case if needed, Kiwi Team can investigate for each reason separetely.

• ERROR_REGISTERING_SUBSCRIPTION_ON_KIWI(4): Means the input values are under the given format, but the content is somehow not present at Kiwi Platform, e.g. user Id or account Id is under UUID format but isn't found, etc.

• ERROR_GIFTCARD_NOT_RESERVED(5): Means the end-user is trying to redeem a Gift card which is not under the RESERVED state (possibly under AVAILABLE state). It needs to contact customer happiness ind er to set up the gift card to RESERVED state.

• ERROR_GIFTCARD_ALREADY_EXPIRED: Means someone is trying to redeem an already expired gift card more than once. Useful to identify multiple useless gift card redeem tries.

• ERROR_GIFTCARD_EXPIRED(7): Means someone tries to redeem a Reserved gift Card and this gift card reaches its expiration date at the first time. The gift card is set to Expire and returns a specific status about it.

• ERROR_GIFTCARD_ALREADY_REDEEMED(8): Means someone is trying to redeem a gift card which was already redeemed. A gift card can be redeemed just one time, creating a valid subscription.

• ERROR_UNKNOWN(9): Status for unexpected Errors, which wasn't coverered by no one of the status above, mostly for unexpected exceptions.

Example of a successful output:

{
  "status": 0,
  "message": "Subscription Created successfully",
  "subscription": {
    "id": 36306492510768,
    "subscription_platform": 10,
    "subscription_type": 2,
    "subscription_status": 1,
    "sku": "123",
    "currency_code": "USD",
    "price": 0,
    "external_transaction_id": "HRK-VHB-VQ4",
    "created_as_trial": false,
    "trial_duration_in_days": 0,
    "activated_at": 1455651179,
    "expires_at": 1455737579,
    "extra_data": {
      "teste": "teste"
    }
  }
}

Example of a unsuccessful output:

{
  "status": 3,
  "message": ""The Gift card code ABCSD is invalid"",
}

On-Demand gift card creation

If, by any reason, you decide to create gift cards upon request (e.g., to distribute gift cards when an user subscribes with an external partner), you can use on-demand gift card creation, via requests to a specific API.

In order to do so, you first need to enable on-demand creation and setup an authorization secret for your app, which Kiwi will use to authenticate the request.

Gift cards can only be created with status RESERVED using this API.

Enabling on-demand creation

1. On Kiwi Admin, navigate to Monetization, head to the GIFTCARD item on the table and click on the edit icon (the last one)

2. Enable / disable the usage of the API with the yes/no switch and configure the authorization password on the text input. We recommend using a strong password, given that the usage of this API can generate gift cards freely.

3. Click on save, and you're all set =)

API details

To create the gift card, you just need to call our Tools Webservice with the following data:

Method: POST

Endpoint: https://tools.kwsdk.io/api/1.0/subscription/giftcard/create

Headers

X-Kiwi-Application-Key: <insert your app key here>
X-Kiwi-Authorization-Secret: <insert the configured secret here>

Request body

{
  "sku": "<the SKU to assign to this gift card>",
  "expiresAt": "<max. date to redeem the code>"
}

The sku field is mandatory and it's validated against the SKUs configured on Kiwi for the application. The expiresAt is optional: if missing, the gift card can be redeemed at any time.

Response

{
  "status": "<status text>",
  "statusCode": "<status code>",
  "message": "<a message explaining the status>",
  "giftCard": "<the generated code, if success>",
}

If the operation fails, by any reason, the giftCard field won't be sent.

The statuses are the following:

HTTP Status	Status	Status Code	Possible causes
500	UNKNOWN	-1	it didn't work
200	SUCCESS	0	it worked
403	ERROR_DISABLED	1	on-demand is disabled for the app on Kiwi Admin
401	ERROR_INVALID_CREDENTIALS	2	missing app key or secret, inexistent app key or wrong secret
422	ERROR_MISSING_GIFTCARD_CONFIGURATION	3	missing configuration for gift cards on Kiwi Admin
422	ERROR_INVALID_EXPIRATION	4	the requested expiration date is on the past
422	ERROR_INVALID_SKU	5	missing SKU or the SKU is not configured on Kiwi Admin

Platform releases

Gift Card Purchases are available under WEB / iOS / Android Platforms.

WEB Release

Can be integrated through landing pages and following the JSON format as input, explained here at this documentation.

iOS Release (kiwi-sdk-ios):

https://github.com/Movile/kiwi-sdk-ios/releases/tag/0.30.2

Android Release (kiwi-sdk-androidprovider-purchase):

https://github.com/Movile/kiwi-sdk-android-provider-purchase/releases/tag/v-0.3.7

Test Applications

Both iOS / Android releases contains test applications explaining how to redeem a gift card:

Android Test-app example:

https://github.com/Movile/kiwi-sdk-android/blob/develop/kiwi-sdk-android-testapp/src/main/java/com/movile/kiwi/sdk/testapp/activities/GiftCardPurchaseActivity.java

iOS Test-app example:

https://github.com/Movile/kiwi-sdk-ios/blob/d58216c71debba93a9a508df6097db64b3a83b1b/Kiwi/KWIGiftCardViewController.m

BlackHawk Integration

Kiwi has a gateway implementing only the redemption method of the BHNUMS platform. The platform itself is responsible to handle transaction reversal in case of soft declines. The retry interval is hard-coded to 15 minutes.

In order to use this integration, besides the commercial agreement with BH, you need to open a ticket to the Kiwi team, asking for the configuration of BH's parameters on our platform.

The gateway is implemented according to the spec 4.3E (43).

Validation API:

This API merely checks for a card existence on Kiwi's database, not relying on BH's balance inquiry API.

Method: GET

Endpoint:https://purchase.kwsdk.io/api/1.0/subscription/blackhawk/giftcard/validate?pinCode=<pincode to check>

Headers:

X-Kiwi-Application-Key: <insert your app key here>

Response:

{
  "status": <status code>,
  "message": "<a status message explaining the status code - useful for debugging>"
}

The statuses are the following:

Status Code	Status	Message
0	UNKNOWN	An unknown error has happened
1	OK	Card can be redeemed (note: this only checks for a card existence, the success of the redeem operation depends upon card activation at PoS)
2	ALREADY_REDEEMED	The card has already been redeemed
3	INVALID	The card is invalid
4	NOT_FOUND	Card not found

Redeem API:

To redeem a gift card distributed by BlackHawk, you just need to call our Purchase Webservice with the following data:

Method: POST

Endpoint: https://purchase.kwsdk.io/api/1.0/subscription/blackhawk/giftcard/redeem

Headers:

Content-Type: application/json
X-Kiwi-Application-Key: <insert your app key here>

Request body:

{
  "app_install_id": "<the app install id to associate the subscription>",
  "user_uuid": "<the user that this app install belongs to>",
  "account_uuid": "<optional - the account to link with this subscription>",
  "pin": "<the pincode to be redeemed>",
  "media_info": { 
    // optional, refer to the general documentation on giftcards for more details
  }
}

Response:

{
  "status": <status code>,
  "message": "<a status message explaining the operation result - useful for debugging purposes>",
  "blackhawk_status": "<the field responseCode returned as is from UMS>",
  "blackhawk_message": "<a status message explaining the status at BlackHawk - useful for debugging>",
  "subscription": {
    // a KiwiSubscription object representing the created subscription
    // only returned if the redeem operation succeeded
  }
}

If the operation fails, the subscription object is not returned.

The statuses are the following:

Status Code	Status	Message
0	UNKNOWN	An unknown error has happened
1	SUCCESS	The redeem at BH was successful, the subscription was registered at Kiwi and linked to the given account
2	SUCCESS_REDEEM_BUT_REGISTER_SUBSCRIPTION_FAILED	The giftcard was redeemed at BH but no subscription was created at Kiwi
3	SUCCESS_REDEEM_BUT_ACCOUNT_LINK_FAILED	The giftcard was redeemed at BH and a subscription has been created at Kiwi, but the platform failed to link it to an account. This status will also be returned if the field account_uuid was not specified on the request
4	FAILED	General failure

For details on BlackHawk's status codes, please refer to the BHNUMS documentation.