Earns
3.2 Earning on completed sales with payment “out-of-app” (Earn Request)
Customers can earn points on their sales in partnering shops. If a sale is done “out-of-app”, meaning paid for in cash or by any other means not associated with the KENZ'UP app, the customer will have to scan a QR code to earn the points for that complete sale. This QR code can be displayed on the printed receipt or directly on the shop till for a short period of time after the sale has been completed.
The KENZ'UP platform will need to be made aware of a sale that has been completed, to allow the customer to earn their points after the fact. In addition, this will allow the platform to limit fraud as much as possible. An API call should be made to provide KENZ'UP the information needed for the content of the QR code that the shop will need to generate and display.
A sale can be assigned to a specific customer by its phone number beforehand so that only that customer can scan the generated Qr (pay/earn).
The earn operation can be forced so that the customer would get points from the sale immediately without scanning the Qr using the force parameter within the request payload.
If an earn is forced with a non-registered mobile number, a special type of credit is saved (to be granted to the customer as soon as they are registered, or turned into vouchers in case the sale is made by Afriquia Gaz brand) instead of returning a scannable Qr. This is possible only from the first successful try, which means once a sale is created (identified by its order_id) it cannot be forced for a non-registered customer even if it's not scanned yet.
A polling endpoint is also returned to allow the till to check if the sale has been completed successfully, as well as a deeplink for E-commerce transactions
As part of the onboarding of a new shop, the KENZ'UP integration team will assign a shopId that will be used to link a sale to a shop.
POST /api/v1/shops/<shop_uuid>/earn-requests
Request Parameters:
| Parameter | Type | Description |
|---|---|---|
terminal_id | string | A unique ID for the POS/terminal/till |
agent_id | string | (optional) ID of the agent/cashier performing the transaction |
amount | float | The amount of the completed sale |
currency | string | ISO 4217 code of the currency of the completed sale (e.g. MAD for Moroccan dirham) |
cashback_rate_override | float | (optional) The cashback rate override |
cashback_amount_override | float | (optional) The cashback amount override |
cashback_override_reason | string | (optional) The chashback override reason |
order_id | string | A unique ID representing the completed sale that can be used later on to refund or for reconciliation |
time | string | ISO 8601 string representing the time the sale was completed |
customer | string | (optional) E.164 format or national (06/07xxxxxxxx) mobile number of the sale owner (customer) to allow only them to scan the Qr (earn) |
force | bool | (optional) set to true to force the points earn, i.e. the customer would get the points immediately without scanning the Qr. In this case, the customer parameter is required |
Sample Request:
{
"terminal_id": "POS_123456789",
"amount": 12.45,
"currency": "MAD",
"order_id": "TX_123456789",
"time": "2020-02-12T19:20:30+01:00",
"customer": "+212611223344",
"cashback_rate_override": "0.05",
"cashback_override_reason": "sample reason",
"force": true
}
{
"terminal_id": "POS_123456789",
"amount": 12.45,
"currency": "MAD",
"order_id": "TX_123456789",
"time": "2020-02-12T19:20:30+01:00",
"customer": "+212611223344",
"cashback_amount_override": "12.34",
"cashback_override_reason": "sample reason",
"force": true
}
Response Parameters:
| Parameter | Type | Description |
|---|---|---|
order_id | string | The unique ID representing this sale |
points | integer | The amount of points the customer can earn |
message | string | A message that should be displayed with the QR |
body | string | The content of the QR code that needs to be generated (sale UUID) |
deeplink | string | Sale deeplink in the format kenzup://Sale/{sale_uuid} |
polling_path | string | The API endpoint to hit to get the status of the sale |
b64_QR | string | base64 encoded representation of a branded Earn Qr code PNG image |
Sample Response:
{
"order_id": "TX_123456789",
"points": 30,
"message": "Recevez 5 points de fidélité en téléchargeant Kenz'up!",
"body": "269cac45-0684-4338-8831-9d3f7324106d",
"deeplink": "kenzup://Sale/269cac45-0684-4338-8831-9d3f7324106d",
"polling_path": "https://app.kenzup.com/api/v1/shops/269cac45-0684-4338-8831-9d3f7324106d/payment-request/TX_123456789",
"b64_QR": "iVBORw0KGgoAAAANSUhEUgAAAcIAAAHCCAIAAADzel4SAAAltklEQVR4nO3debSkd13n8c/
[[[****TRUNCATED****]]]
B7Kh20TdU38pAAAAAElFTkSuQmCC"
}
For example, in python, the b64_QR can be decoded to obtain a PNG image as follows:
import base64
b64_QR = b'iVBORw0KGgoAAAANSUhEUg....'
with open('qr.png', 'wb') as f:
f.write(base64.b64decode(b64_QR))
Sample Response (Forced Earn for Non-registered Customers):
{
"message": "Unregistered customer credit saved",
"mobile_number": "+212611223344"
}