Information

Point Of Sales Integration Documentation

Welcome to the Avenum POS Integration Documentation! This guide provides detailed instructions for integrating your Point-of-Sale (POS) system with our service. By connecting your POS system to Avenum, you can offer customers a streamlined shopping experience, allowing them to scan barcodes, add items to a cart, and generate a QR code for seamless checkout at physical terminals. Additionally, businesses can easily register their company information within the Avenum platform, making it more accessible to users.

Advice: For a quicker setup, refer to our short documentation. It’s a simple five-step process to integrate our service with your POS system. Register here to get started.

Target Audience:
This documentation is intended for businesses and developers seeking to integrate their POS systems with Avenum’s service. It provides step-by-step guidance on how to configure your POS system to scan customer-generated QR codes to retrieve shopping cart details via HTTP requests, calculate the total price, and include discounts and memberships. By completing this integration, your POS system will seamlessly interact with Avenum, enhancing the checkout process and improving the overall customer experience.

Objectives:

  • Create an account to generate checkout simulations for POS integration testing.
  • Get clear instructions on updating your POS (Point of Sale) system to leverage all the features and benefits our service offers.

This documentation covers the following aspects:
  • Account: Understand how to set up and manage your account to access all features and resources.
  • QR Code Scanner: How to use a barcode scanner and integrate it to make the checkout process smoother for your customers.
  • Point-Of-Sales (POS): How our service works seamlessly with your POS system to ensure a smooth and convenient purchase experience for your customers.

Benefits of Using Our Service:
  • Competitive Advantage for Your Clients: By integrating our service, your POS system offers store owners an advanced, streamlined checkout process, enhancing the shopping experience and helping them attract and retain customers.
  • Revolutionized Checkout for Retailers: Empower your clients with a modern, efficient checkout experience that leverages QR code scanning and digital cart retrieval, delivering an innovative solution for today's retail environment.
  • Cost-Efficient Solution: Our service helps store owners reduce operational costs by minimizing the need for additional cashier personnel, offering a cost-effective alternative without compromising on service quality.
  • Seamless and Fast Transactions: Enable your clients to provide faster checkouts, reducing customer wait times and creating a smoother, more enjoyable shopping journey.

Setup

To test our service, there are a few essential steps you must follow to ensure smooth operation. Below, we'll detail each requirement:

Account Registration

To test the integration between your POS system and Avenum's service, you'll need to create an account on our platform. Once registered, you can create checkout dummies and generate QR codes that simulate the QR codes produced when a customer approves their shopping cart. This allows you to scan the generated QR code and test the communication between your POS system and our service.

  • Visit Account Register-page in your web browser.
    Note: This link is specifically for companies looking to integrate our service with their POS system and should not be confused with the account registration page for stores.
  • Provide the required details, such as your company name, email address and a secure password.

For further information on setting up your account, please refer to the "Account Setup" section below.

Point-of-Sales (POS) System Update - Information

To fully leverage our service, ensure your POS system is equipped with an up-to-date QR code scanner and software. This integration enables your POS system to scan customer-generated QR codes and make HTTP requests to retrieve the full shopping cart details, including product information, membership ID and discount code. Keeping your system updated ensures a seamless, efficient, and modern shopping experience for both your business and your customers.

How it Works:

When a cashier or self-checkout scanner scans the QR code created by our app, the Point of Sale (POS) system will receive shopping cart information. Developers need to ensure that the POS system can handle this data, perform the required calculations, and provide a smooth checkout experience. Here’s a simple overview of what the system should do:

  1. POS System Integration

    • The POS system scans the QR code generated by the Avenum app. This QR code contains a special CHECKOUT ID linked to the customer’s shopping cart. For example, the CHECKOUT ID could be: PBWAMC5R3K5DTE.
    • The POS sends an HTTP request to the Avenum server, including the CHECKOUT ID in the URL. This step helps the POS system get the customer's shopping cart details. 
      https://avenum.se/api/v1/checkout/?checkoutId=PBWAMC5R3K5DTE
    • After sending the request, the POS system receives all the information about the shopping cart, such as the items the customer has added, discount and membership card.
    • The POS calculates the total price by going through each item and applying discount and membership card savings where needed.
    • Finally, the total amount is shown on the POS terminal, and the customer can proceed to pay for their items.
  • Looping Through Product IDs (UPC):

    The POS system should loop through the Product IDs (UPC/Barcode) received from the HTTP response. By matching these IDs with the products in the system's database, it should collect the necessary information for processing. While displaying product titles and images on the customer display screen is optional, the system must accurately calculate the total price, just as it would if the cashier were scanning barcodes individually.

  • Reading Membership ID and Coupon ID:

    If a membership ID or discount ID is present in the QR code data, the POS system should extract and read these IDs. This enables the system to apply any relevant discounts or special offers associated with the membership or coupon.

  • Calculating Total Price:

    After the POS system has made an HTTP request, it should loop through all the products to calculate their individual prices and the total sum, providing the customer with the final amount to pay.

To simplify the process: The POS scans the QR code, includes the code in the HTTP URL, receives the shopping cart details, calculates the total price, and applies discounts or memberships.

Point-of-Sales (POS) System Update - Testing

In this section, we will guide you through updating your Point-of-Sale (POS) system. We will explain how to create checkout dummies for testing your POS with our service, ensuring accurate calculations and retrieval of the correct information.

How it Works:

The image below shows the generated QR code with the value PBWAMC5R3K5DTE. The POS system must include the value of the generated QR code in its HTTP request to retrieve the corresponding shopping cart details from our database.

Example of a HTTP link: 

https://avenum.se/api/v1/checkout/?checkoutId=PBWAMC5R3K5DTE

NOTE: The Checkout ID can be found in the table (on the QR Checkout Dummy-page) once you create a checkout dummy. Include the Checkout ID when making the HTTP request.

Below is an example of HTTP response that showcases the data received by the POS system after scanning the QR code:

{
    "ProductIDs": ["UPC123", "UPC456", "UPC789"],
    "MembershipId": "MEM123",
    "DiscountId": "COUP456"
}

Instead of generating a QR code directly in the mobile app, you can create checkout dummies that generates a QR code. Scanning the QR code will provide a CHECKOUT ID value that you can use to make an HTTP request and retrieve the necessary information, as shown in the example code above.

QR Checkout (Testing)

This section will guide you in generating customized QR codes for testing the integration between our service and your POS system.

The Importance of Testing with QR Codes:

Testing QR codes is essential to ensure that your POS system accurately processes the data they contain. If the QR codes are not scanned correctly or if the values retrieved are incorrect, your customers will face issues using our service, leading to potential disruptions and dissatisfaction.

By thoroughly testing the QR codes before deploying them in a production environment, you can verify that all data—such as discount, membership, and product IDs—is processed correctly, ensuring a smooth and reliable experience for your customers.

Requirement:

(POS) Point of Sale System and QR Code Scanner

Step by Step Guide:

  1. Accessing the QR Code Generator:

    • To access the QR Checkout (Testing)-page, you must log in to your account. If you do not have an account, you can register here for testing purposes.

  2. Entering QR Code Information:

    • Add product IDs (barcodes) in the provided textbox. These will then appear in the dropdown menu. You can optionally enter a discount ID and a membership ID in the designated field.
    • Click the "Generate QR Code" button to create your custom QR code.
    • Copy the link for testing purposes (found under API URL For Testing) and integrate it into your POS system.
      • To make a HTTP request to the API, here is an example of how you can perform an HTTP GET request in 
        public static async Task Main(string[] args)
{
    HttpClient client = new HttpClient();
    string CHECKOUT_ID = "ABC123"; // Replace with the scanned QR code value
    string url = $"https://avenum.se/api/v1/checkout/?checkoutId={CHECKOUT_ID}";

    HttpResponseMessage response = await client.GetAsync(url);
    response.EnsureSuccessStatusCode();
    string responseBody = await response.Content.ReadAsStringAsync();
    
    ShoppingCartInfo shoppingCartInfo = JsonConvert.DeserializeObject<ShoppingCartInfo>(responseBody);
    foreach (var productId in shoppingCartInfo.ProductIDs)
    {
        // Retrieve product info based on Product ID (simulating cashier behavior)
        Console.WriteLine("Product ID: " + productId);
        // Here you would add code to retrieve and display product details
    }

    Console.WriteLine("Membership ID: " + shoppingCartInfo.MembershipId);
    Console.WriteLine("Discount ID: " + shoppingCartInfo.DiscountId);
}

public class ShoppingCartInfo
{
    public string MembershipId { get; set; }
    public string DiscountId { get; set; }
    public List<string> ProductIDs { get; set; }
}
    • The CHECKOUT_ID should change based on the scanned QR code. Make sure to replace CHECKOUT_ID with the actual value.
    • Once you receive data from the HTTP request, loop through the product IDs, apply discounts and memberships, and calculate the total for customer payment.

    3. If you encounter any difficulties during testing, please feel free to reach out to our support team for assistance.

  3. From Test to Production:

    • After successful testing, replace the hardcoded checkout ID with the scanned QR code value to transition to production:
      From: https://avenum.se/api/v1/checkout/?checkoutId=PBWAMC5R3K5DTE
      To: https://avenum.se/api/v1/checkout/?checkoutId={SCANNED_QR_CODE_VALUE}