Skip to main content

FAQ

General​

Can the Oasis API live on-premise?​

In general, no.

Oasis APIs are designed to manage your fleet of stores and should be deployed in a network with accessibility to every store instance. However, in certain circumstances, it's possible to discuss a per-store, on-premise deployment. This setup is discouraged and is individually discussed with the retailer.

Admin API - Customers​

Create customer​

What password do we need to use for creating a customer? Any constant secret value (same value for all accounts)?​

This isn't a required value. We suggest not providing any value if you don't intend your customers to log in with this information. However, if necessary, any random value can be provided.

Due to our data privacy policy, customers' PII information can't leave our environment. Is it possible to initiate the transaction without creating a customer entity, assuming that anonymous customers won't have any associated information in the AiFi system?​

No, it's required to have a customer entity in the AiFi system. However, the entity can be fully anonymous, without any PII. Creating an anonymous customer is simply creating an ID that isn't linked to any PII. If preferred, you can generate a new customer (a new ID) per shopping session, removing the link even between the orders. Note that this may severely impact the metrics provided by AiFi.

Do we still need to pre-register the QR code if anonymous customers have all null attributes?​

Yes.

Create new entry code for the customer​

Will this call return the same values (code, sessionId) if there is an active session available for the AiFi customer?​

AiFi customers can have multiple sessions active independently. "Create new entry code for a customer" is for registering the code for future use, not for verification.

Is the sessionId auto generated if no value is specified or only the code?​

Yes.

What's the purpose of the groupSize value?​

This value is for informational purposes only, indicating the expected group size. If your app supports defining this value, AiFi will store it, but currently, no processing leverages it.

Push API - Entry Codes​

Verify entry code at an external provider​

Is it possible to include the QR code validation status (rejected/approved) in the request body?​

We don't currently forward codes that were rejected in preliminary calls. Rejections can happen, for example, when:

  • A code wasn't pre-registered.
  • The limit of the number of people was reached (configurable).
  • The store isn't open to the public (store status can be CLOSED or CLOSED_FOR_MAINTENANCE, in which case all codes are rejected or all non-employee codes are rejected, respectively).
  • The customer was explicitly blocked from entering.
  • The code was already used (unless it's a consecutive entry of multiple people within the same group with the same QR code).
  • The code expired (the default expiry of QR code is 5 minutes and it's configurable).

If you don't use the people limit or the store status features, all pre-registered codes should be sent to you for verification. However, after the retailer system approves the QR code, the AiFi system can still reject the code if AiFi is in charge of the payments and:

  • The customer's payment method expired.
  • The customer has unpaid orders.
  • We perform pre-authorization of funds that fails.
note

These restrictions apply if AiFi owns the QR reader hardware and the only communication in the check-in process to the retailer is the webhook in question. If you own the QR reader and use the Admin API -> stores -> verify entry code and check in by device id, we always provide back to you the result of the QR code scanning.

Will the store doors only open after getting the response from the Push - entry codes webhook?​

Yes.

What are the restrictions on scanning the QR codes?​

QR codes have the following restrictions:

  • Every pre-registered QR code expires within N minutes (N=5 by default, can be changed).
  • Every QR code can be rescanned to let a peer in, but only until the first checkout and only if these are consecutive scans at the same doors. You can scan twice for you and your friend, but once you leave, the code can't be reused.
  • If a QR code scanning fails, the code is rejected forever. Example: if the retailer webhook failed for a QR code because of insufficient funds on the customer account, they can't use the same QR code again after they add more funds to their account; they need to generate a new one.

QR codes don't have any restrictions related to the group size. The group size provided is just the expected group size, but the customer is free to enter with more or fewer people than provided.

Appendix​

Appendix A - Best Practices When Building Your Own Customer App​

Onboarding screens for customers​

Onboarding screens in the app help introduce users to the shopping journey in an autonomous store. This is extremely helpful for new concepts in the market. On the onboarding screens, you can cover how the shopping journey looks like in the autonomous store and how the application itself works. It's important to keep the design simple, welcoming, and user-friendly.

Social logins for quick registration​

Giving users the option to register to the app using social logins can enhance engagement with your app and store. The social login is a simple process that can be completed in just a few steps: the user enters the app and selects their chosen social network. This smooth and fast registration process enables a more enjoyable, frictionless journey.

QR code brightness​

Sometimes customers are unable to enter a store because a QR reader has difficulty scanning the QR code in the app due to a dark screen. This issue is often related to the lack of brightness on a customer's phone, which prevents the QR reader from scanning the code. To avoid such issues, we recommend automatically increasing the phone's brightness when the user opens the QR code section in the app.

Comments during contests​

Allowing customers to add comments during the contesting receipt flow in the application is recommended. The text box doesn't need to be extensive, but it often happens that customers want to clarify what went wrong in the receipt after the shopping journey.

Retry payment button​

When building your own customer app integrated with the payment provider, it's important to consider that sometimes a receipt transaction may not be successful. To avoid the customer being denied entry to the store (due to a receipt pending payment), we recommend adding a feature that allows users to retry the payment whenever it fails.

Appendix B - Example Flow with Cart Mutator​

The following diagram shows an example user flow that incorporates AiFi handling the payments while the retailer is responsible for providing product prices and taxes upon checkout. In this example, the retailer can also be responsible for final communication and issuing a proper receipt, which is another customizable feature.

In this flow, the entire check-in process is handled by AiFi, while the retailer only needs to listen to checkout and cart mutator webhooks.

For more information, see the Cart mutator integration flow.