Overview

ScanControl works by having a per-user virtual "wallet", where scan credits are held and can be used for initiating scans. Scan credits are banked to the user wallet by the client system announcing to ScanControl API the purchase of these credits for the user. Various package options differentiated by scan type, credit amount, and expiry can be configured based on commercial agreements with clients.

ScanControl can also be used to manage bulk-purchase of scans, where an organisation account gets a "pool" of scan credits are shared to all users under that account.

‍

The following details how a developer can integrate with the ScanControl service, either with a payment gate on the device side, such as Apple or Google Pay. The service primarily adopts RevenueCat subscription management solution and allows interoperability with that product, but can be used with whatever subscription and payment gateway solution as needed.

‍

Usage Guide

1. Get Credentials

For the AHI token provided to the client (either dev or prod token), call the following API to determine the associated RevenueCat API for the account:

  	 
curl --request POST \
  --url https://api.ahi.tech/connect \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <API KEY>' \
  --data '{"token":"<TOKEN>"}'
	
  

• ^{API KEY} - provided by AHI on request.
• ^TOKEN - the AHI SDK development/production token.

The response will include the link to the RevenueCat complaint Web Hook API, ^VENDOR ID and ^APP ID as used to announce to AHI when payment transaction occurs, and credit the user wallet with scan credit:

  	 
{
  "url": "https://<ACC API>/revenuecat",
  "x-api-key": "<ACC API KEY>",
  "environment": "<ACC ENV>",
  "vid": "<VENDOR ID>",
  "aid": "<APP ID>"
}
	
  

• ^{ACC API} - URL endpoint for the account specific RevenueCat Web Hook API.
• ^{ACC API KEY} - the API key to pass to the x-api-key request header.
• ^{ACC ENV} - the associated environment type, either SANDBOX for dev, or PRODUCTION for prod, depending on what environment the provided token is associated with.
• ^{VENDOR ID} - an ID unique to the client of AHI (formally referred to as "vendor").
• ^{APP ID} - an ID unique to the App. This allows a client to have multiple apps and stages (prod, dev).

‍

2. Announcing Transaction

Whenever a payment transaction occurs, whether user subscription for month or year, single scan purchase, or bulk purchase, AHI must be informed so that the user "wallet" can be credited with scan credits accordingly. With the details returned in step 1, call the RevenueCat Web Hook to inform payment transaction occured (if using RevenueCat product, this will be done automatically once configured).

For example, to announce a user monthly subscription pay transaction, using the details from 1. Get Link step, make the following call:

  	 
curl --request POST \
  --url https://<ACC API>/revenuecat \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <ACC API KEY>' \
  --data '{
    "event":{
      "original_app_user_id": "<USER ID>",
      "product_id": "<PRODUCT ID>",
      "type": "<INITIAL_PURCHASE / RENEWAL / NON_RENEWING_PURCHASE>",
      "environment": "<ACC ENV>",
      "purchased_at_ms": <PURCHASE TIME>,
      "expiration_at_ms": <EXPIRE TIME>,
      "transaction_id": "<TRANSACTION ID>"
    }
  }'
	
  

• ^{ACC API, ACC API KEY, ACC ENV} - same as in Step 1.
• ^{USER ID} - the associated user ID, as passed to AHI user authorization call.
• ^PRODUCT ID - the purchase type, which AHI will supply to the client all ^product_id codes to facilitate the contract agreements.
• ^{INITIAL_PURCHASE / RENEWAL / NON_RENEWING_PURCHASE} - payment type.
• ^{PURCHASE TIME and EXPIRE TIME} - not used by AHI, but can be used for client audits.

• ^{TRANSACTION ID} - not used by AHI, but can be used for client audits or cross-reference key.

‍

Check Scan Credits Status

AHI SDK will automate the checking and redeeming of scan credits in the user wallet. However, the client can query the current state for a given user, to determine how much credit and expiry of said credit a user has for scans:

  	 
curl --request POST \
  --url https://<ACC API>/state \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <ACC API KEY>' \
  --data '{
    "uid": "<USER ID>",
    "vid": "<VENDOR ID>",
    "aid": "<APP ID>"
  }'
	
  

• ^{ACC API}, ^{ACC API KEY}, ^{ACC ENV} - same as in step 1.
• ^{USER ID} - the associated user ID, as passed to AHI user authorization call.
• ^{VENDOR ID} - an ID unique to the client of AHI (formally referred to as "vendor").
• ^{APP ID} - an ID unique to the App. This allows a client to have multiple apps and stages (prod, dev).

‍

More

What is ScanControl? Click Here.