Introduction

Welcome to GiftPesa! Giftpesa is a gift management platform that automates the entire process of buying, disbursing and redeeming gift rewards.

You can use our api to disburse vouchers and track redemption of the disbursed vouchers in realtime

We currently have language bindings in Shell(Curl)! You can view code examples in the dark area to the right.

Incase of any difficulties reach out to us via email

Authentication

The Giftpesa API uses Access token keys to authenticate requests. On your gitpesa dashboard head to settings to generate your API Keys

and .crt files.

Your API keys carry many privileges, so be sure to keep them secure! Do not share your secret API keys in publicly accessible areas such as GitHub, client-side code, and so forth.

Generating Access token

To generate authorization token

curl "https://3api.giftpesa.com/authorize" \
  -H "Authorization: Basic <Base64 encoded string>" \
  -H "Username: <your account username>

HTTP Request

GET https://3api.giftpesa.com/authorize

To generate acess token generate the api key from the Giftpesa dashboard and get the Timestamp in yyyymmddhhmmss format. When you generate the API Key you also get access to key.crt file which will be used to encrypt requests

Once you have access to both the API KEY and Pem file, Encrypt the API_KEY:TIMESTAMP with the CRT file and base64 encode the result.

Perform the request to the endpoint to get an access token

Authorization: Basic {base64_encoded_string}

Merchants

curl "https://3api.giftpesa.com/merchants"
  -H "Authorization: Bearer {ACCESS_TOKEN}"

This endpoints the list of merchants and their respective categories

HTTP Request
GET https://3api.giftpesa.com/merchants

Response

[
  {
    "MerchantID": "naivas",
    "Merchant": "Naivas",
    "Category": {
      "ID": "supermarkets",
      "Label": "Supermarkets"
    }
  },
  {
    "MerchantID": "pizza-inn",
    "Merchant": "Pizza Inn",
    "Category": {
      "ID": "cafes-restaurants",
      "Label": "Cafes and Restaurants"
    }
  }
]

Disbursements

Create a new Disbursement

curl "https://3api.giftpesa.com/disburse"
  -H "Authorization: Bearer {ACCESS_TOKEN}"

Example Payload [Name Phone and Amount required in the recipient list]

{
  "DisbursementID": "<DisbursementID>",
  "DisbursementTitle": "XYZ Disbursement",
  "VoucherStartDate": "20210512",
  "VoucherEndDate": "20210820",
  //Merchant Ids, Leave blank for open vouchers
  "Merchant":["naivas","quickmart"],
  "Recipients": [
    {
      "Name": "Jane Doe",
      "Phone": "07XXXXXXXX",
      "Amount": 100,
      ...
    },
    {
      "Name": "John Doe",
      "Phone": "07XXXXXXXX",
      "Amount": 50,
      ...
    },
    ...
  ],
  //Enable redemption from an external paybill
  "External": true,
  "CallbackURL": "https://test2.com",
  "SupressNotifications": true,
}

Response

{
  "DisbursementID": "<DisbursementID>",
  "RecipientsCount": 2,
  "Amount": 150,
  "Cost": 45
  ...
}

This is an object representing creating a new disbursement. You can initiate a new disbursement by invoking a request to the endpoint below.

HTTP Request

POST https://3api.giftpesa.com/disburse

Disbursement Query

curl "https://3api.giftpesa.com/query/:id"
  -H "Authorization: Bearer {ACCESS_TOKEN}"

Response

{
  "DisbursementID": "<DisbursementID>",
  "Status": "success",
  "Amount": 100,
  "RecipientsCount": 1,
  "AmountDisbursed":100,
  ...
}

This is an object representing querying the status of a disbursement.

HTTP Request

GET https://3api.giftpesa.com/query/:id

URL Parameters

Redeem

curl "https://3api.giftpesa.com/redeem"
  -H "Authorization: Bearer {ACCESS_TOKEN}"

Example Payload

{
  "TransactionID": "<TransactionID>",
  "Name": "Jane Doe",
  "Phone": "+254720XXXXXX",
  "TillNo": "123456",
  "Amount": 10,
  "Remarks": "Weekly shopping",
}

Response

{
  "TransactionID": "<TransactionID>",
  "Status": "success",
  "ReceiptNo": "PEKL98SO",
  "TransactionCode": "A9012333",
  "TrasanctionDate": "2020-28-06 19:02:50",
  "Merchant": "Naivas - EastGate",
  "TillNo": "123456",
  "Amount": 10,
  "Message": "PEKL98SO confirmed. KES 10 redeemed at Naivas - Eastgate on 2020-28-06 19:02:50."
}

This is an object representing redeeming a in one of our partner merchants. You can initiate a new redemption by invoking a request to the endpoint below.

HTTP Request

POST https://3api.giftpesa.com/redeem

Callbacks

** In the case the callback url is unreacheable the system will retry upto 10 times in the next hour after initial try **

Disbursement Callback

POST <your callback url> This represents the structure of the payload to expect on the callback url

Redemption Callback

POST <your callback url> This represents the structure of the payload to expect on the callback url

• More than one voucher code may be affected by a transaction initiated by a customer e.g a customer may have two vouchers and redeem both at the same transaction. The VoucherCodes property will contain an array of both voucher codes ([Voucher Code 1, Voucher Code 2])

Errors

GiftPesa uses the following error codes