Skip to content

ScanControl

To help facilitate the Pay Before solution, particularly for subscription based contract, the ScanControl service allows tracking and coordination for such arrangements.

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.

Overview

As detailed in the Payment Overview section, ScanControl works by having a per-user virtual "wallet", whereby scan credits are held and can be used for the purchase of scans. These scan credits are banked to the user wallet by the client system announcing to ScanControl of the purchase of these credits from user subscription or pre-payment transaction. The client system announces to the RevenueCat compliant API when the transaction occurs.

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

Usage Guide

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 on request.
  • TOKEN - the AHI provided SDK token.

The response will include the link to the RevenueCat complaint Web Hook API, as used to announce to AHI when payment tansaction 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. Pay 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 - ignored, but used for audits.
  • TRANSACTION ID - not used by AHI, but can be used for client audits or cross-reference key.

3. Scans

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).