Developer Portal

See IOT in Action: Digital Tip Jar

Below is a full example using Heartland's Python SDK to accept $1.00 tips via a Heartland End-to-End Encryption (E3) card reader and a Raspberry Pi 2 device, with a large chunk of the code supporting the control of the Pi's LEDs for payment status.

How does it work?

The E3 card reader is set up in human interface device (HID) mode, allowing the Python script to read input as it normally would thanks to Python’s raw_input function, and connected to the Raspberry Pi via USB. Once the script has obtained the track data, it builds out some data objects exposed through Heartland’s SDK, EncryptionData to hold information abou how the track data is encrypted as Heartland supports multiple encryption schemes and CreditTrackData to hold the encryption information and the encrypted track data itself.

Leveraging Python’s try / except control structure and Heartland’s exposed exception types, the script uses the try / catch to handle execution flow. The CreditTrackData.charge method is used to initiate an authorization request against the card’s track data. To handle successes vs. failures, the script properly treats exceptions as payment failures and the lack of an exception as a successful payment, indicating these two options to the tipper (end-user) with the Raspberry Pi’s onboard LEDs by blinking the activity (green) LED for successful payments or the power (red) LED for failed payments.

The Code

# useful imports
from globalpayments.api import ServicesConfig, ServicesContainer
from globalpayments.api.entities import EncryptionData
from globalpayments.api.entities.enums import EntryMethod
from globalpayments.api.entities.exceptions import ApiException
from globalpayments.api.payment_methods import CreditTrackData
from time import sleep

# filename template for controlling the onboard LEDs
filename = '/sys/class/leds/led{0}/brightness'
def change(led, what):
    '''
    changes a given onboard `led` to the `what` brightness level
    ## Expected values
    `led`
    - `0` - activity LED
    - `1` - power LED
    `what`
    - `0` - off
    - `1` - on
    '''
    tf = open(filename.format(led), 'w')
    tf.write(what)
    tf.close()
def blink(led):
    '''
    blinks a given onboard `led` for 2 seconds
    ## Expected values
    `led`
    - `0` - activity LED
    - `1` - power LED
    '''
    for i in range(10):
        change(led, '1')
        sleep(0.2)
        change(led, '0')
        sleep(0.2)

# start with the LEDs off
change(0, '0')
change(1, '0')
# build our configuration objectconfig = ServicesConfig()
config.secret_api_key = 'skapi_cert_MaePAQBr-1QAqjfckFC8FTbRTT120bVQUlfVOjgCBw'
config.developer_id = '000000'
config.version_number = '0000'
config.service_url = 'https://cert.api2.heartlandportico.com'
ServicesContainer.configure(config)

# loop while waiting for input from card reader
while True:
    # read input from keyboard
    # the card reader sends track data + '\n'
    track_data_string = raw_input("> ")
    # build track data object to be passed to `service`
    track_data = CreditTrackData()
    track_data.value = track_data_string
    track_data.entry_method = EntryMethod.Swipe
    track_data.encryption_data = EncryptionData()
    track_data.encryption_data.version = '01'
    try:
        # attempt a charge (CreditSale) using the track data obtained from the reader
        response = track_data.charge(1.00) \
            .with_currency('USD') \
            .execute()
        # log the transaction id
        print response.transaction_id

        if response.response_code is not '00':
        print "failure"
            # blink the power LED (red) for failure
            blink(1)
        else:
            # blink the activity LED (green) for success
            blink(0)
    except ApiException, e:
        print "failure"
        # blink the power LED (red) for failure
        blink(1)