Transactions ‐ QR Code scanning - kangaroorewards/api-docs GitHub Wiki

How to Create Transactions Based on QR Code Scanning

In this tutorial, we will demonstrate how to create transactions using the Kangaroo Rewards API by scanning a sale receipt QR code. The QR code information will be decoded and sent as part of the transaction creation request.

Objective: Learn how to create transactions based on QR code scanning using the Kangaroo Rewards API.

Prerequisites:

  • Basic understanding of APIs and HTTP requests.
  • Basic understanding of encryption and decryption algorithms.
  • A registered business account with Kangaroo Rewards.
  • Client ID and client secret from an OAuth2 application that has been approved.
  • An API client like Postman or cURL installed.
  • A QR code scanner or a method to obtain the QR code information.

Step-by-Step Instructions

Step 1: Encrypt a sale info and prepare a QR code

In this example we are going to use AES-256-CBC cipher, Encryption Key: QmIpQaZiJKwjCY2I74maS3lcRLQfiahuhrgsEYlc4iA=, IV: 1Tw0k6SYJQBDThQ+ANqV6g==, PHP, openssl_encrypt, and openssl_decrypt functions.

A sale info payload should have the following structure:

{
    "businessId": 125,
    "currency": "USD",
    "amount": 49.99,
    "timestamp": "2023-12-06T10:34:52",
    "locationId": 1001,
    "invoiceId": "12399998"
}

The minimum required attributes are the following:

  • businessId: This attribute represents the unique identifier for a business entity. In this case, the value is 125.
  • currency: This attribute specifies the currency being used, which is "USD" (United States Dollar).
  • amount: This attribute represents the monetary amount, which is 49.99.
  • timestamp: This attribute stores the date and time of the transaction or event in the ISO 8601 format, which is "2023-12-06T10:34:52".
  • locationId: This attribute identifies the specific location associated with the transaction or event, which is 1001.
  • invoiceId: This attribute holds the unique identifier for the invoice, which is "12399998".

Here are the steps to encrypt and encode the QR Code:

  1. JSON Encode the payload (amount, invoice, currency, timestamp etc.)
  2. Encrypt the JSON string from the step 1 with AES-256-CBC algorithm, with a key and IV, both base64 encoded
  3. Generate a QR Code with the result from step 2. You can use any QR Code library or a specialized website, for example: qr.io.

You can find a working example here. PHP and Bash code sample here

Step 2: Set up your environment

Before making any API requests, you need to obtain an access token by authenticating your application with Kangaroo Rewards. Refer to the OAuth - Password Credentials Grant section in the API documentation to learn how to request an access token using the "password" grant type.

Ensure you have an Access Token and X-Application-Key from Kangaroo Rewards. These keys are necessary for authenticating your API requests.

Example cURL request:

curl --request POST \
  --url https://api.kangaroorewards.com/oauth/token \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data grant_type=password \
  --data client_id={YOUR_CLIENT_ID} \
  --data client_secret={YOUR_CLIENT_SECRET} \
  --data username={YOUR_USERNAME} \
  --data password={YOUR_PASSWORD} \
  --data scope=admin \
  --data application_key={YOUR_APPLICATION_KEY}

Step 3: Obtain the QR Code Information

Use a QR code scanner or a mobile app with a QR code scanner built in to scan the sale receipt. The scanner should provide an encrypted string, which represents the QR code information.

Step 4: Make a POST Request to Create a Transaction

Use the encrypted QR code information and make a POST request to the Kangaroo Rewards API to create a transaction. Replace the placeholder values with actual data.

Create a JSON object containing the following data:

intent: Set to "qr_code" to indicate that the transaction is being created based on a QR code scan. customer: This is a nested object containing the id of the customer associated with the transaction. qr_code_info: The encrypted string obtained from decoding the QR code.

curl --request POST \
  --url https://api.kangaroorewards.com/transactions \
  --header 'Accept: application/vnd.kangaroorewards.api.v1+json;' \
  --header 'Authorization: Bearer YOUR_ACCESS_KEY' \
  --header 'Content-Type: application/json' \
  --header 'X-Application-Key: YOUR_APPLICATION_KEY' \
  --data '{
  "intent": "qr_code",
  "customer": {
    "id": "CUSTOMER_ID"
  },
  "qr_code_info": "ENCRYPTED_QR_CODE_INFO"
}'

Replace the following placeholders:

  • YOUR_ACCESS_KEY: Your API access key.
  • YOUR_APPLICATION_KEY: Your application key.
  • CUSTOMER_ID: The unique identifier of the customer.
  • ENCRYPTED_QR_CODE_INFO: The encrypted string obtained from the QR code.

Step 5: Handle the Response

The API will respond with the details of the created transaction. Handle the response appropriately in your code.

response=$(curl --request POST \
  --url https://api.kangaroorewards.com/transactions \
  --header 'Accept: application/vnd.kangaroorewards.api.v1+json;' \
  --header 'Authorization: Bearer YOUR_ACCESS_KEY' \
  --header 'Content-Type: application/json' \
  --header 'X-Application-Key: YOUR_APPLICATION_KEY' \
  --data '{
  "intent": "qr_code",
  "customer": {
    "id": "CUSTOMER_ID"
  },
  "qr_code_info": "ENCRYPTED_QR_CODE_INFO"
}')

echo "Response: $response"

Conclusion

In this tutorial, we covered how to create transactions based on QR code scanning using the Kangaroo Rewards API. By following these steps, you can streamline the process of recording transactions through QR codes, enhancing customer experience and operational efficiency.

Best Practices

  • Ensure the QR code information is correctly encrypted, decoded and formatted before sending the API request.
  • Handle API responses and errors appropriately to manage failed requests.
  • Securely store your API keys and avoid exposing them in your code or public repositories.
  • Optimize your API usage by minimizing the number of requests and handling rate limits.
  • Comply with the QR code encoding limitations.

Additional Resources

Troubleshooting

  • Verify that the encrypted QR code information is correctly obtained and formatted.
  • Ensure your Access Token is correct, has not expired, and has the necessary permissions (401 Unauthorized error).
  • For 400 Bad Request errors, check if the qr_code_info parameter is correctly decoded.
  • Missing or incorrect fields after decrypting the QR code. Verify that the decryption process is working correctly, and the resulting string is in the expected format. Inspect decrypted string, by examining the decrypted string to identify any missing or incorrect fields.
  • Expired QR Codes. Check the expiration date of the QR code to ensure it has not expired. If the code has expired, update the expiration date or generate a new QR code with a valid expiration date.
  • Codes that have already been scanned. If the code has already been scanned, the API will return an error.
  • Review the error messages returned by the API for clues on what went wrong.