Burns

3.3 Payments made using the KENZ'UP app (Payment Request)

The KENZ'UP app enables mobile payment using bank cards or a mobile wallets. A customer is also able to complete purchases using their earned points. The till shows a QR code that the customer will scan to pay for their purchase. KENZ'UP needs to be made aware of the full amount of the sale that will be completed. And similar to the Earn Request, the polling path and the sale's deeplink are returned.

Similar to the Earn Request, a customer can be assigned to the sale with the same way and same constraints.

It is possible to allow a customer to make a partial payment out-of-app and pay the rest in-app using a single Qr scan. This is a special type of in-app payment called Hybrid Payment. To do so, the request payload must contain amount with the value of the partial payment to be made in-app alongside with sale_amount containing the total amount. This would return a response exactly similar to the case of a usual in-app payment, and when the Qr is successfully scanned the customer would receive the usual cashback for the sale amount excluding points amount. It's also possible to explicitly allow users to pay less than what's specified in amount by setting error_on_partial to false which is by default set to true.

P.S: After a sale record has been created in both Earn and Payment actions, it can no longer be updated, which means all subsequent requests data should be consistent (same amount, same customer even if null...), otherwise an error is thrown.

POST /api/v1/shops/<shop_uuid>/payment-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
sale_amount	float	(optional) The total amount of the 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 (pay)
amount	float	(optional) The amount to be paid in-app. If sale_amount is not set, this is considered as the total amount. Default is 0
error_on_partial	bool	Set to false to explicitly allow partial payment (optional. default is true)

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.06",
 "cashback_override_reason": "sample reason",
 "paid_amount": 5.00,
 "error_on_partial": false
}

{
 "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",
 "paid_amount": 5.00,
 "error_on_partial": false
}

Response Parameters:

Parameter	Type	Description
order_id	string	The unique ID representing this sale
body	string	The content of the QR code that needs to be generated (sale UUID)
b64_Qr	string	base64 encoded representation of a branded Payment Qr code PNG image
polling_path	string	The API endpoint to hit to get the status of a payment
deeplink	string	Sale deeplink in the format kenzup://Sale/{sale_uuid}

The b64_QR is handled the same way as in the Earn request

Sample Response:

{
 "order_id": "TX_123456789",
 "body": "bc4d0749-c820-4957-91e3-34a258666081",
 "polling_path": "https://app.kenzup.com/api/v1/shops/2975a9b4-466e-47d9-af8a-247d62520a2e/payment-request/TX_123456789",
 "deeplink": "kenzup://Sale/bc4d0749-c820-4957-91e3-34a258666081",
 "b64_QR": "iVBORw0KGgoAAAANSUhEUgAAAcIAAAHCCAIAAADzel4SAAAltklEQVR4nO3debSkd13n8c/
 [[[****TRUNCATED****]]]
 B7Kh20TdU38pAAAAAElFTkSuQmCC"
}

3.4 Getting the status of a payment request

GET /api/v1/shops/<shop_uuid>/payment-requests/<order_id>

Response Parameters:

Parameter	Type	Description
status	string	The status of the payment (pending|approved|declined|error)
order_id	string	unique ID of the sale
shop_uuid	string	UUID of the shop where the sale is made
sale_amount	float	The sale total amount
amount	float	The amount specified on the Payment Request (if any). Defaults to sale_amount value
paid_amount	float	the amount actually paid in-app
expires_at	string	ISO 8601 string representing the expiry of the sale (the Qr generation)

Sample Response:

{
 "status": "Pending",
 "order_id": "TX_123456789",
 "shop_uuid": "2975a9b4-466e-47d9-af8a-247d62520a2e",
 "sale_amount": 12.45,
 "amount": 5.00,
 "paid_amount": 5.00,
 "expires_at": "2020-02-12T19:25:30+01:00"
}