Link
Zippie Documentation

This site uses Just the Docs, a documentation theme for Jekyll.

Search

Getting started with Zippie Rewards

Zippie Setup

Before starting you will need a few things from Zippie:

  • Zippie API Key - This is a secret password to zippie services provided by us
  • Zippie Reward Token Address - This is a unique identifier for your reward token

And generate yourself:

  • Secure Hash Prefix - This is a prefix or salt used for cryptographic hashing operations, and should be generated by you and kept safe and secure
  • Secure Private Key -

Reward Token Overview

A reward token is something that you can use to keep track of rewards, these can be redeemed by users for things like Mobile Airtime, Mobile Money, or Vouchers for in-house services.

Client side integration

We recommend using our node.js library @zippie/zippie-utils for integrating the reward service into your application, but other options are available for consuming a RESTful HTTP API

    const reward = require('@zippie/zippie-utils/src/reward')
    reward.init('secure_prefix', 'private_key', 'zippie_api_key')

Identifying a User

You can use your local user identifier (eg. Email) with the Zippie Rewards Service. Before transmitting this information to the Service it will be cryptographically hashed along with the specified Secure Prefix to uniquely identify your User to us without leaking personally identifiable information.

    const userReference = reward.getUserReference('example@email.com')

Rewarding a User

Once a secure User Reference has been created, you can continually allocate rewards to that user.

This is as easy as sending the Reward API a UserReference and a reward amount.

    await reward.rewardUser(userReference, 'reward_token_address', 5)

You can check the balance was received with:

const balance = await reward.getUserBalance(userReference, 'reward_token_address')

Onboarding a User to Zippie Wallet

The first time a user claims reward tokens to their account, they will need to follow a quick onboarding process with the Zippie Wallet.

Claiming Rewards to Zippie Wallet

To let a user claim reward tokens to their wallet they will need a Claim Link.

A Claim Link can be generated by the Reward API and sent to the user

Redirect the user to the claim link, which will claim the rewards and forward the user to their Zippie Wallet for your Reward Token

Zippie Wallet

Once claimed, the user can transfer reward tokens to their friends or redeem for specified rewards though the Zippie Wallet

Business Rule Based Rewards

Rewards can be allocated to users by events in your application, this gives you an easy to configure way to track and control your rewards program and fine tune reward amounts with minimal implementation effort.

Events are sent as a JSON payload to our reward api over http to /event endpoint

Once a business rule is configured in the rewards dashboard, the reward api can respond to generic events like:

{"type":"referral", "userRef":"1234567"}

to reward a user with a fixed reward amount once they refer a new user

Or:

{"type":"purchase", "userRef":"1234567", "purchase_amount":"123.00" }

To reward a user with a fixed reward over a purchase threshold, or reward a percentage of the purchase amount

Conditional Rewards

Rewards can be allocated to a user even if they won’t be claimable until later, for example points for a purchase that will only be claimed after a returns period has passed. These rewards will show up in the Zippie wallet, and will become claimable rewards once released.

Allocating a pending reward to a user

const rewardResponse = await reward.queuePendingReward(userRef, tokenAddress, amount, message, expiry)

const rewardId = rewardResponse.id

Once a pending reward is allocated, it will stay in that state until either released or cancelled, using the following API calls

Releasing a pending reward

const releaseResponse = await reward.releasePendingReward(userRef, rewardId)

Once released the rewards can then be claimed through the normal claiming process

Cancelling a pending reward

const cancelResponse = await reward.cancelPendingReward(userRef, rewardId)

To check what pending rewards are queued for a user, you can check the following:

const list = await reward.getPendingRewards(userRef, tokenAddress)