This page includes details on data encryption, requirements, response types, and testing environments.

Authentication

All API calls follow a similar pattern to handle authentication and securing data in transit. The following table lists required data elements.​

The API uses a header to pass a signature value that is calculated on the body of the request. This ensures the request body hasn’t been modified. Here is an example header.
​

BASE_HEADER = {
  'Content-type':'application/json', 
  'Accept':'application/json',
  'customer-id': CUSTOMER_ID,
  'signature': api_signature
}

Request Body Requirements​

Request bodies require a json document with public_data and private_data sections.
​

{
  public_data: { ... },
  private_data: { ... }
}

​
The private_data contains a transaction ID that uniquely identifies the request, along with the data submitted for processing. Below is an example post request for the /submit-barcode endpoint. ​

/api/v1/submit-barcode

payload = {
    "public_data": {
    },
    "private_data": {
      "transaction_id": "<TRANSACTION ID HERE>",
      "barcode": "<BASE64 ENCODED STRING>"
    }
}

# payload is base64 encoded 
base64Payload = base64.b64encode(json.dumps(payload).encode())

# The encoded paylaod is then encrypted 
api_signature = "sha256=" + hmac.new(bytes(API_KEY, 'utf-8'), msg=base64Payload, digestmod=hashlib.sha256).hexdigest().lower()

BASE_HEADER = {
  'Content-type': 'application/json', 
  'Accept': 'application/json',
  'customer-id': CUSTOMER_ID,
  'signature': api_signature
}

response = requests.post(BASE_URL + ENDPOINT, data=base64Payload, headers=headers)

​
In this example, the private_data field contains the transaction_id obtained from the /submit-barcode call and all of the data needed to process the submitted barcode request. The public_data and private_data are added to a payload object which is Base64 encoded, and then the signature is calculated using a sha256 encryption on the Base64-encoded payload. The signature is added to the header and the encoded payload is posted to the endpoint. The endpoint response is Base64 encoded.

Response Types

​​When making an API call, results are returned in three ways depending on the endpoint and requested Signals.​

• Immediate - Included in the response object.
• Post Back - For longer-running transactions that run idcheck and additional fraud signals. The results are posted to a customer-suppled URL using the same headers and body format as outlined for POST requests. This response type requires the /start and /end API calls.
• Polled - Optional method for obtaining longer running transaction results to support backwards compatibility and batch processing.

Sandbox and Staging Environments

There are two test environments, sandbox and staging.

A sandbox environment is available for simple, proof-of-concept (POC) testing. Sandbox returns simulated data. Some features are different or restricted compared to a staging environment:

• Sandbox is for those interested in a Direct integrations. It is not intended for Capture testing.
• All requested signals provide results.
• A capture session must begin by way of a QR code (return_capture_url), not a text message.
• The default time-to-live (ttl) parameter is set at 10 minutes and cannot be changed in Sandbox or Staging. It is, however, editable once you go to a production environment.
• Simulated transaction objects are stored for a limited time.
• Transactions expire after 24 hours.

A staging environment is available for end-to-end testing. Staging is available to Intellicheck customers only. It can accept real requests, and it returns real data just like a production environment.

👍

Sandbox, staging, and production credentials are provided only during the implementation process. Your assigned solutions & implementation engineer will request these credentials.