Getting Started with Direct

Applies to: Direct

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. On our customer portal, clients can self-provision their accounts and generate two keys to be used with their API calls. The following table lists data elements to be configured in the customer portal.​

Element	Format	Description
Customer Id	string	Unique identifier that is created by the customer portal when a new customer is provisioned. This value never changes.
Encryption Key	string	A 33-character string used for AES256 encryption of request body secure_data field.
Signing Key	string	Used to calculate SHA-256 HMAC signature of the request payload.
Location Id	string	Optional value to tie the transaction to a physical location, for example, a branch or a store.

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

Python

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

Request Body Requirements​

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

Pyth

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

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

Python

/api/v1/submit-barcode

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

# 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
}

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

​
In this example, the private_data field contains the transaction_id obtained from the /start call and all of the data needed to process the submitted barcode request. The private_data is then encrypted. 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.

Response Types

​​When making an API call, results are returned in three ways depending on the type and number of 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 is available to anyone. It 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 time-to-live (ttl) parameter is set at 10 minutes and cannot be changed.
• 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.

👍

For both sandbox and staging, you need a customer ID and an API key. If you are interested in our sandbox environment, contact Intellicheck support to request temporary keys.