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.