Dynamic Offers

The APIs are organized around REST. The APIs use conventional HTTP response codes to indicate
the success or failure of a request. In general, codes in the 2xx range indicate success. Codes in
the 4xx range indicate a request that failed given the information provided (e.g., a required
parameter was omitted, etc.). Codes in the 5xx range indicate an error with the API.

The APIs will be used for validating users, fetching customer offers, fulfilling offer purchases, and
querying Mpesa transaction status.

API Definition`

Access token API

Customers logged in are identified by their token. From the token, we can get the associated
user system permissions against which we can verify if the user is authorized to access the
specified resource. Request for the token using basic auth credentials provided under the
Authorization tab.

Once a token is acquired by calling the access token API, pass it to the product purchase, fetch
offer, and get request status APIs in the authorization tab under the bearer token. The token
should be refreshed when expired.

PATH: https://apistg.safaricom.co.ke/oauth2/v1/generate?grant_type=client_credentials

HTTP METHOD: POST

grant_type is passed in the query string as a parameter.

Response Body:

Parameter Description
access_token A unique identifier for the token
expires_in Token lifecycle in seconds
Sample response
C3
{ -
"access_token": "9yljbhAatRBgEApf8c7zmr0KevDz", Saf
"expires_in": "3599" aric
} om
Co
nfi
de
nti
al
Ext
ern
al
Fetch offers API
This endpoint is for fetching the customer offers.

PATH: https://apistg.safaricom.co.ke/v1/dynamic-offers/fetch?msisdn=254708391435

HTTP METHOD: GET

Response Body:

Parameter Description
id Unique identifier for the operation
A message indicating whether a request has been successfully
desc
completed
status Status code indicating the result of the operation
lineItem A list of the offers
characteristicsValu
A list of the offers
e
offerName The price of the product and the resource to be awarded.
offeringId The unique number of the product
offerUssdName The price of the product and the resource to be awarded.
resourceAccId The unique number of the account that contains resources
offerPrice The product price
resourceValue The amount of resources to be awarded in MBs
offerValidity The product validity in days/hours
offerSource The product category
locationId The unique number of the location of the product
subscribed Indicates if the customer has bought the product
childOffers Indicates if the product contains other products

Sample response

{
"id": "",
"desc": "Success",
"status": "1000",
"relatedSusbscription": null,
"lineItem": {
"characteristicsValue": [
{
"offerName": "Sh20=1GB 1hr",
"offerValidity": 1,
"resourceAccId": 5158,
"resourceValue": 1024,
"offerPrice": 20, C3
"offerUssdName": "Sh20=1GB 1hr", -
"offeringId": 50502021,
"offerSource": "CVM1",
Saf
"locationId": null, aric
"subscribed": null, om
"childOffers": [] Co
},
{ nfi
"offerName": "Sh99=1GB 24hr", de
"offerValidity": 1, nti
al
Ext
ern
al
 "resourceAccId": 2572,
"resourceValue": 1024,
"offerPrice": 99,
"offerUssdName": "Sh99=1GB 24hr",
"offeringId": 28042021,
"offerSource": "CVM2",
"locationId": null,
"subscribed": null,
"childOffers": []
},
{
"offerName": "Sh250=2GB 30Days",
"offerValidity": 30,
"resourceAccId": 2401,
"resourceValue": 2048,
"offerPrice": 250,
"offerUssdName": "Sh250=2GB 30Days",
"offeringId": 20220124,
"offerSource": "CVM3",
"locationId": null,
"subscribed": null,
"childOffers": []
},
{
"offerName": "Sh500=5GB 30Days",
"offerValidity": 30,
"resourceAccId": 2401,
"resourceValue": 5120,
"offerPrice": 500,
"offerUssdName": "Sh500=5GB 30Days",
"offeringId": 20220124,
"offerSource": "CVM4",
"locationId": null,
"subscribed": null,
"childOffers": []
}
]
}

Description:
When a customer opens the TikTok app, the Fetch offers API is called, and msisdn is passed in
the query string as a parameter. The API returns a payload with the offer object. Display to the
customer the value of offerName.

C3
Optional: -
Saf
1.To filter out gift offers and offers not in scope, use the offerSource on the API and set it to aric
select only the offerSource CM1,CVM2,CVM3,CVM4, and CVM5 om
Co
2. For header enrichment implementations, add the header x-key-type and set header to 1 for nfi
encrypted Msisdn’s and 0 for plain Msisdn’s de
nti
al
Ext
ern
al
Offer purchase API
This endpoint is for fulfilling all the product/offer purchases.

PATH: https://apistg.safaricom.co.ke/v1/dynamic-offers/facebook-bundle/purchase

HTTP METHOD: POST

Request Headers:
Field Data Type Description

x-source-system String Indicates the source system making the request.

In this case, it is TikTok.
Accept-Encoding String Indicates the supported response encoding
format. In this case, it is gzip, deflate, br.
Accept String Specifies the desired format of the response. In
this case, it is */*.
Content-Type String Indicates the format of the request payload. In
this case, it is application/json.
Content-Security-Policy String This controls resources that a browser can load on
a web page. In this case, it is default-src 'none'.
X-Frame-Options String This allows the web page to be rendered in the
frame. In this case, it is DENY.
X-Content-Type-Options String Prevents MIME-sniffing a response away from the
declared content-type. In this case, it is nosniff.
Authorization String Contains the authentication credentials to access
the resource. In this case, it is Bearer.
x-correlation-conversationid String A unique identifier for the conversation between
the client and server. In this case, it is a
timestamp.
x-msisdn String The customer number that is making the request
x-key-type Boolean 1 means encrypted and 0 means plain Msisdn- For
header enrichment implementation

Request Body:
C3
Parameter Description Required Sample Value -
MSISDN The mobile number of the customer Yes 254705915690 Saf
OfferingID The unique number of the product Yes 28042021 aric
paymentMode The mode of purchase Yes Airtime/Mpesa om
The unique number of the account Co
accountId Yes 2572
that contains resources nfi
price The product price Yes 5 de
nti
al
Ext
ern
al
 The amount of resources being
resourceAmount Yes 50
awarded in MBs
validity The product validity in days/hours Yes 1
transactionId The x-correlation-conversational value Yes 1

Sample request

{
"offeringId": "28042021",
"accountId": "2572",
"price": "5",
"resourceAmount": "50",
"validity": "1",
"msisdn": "795898572",
"transactionId": "1",
"paymentMode": "airtime"
}

When a customer makes a payment for an offer, the Offer purchase API is called. From the
response body, the customer should see the customerMessage.

Response Body:

Parameter Description
requestRefId A unique identifier for the operation
responseCode Status code indicating the result of the operation
A message indicating whether a request has been
responseMessage
successfully completed
customerMessage The message that is shown to the customer
timestamp Time of the request
Sample response

{
"header": {
"requestRefId": "ac5633a7-ad08-4b61-8e77-30d83903fb58",
"responseCode": 200,
"responseMessage": "operation successful",
"customerMessage": "Bundle purchase was successful",
"timestamp": "2023-06-08T16:38:01.838453"
}
}

C3
-
Parameter Mappings
Saf
The parameters of the Get Offers API and the Offer Purchase API will be mapped as follows. aric
om
Get Offers API Offer Purchase API Co
offeringId offeringId nfi
resourceAccId accountId de
nti
al
Ext
ern
al
 offerPrice price
resourceValue resourceAmount
offerValidity validity

Get request status API

This endpoint is for querying the status of Mpesa purchases. Mpesa is Async. Use the API to tell
if the purchase request was successful or not.

PATH: https://apistg.safaricom.co.ke/subscriptionAPI/v2/subscription?
id=1684930301&serviceAccountId=0

HTTP METHOD: GET

Id and serviceAccountId are passed in the query string as parameters. Id is the transactionId
that is passed on the request payload of the purchase request, and serviceAccountId is 0
(implying a dynamic offer).

Response Body:

Parameter Description
responseId A unique string that identifies the response
A message indicating whether a request has been
responseDesc
successfully completed.
Status code indicating whether a request has been
responseStatus
successfully completed
responseCreated Record of the time of the request

Sample response

{
"responseId": "788797897889",
"responseDesc": "Successful bundle purchase",
"responseStatus": "1000",
"responseCreated": "20230609143000543"
}

C3
-
Saf
aric
Query balances API om
Co
This endpoint is for querying a customer’s airtime, okoa, and mpesa balances. Search customer’s nfi
balance by Id (521) and by customer number (msisdn). The airtime and okoa account balances de
nti
al
Ext
ern
al
are returned in Kenya shillings. If there is no balance in the account, zero is returned. For mpesa,
true or false will be returned, true to imply the account has money, and vice versa.

PATH: https://apistg.safaricom.co.ke/v1/fb-okoa/queryBalance?id=521&customerNumber=795898572

HTTP METHOD: GET

Request Headers:
Content-Type: application/json
Accept-Encoding: application/json
x-source-system: fb
x-correlation-conversationid: {{$timestamp}}
x-route-id: fb-okoa-query-balance
Authorization: Bearer access_token

Params:
customerNumber: 795898572
id: Can be left as is or pass nothing.

Response Body:
Parameter Description
id A unique string that identifies the response
responseDesc The response message from the server
status Response code from the server
airtimeBalance Customer airtime account balance
okoaBalance Customer okoa (data loan) account balance
mpesaBalance Customer mpesa account balance
Sample response

{
"id": "srcreqid-16901905231280-3106617-1-20230724122204",
"responseDesc": "Operation Successful",
"status": "1000",
"airtimeBalance": "19637.00",
"okoaBalance": "0.00",
"mpesaBalance": "false"
}

curl --location 'https://apistg.safaricom.co.ke/v1/fb-okoa/queryBalance? C3

id=0&customerNumber=795898572' \ -
--header 'Content-Type: application/json' \
Saf
--header 'Accept-Encoding: application/json' \
aric
--header 'x-source-system: fb' \
--header 'x-correlation-conversationid: 1690190616' \ om
--header 'x-route-id: fb-okoa-query-balance' \ Co
--header 'Authorization: Bearer p3HHDACsK7zpLucBlOLCryQ2uvAr' \ nfi
--header 'Cookie: de
incap_ses_1020_2912339=8pkbNMUcJH1CX3b+msUnDlkrvmQAAAAAt50zyEdsGtfV6+9AoSpMqQ==; nti
al
Ext
ern
al
incap_ses_1023_2912339=k9V7Ws3PwXH6ib/sFm4yDhopvmQAAAAA77DlJ6kC0DSg7wnokpKptQ==;
incap_ses_1025_2912339=0UOUKM+4Uk7uB3NB/4g5DjdCvmQAAAAAYziEIQSPyAdroXPH5AvcJg==;
visid_incap_2912339=Xp7+kJS4TaqvD7wqzuaXg5e+pmQAAAAAQUIPAAAAAAC5EvGdlFTO8x/mjL2KyDar;
JSESSIONID=node0xga88ioadege13041fyitj5174.node0'

C3
-
Saf
aric
om
Co
nfi
de
nti
al
Ext
ern
al