App for Entry & Payment Integration

Overview

In this integration model, the retailer owns the customer-facing mobile application, while AiFi manages store access, session tracking, and checkout automation.

The retailer app is responsible for user authentication and the user interface. AiFi generates and validates entry codes that grant access to the autonomous store, tracks the shopping session, and triggers checkout when the shopper leaves.

This approach enables a seamless and secure shopping experience without requiring any in-store login or payment interaction.

Shopper journey

1. The shopper downloads and registers in the retailer mobile app.
2. The retailer system creates (or retrieves) a customer in AiFi.
3. The shopper requests access to the store from the app.
4. The retailer system requests a new entry code from AiFi.
5. AiFi generates a short-lived entry code.
6. The app renders the entry code as a QR code.
7. The shopper scans the QR code at the store entrance.
8. AiFi validates the entry code and opens the entry gates.
9. The shopper enters the store and shops freely.
10. The shopper leaves the store.
11. AiFi finalizes the shopping session and triggers the checkout webhook.
12. The retailer system processes payment and generates the receipt.

Developer integration flow

Requirements

Before you start, ensure that you have:

• Access to an AiFi sandbox or production environment
• A valid AiFi Admin API token
• A retailer is capable of calling AiFi APIs
• A customer-facing mobile app capable of rendering QR codes
• Access to the AiFi Console, if required

For webhook configuration, see the Webhooks documentation. For authentication, see the Authentication documentation.

Entry code integration

In this part of the app integration, there are two supported entry code flows. The integrator must choose one of the following options:

• Entry code managed by AiFi AiFi is responsible for generating and validating entry codes. In this case, follow the flow "App journey – Entry code managed by AiFi."

• Entry code managed by the integrator The integrator is responsible for generating and managing entry codes. In this case, follow the flow "App journey – Entry code managed by the integrator."

App journey – Entry code managed by AiFi

In this flow, AiFi generates and validates entry codes. The retailer system requests entry codes and the mobile app renders them as QR codes for store entry.

API Endpoints

Step 1: Create a customer

Create (or upsert) a customer in AiFi. This customer ID is required to generate an entry code.

{
  "externalId": "USER_12345",
  "email": "john.doe@example.com",
  "firstName": "John",
  "lastName": "Doe"
}

{
  "id": "1234567890"
}

Step 2: Create an entry code for a customer

Generate a new entry code that the mobile app will render as a QR code. Entry codes are short-lived and should be generated per store visit.

{
  "code": "1234",
  "expiresAt": "2026-02-03T18:30:00Z"
}

Step 3: Verify an entry code (optional)

If you operate your own scanner or need to validate a code before attempting a gate action, you can call the verification endpoint. If AiFi controls the scanner and gates, this step is optional because AiFi validates during scan.

{
  "code": "1234"
}

{
  "valid": true,
  "code": "1234",
  "customerId": 42
}

{
  "valid": false,
  "code": "1234",
  "reason": "expired|not_found"
}

App journey – Entry code managed by the integrator

This section describes the external entry validation webhook used in the App journey – Entry code managed by the integrator, assuming QR code passthrough mode is enabled.

When a shopper scans a QR code at the store entrance, AiFi forwards the scanned code to the integrator’s webhook as the first step of validation. The integrator can perform its own checks (for example payment pre-authorization, eligibility rules, or account status) and return a response indicating whether entry should proceed.

AiFi remains the final authority on granting or denying entry and may still reject access based on internal rules (for example store closed or payment method checks).

API Endpoints

{
  "code": "1234"
}

{
  "status": "ok",
  "customerId": "cust_12345"
}

{
  "status": "ok"
}

{
  "status": "rejected",
  "reason": "invalid_code|expired|not_found|blocked|etc."
}

{
  "message": "Customer id not found"
}

Cart mutator (discounts, taxes, pricing adjustments)

The cart mutator is an optional checkout integration that allows pricing changes before final checkout.

It can be used to apply:

• Discounts and promotions
• Tax calculations
• Price adjustments
• Loyalty or employee benefits

AiFi provides basic tax and discount support, but it is recommended that the integrator owns this logic for full flexibility.

Two models are supported:

• AiFi-managed basket calculation (simple use cases)
• Integrator-managed basket calculation via cart mutator (recommended)

See the Cart mutator documentation for implementation details.

Checkout webhook

The checkout webhook notifies the integrator when a customer has finished shopping and is ready to check out.

When the checkout status is completed, the webhook is triggered with the final basket details and the total transaction amount. If you own the payment flow, you can use this event to charge the customer and update the payment status in your system.

If you need to control or synchronize the order status between AiFi and your backend, you can also rely on the external payment flow using the checkout webhook. For more details, see External payment flow via checkout webhook.

Receipt ownership and receipt disputes

AiFi does not control the payment flow. Receipt creation and delivery must be handled by the retailer application.

Receipt disputes, corrections, and adjustments must also be handled by the retailer backend.

If order data or receipts are modified outside of the cart mutator flow, AiFi will not be aware of those changes. This may cause inconsistencies in AiFi dashboards and reports.

To avoid data desynchronization:

• Apply pricing changes through the cart mutator whenever possible
• Keep order data consistent across systems
• Ensure post-checkout changes are reflected everywhere

API Endpoints

{
  "orderId": 0,
  "message": "",
  "items": [
    {
      "id": 0,
      "productId": 0,
      "contestedQuantity": 0
    }
  ]
}

[
  {
    "createdAt": "2019-08-24T14:15:22Z",
    "id": 0,
    "productId": 0,
    "rin": "string",
    "contestedOrderId": 0,
    "originalQuantity": 0,
    "contestedQuantity": 0
  }
]