Starting A Transaction

Applies to: Direct | Capture

This page provides a walkthrough of how to begin a Transaction using our provided API end points.

To get a full copy of the scripts visit the Recipes page.

Step 1: Initialize Constants

Replace the place-holder text for CUSTOMER_ID, API_KEY, AES_KEY, and BASE_URL. The information needed for these variables should have been provided to you through our customer portal.

To start a transaction the ENDPOINT must be /api/v1/start

Python

CUSTOMER_ID = '<CUSTOMER ID HERE>'
API_KEY = '<API KEY HERE>'
AES_KEY = '<AES KEY HERE>'
BASE_URL = 'http://<PROVIDED BASE URL HERE>'
ENDPOINT = '/api/v1/start'

Step 2: Initialize Payload

To start a transaction there must be both public and private data objects defined. public_data is optional, but private_data must contain the desired signal to fire off as well as the document type being passed in.

Once Created both objects are wrapped in a payload object and encrypted using a base64 encoder.

Python

public_data = {}

private_data = {
    'signals': ['idcheck'],
    'document_type': 'na_dl'
}

payload = {
    "public_data": public_data,
    "private_data": private_data
}

# +----------------------------------------------------------------------+
# Encrypt Payload 
base64Payload = base64.b64encode(json.dumps(payload).encode())

Step 3: Initialize Header

All APIs use a header to pass a signature value that is calculated on the payload of the request. This ensures the request body hasn’t been modified.

To create the api_signature we run our base64Payload along with the defined API_KEY through a sha256 hash function and append the signature to our request header.

Python

# +----------------------------------------------------------------------+
# Sign Payload 

api_signature = "sha256=" + hmac.new(bytes(API_KEY, 'utf-8'), msg=base64Payload, digestmod=hashlib.sha256).hexdigest().lower()

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

Step 4: Decode Response

Once a response is received, the encoded response text is passed through the same sha256 hash function with the defined API_KEY to decode the response correctly. From this you should receive a transaction_id in the public_data which will be passed into the private data for any of our available endpoints.

Python

# +----------------------------------------------------------------------+
# Post Request

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

# +----------------------------------------------------------------------+
# Verify Signature and Decode Payload 

header_signature = response.headers['signature']
signature = "sha256=" + hmac.new(bytes(API_KEY, 'utf-8'), msg=response.text.encode(), digestmod=hashlib.sha256).hexdigest().lower()
if not hmac.compare_digest(signature, header_signature):
    print('invalid return signature')
    exit(1)

decoded_json = json.loads(base64.b64decode(response.text).decode())
public_pretty = json.dumps(decoded_json['public_data'], indent=4 )
private_pretty = json.dumps(decoded_json['private_data'], indent=4 )

Step 5: Continuing the Transaction

Now that we have access to a transaction_id we have the ability to run additional endpoints that are available. For additional endpoints and example code reference Recipes