Developer Portal

Semi-integrated Devices

The Heartland SDK is compatible with semi-integrated devices that connect directly with Heartland, providing a variety of methods which make performing transactions simple and easy, keeping all payment data away from the Point of Sale software. With the Heartland SDK library, you can quickly implement Credit, Debit, and Gift/Loyalty capabilities into your Heartland integrations.

Connecting to Device

The SDK supports communication with the Semi-integrated Devices. The ConnectionConfig object is used by the SDK to define device communication protocols. To configure the connection, you will need to select a ConnectionMode and supply any additional pertinent information for the mode specified. Please refer to your device documentation for supported connection modes.

Device setup

// see .Net/Java
// RequestIdProvider
using GlobalPayments.Api.Terminals;

public class RequestIdProvider : IRequestIdProvider {
    private Random random;

    public RequestIdProvider() { 
        random = new Random(DateTime.Now.Millisecond);
    }

    public int GetRequestId() {
        return new Random().Next(100000, 999999);
    }
}

// Device connection
var device = DeviceService.Create(new ConnectionConfig {
    DeviceType = DeviceType.HPA_ISC250,
    ConnectionMode = ConnectionModes.TCP_IP,
    IpAddress = "10.12.220.130",
    Port = "12345",
    TimeOut = 30000,
    RequestIdProvider = new RequestIdProvider()
});
// RequestIdProvider
import java.util.Random;
import org.joda.time.DateTime;
import com.global.api.terminals.IRequestIdProvider;

public class RequestIdProvider implements IRequestIdProvider {
    private Random random;

    public RequestIdProvider() { 
        random = new Random(DateTime.now().getMillisOfSecond());
    }

    public int getRequestId() { 
        return 100000 + random.nextInt(999999);
    }
}

// Device configuration
import com.global.api.entities.enums.ConnectionModes;
import com.global.api.entities.enums.DeviceType;
import com.global.api.services.DeviceService;
import com.global.api.terminals.ConnectionConfig;
import com.global.api.terminals.abstractions.IDeviceInterface;

ConnectionConfig deviceConfig = new ConnectionConfig();
deviceConfig.setDeviceType(DeviceType.HPA_ISC250);
deviceConfig.setConnectionMode(ConnectionModes.TCP_IP);
deviceConfig.setIpAddress("10.12.220.130");
deviceConfig.setPort(12345);
deviceConfig.setTimeout(30000);
deviceConfig.setRequestIdProvider(new RequestIdProvider());

IDeviceInterface device = DeviceService.create(config);
# see .Net/Java
# see .Net/Java
// see .Net/Java
#import "HpsHpaDevice.h"

HpsConnectionConfig *config = [[HpsConnectionConfig alloc] init];
config.ipAddress = @"10.12.220.172";
config.port = @"10009";
config.connectionMode = HpsConnectionModes_TCP_IP;

HpsHpaDevice * device = [[HpsHpaDevice alloc] initWithConfig:config];

Credit Transactions

The following credit transactions to the terminal are supported:

CreditSale

CreditSale authorizes a credit card transaction. These authorizations are automatically added to the batch to be settled. If a batch is not already open, this transaction will create one.

Credit Sale Example

// see .Net/Java
var response = device.CreditSale(11m)
    .Execute();
import com.global.api.terminals.TerminalResponse;
import java.math.BigDecimal;

TeminalResponse response = device.creditSale(new BigDecimal("11"))
    .execute();
# see .Net/Java
# see .Net/Java
// see .Net/Java
HpsHpaCreditSaleBuilder *builder = [[HpsHpaCreditSaleBuilder alloc] initWithDevice:device];
builder.amount = [NSNumber numberWithDouble:11.0];
builder.referenceNumber = 1;
builder.creditCard = card;
builder.address = address;

[builder execute:^(HpsHpaCreditResponse *payload, NSError *error) {}];

CreditVerify

CreditVerify is used to verify that the associated account is in good standing with the Issuer. This is a zero dollar transaction with no associated authorization. Since VISA and other Issuers have started assessing penalties for one dollar authorizations, this provides a way for merchants to accomplish the same task while avoiding these penalties.

There are differences in the processing of this transaction based on card type.

  • VISA: an account verification is done at the Issuer,
  • MasterCard: an account status check is done at the Issuer,
  • Discover: an account verification is done at the Issuer,
  • AmEx/Other: an AVS only verification is done; this still ensures that the account is valid but requires that AVS data is supplied (zip code at a minimum).

Credit Verify Example

// see .Net/Java
var response = device.CreditVerify()
    .Execute();
import com.global.api.terminals.TerminalResponse;

TeminalResponse response = device.creditVerify()
    .execute();
# see .Net/Java
# see .Net/Java
// see .Net/Java
HpsHpaCreditVerifyBuilder *builder = [[HpsHpaCreditVerifyBuilder alloc] initWithDevice:device];
builder.referenceNumber = 1;
builder.creditCard = card;
builder.address = address;

[builder execute:^(HpsHpaCreditResponse *payload, NSError *error) {}];

CreditVoid

CreditVoid is used to cancel an open auth or remove a transaction from the current open batch. The original transaction must be a credit auth, sale, or return. Once a batch is closed, associated transactions can no longer be voided. In these cases, a CreditReturn can be used to adjust a customer’s account. If a transaction has been fully or partially returned, it cannot be voided. This transaction can also be performed directly against Portico, see Transactions via Portico.

Credit Void Example

// see .Net/Java
var saleResponse = device.CreditSale(16m)
    .Execute();

var voidResponse = device.CreditVoid()
    .WithTransactionId(saleResponse.TransactionId)
    .Execute();
import com.global.api.terminals.TerminalResponse;
import java.math.BigDecimal;

TeminalResponse saleResponse = device.creditSale(new BigDecimal(16))
    .execute();

TeminalResponse voidResponse = device.creditVoid()
    .withTransactionId(saleResponse.getTransactionId())
    .execute();
# see .Net/Java
# see .Net/Java
// see .Net/Java
HpsHpaCreditSaleBuilder *builder = [[HpsHpaCreditSaleBuilder alloc] initWithDevice:device];
builder.amount = [NSNumber numberWithDouble:11.0];
builder.referenceNumber = 1;
builder.creditCard = card;
builder.address = address;

[builder execute:^(HpsHpaCreditResponse *payload, NSError *error) {

HpsHpaCreditVoidBuilder *rbuilder = [[HpsHpaCreditVoidBuilder alloc] initWithDevice:device];
rbuilder.transactionId = payload.transactionId;
[rbuilder execute:^(HpsHpaCreditResponse *rpayload, NSError *rerror) {}];

}];

CreditAuth

CreditAuth authorizes a credit card transaction. These authorization only transactions are not added to the batch to be settled. If you prefer to have the authorization automatically added to the batch, use CreditSale.

Credit Auth Example

// see .Net/Java
var response = device.CreditAuth(12m)
    .Execute();
import com.global.api.terminals.TerminalResponse;
import java.math.BigDecimal;

TeminalResponse response = device.creditAuth(new BigDecimal("12"))
    .execute();
# see .Net/Java
# see .Net/Java
// see .Net/Java
HpsHpaCreditAuthBuilder *builder = [[HpsHpaCreditAuthBuilder alloc] initWithDevice:device];
builder.amount = [NSNumber numberWithDouble:12.0];
builder.referenceNumber = 1;
builder.allowDuplicates = YES;
builder.creditCard = card;
builder.address = address;

[builder execute:^(HpsHpaCreditResponse *payload, NSError *error) {
}];

CreditCapture

CreditCapture is primarily used to add a previously approved open authorization to the current open batch.

Credit Capture Example

// see .Net/Java
var response = device.CreditAuth(12m)
    .Execute();

var captureResponse = device.CreditCapture(12m)
    .WithTransactionId(response.TransactionId)
    .Execute();
import com.global.api.terminals.TerminalResponse;
import java.math.BigDecimal;

TeminalResponse response = device.creditAuth(new BigDecimal("12"))
    .execute();

TeminalResponse captureResponse = device.creditCapture(new BigDecimal("12"))
    .withTransactionId(response.getTransactionId())
    .execute();
# see .Net/Java
# see .Net/Java
// see .Net/Java
HpsHpaCreditCaptureBuilder *cbuilder = [[HpsHpaCreditCaptureBuilder alloc] initWithDevice:device];
cbuilder.transactionId = transactionId;
cbuilder.referenceNumber = 2;
cbuilder.amount = [NSNumber numberWithDouble:12.0];

[cbuilder execute:^(HpsHpaCreditResponse *cpayload, NSError *cerror) {
}];

CreditReturn

CreditReturn allows the merchant to return funds back to the cardholder. Returns can be for the entire amount associated with the original sale or a partial amount. The transaction is placed in the current open batch. If a batch is not open, this transaction creates an open batch. This transaction can also be performed directly against Portico, see Transactions via Portico.

For added fraud protection, CreditReturn can be run utilizing the GatewayTxnId from a previous sale. When this feature is used, the gateway tracks returns against the original sale and applies several rules.

The following rules apply when returning by GatewayTxnId:

  • The original transaction must be a CreditAuth, CreditSale, CreditOfflineAuth, CreditOfflineSale, or RecurringBilling and must be in a batch. It cannot be an open authorization that still needs to be added to a batch.
  • The total of all returns cannot exceed the original sale amount. This is true for processing a single return as well as multiple returns against the same original transaction.
  • A return amount must be greater than zero.
  • The return must be run within 90 days.
  • CreditReversal, CreditVoid, and CreditTxnEdit are not allowed against original transactions for which a full or partial return has been run.
  • A return can be voided. If this results in the total return amount being adjusted back to zero, CreditVoid, CreditReversal, and CreditTxnEdit are allowed on the original transaction once again.
  • If CardData is also supplied, then the supplied card number and the card number of the original transaction must match.

Note: If the original transaction is in the current open batch, a CreditVoid or CreditReversal may be used instead. However, only a return can be used once the batch is closed.

Credit Return Example

// see .Net/Java
var saleResponse = device.CreditSale(16m)
    .Execute();

var returnResponse = device.CreditReturn(14m)
    .WithTransactionId(saleResponse.TransactionId)
    .Execute();
import com.global.api.terminals.TerminalResponse;
import java.math.BigDecimal;

TeminalResponse saleResponse = device.creditSale(new BigDecimal("16"))
    .execute();

TeminalResponse returnResponse = device.creditReturn(new BigDecimal("16"))
    .withTransactionId(saleResponse.getTransactionId())
    .execute();
# see .Net/Java
# see .Net/Java
// see .Net/Java
HpsHpaCreditReturnBuilder *rbuilder = [[HpsHpaCreditReturnBuilder alloc] initWithDevice:device];
rbuilder.amount = [NSNumber numberWithDouble:11.0];
rbuilder.referenceNumber = 2;
rbuilder.transactionId = transactionId;
rbuilder.authCode = authorizationCode;

[rbuilder execute:^(HpsHpaCreditResponse *rpayload, NSError *rerror) {
}];

Debit Transactions

DebitSale

DebitSale authorizes a debit card transaction. These authorizations are automatically added to the batch to be settled. If a batch is not already open this transaction will create one.

Debit Sale Example

// see .Net/Java
var response = device.DebitSale(10m)
    .Execute();
import com.global.api.terminals.TerminalResponse;
import java.math.BigDecimal;

TerminalResponse response = device.debitSale(new BigDecimal("10"))
    .execute();
# see .Net/Java
# see .Net/Java
// see .Net/Java
HpsHpaDebitSaleBuilder *builder = [[HpsHpaDebitSaleBuilder alloc] initWithDevice:device];
builder.amount = [NSNumber numberWithDouble:10.0];
builder.referenceNumber = 5;

[builder execute:^(HpsHpaTerminalResponse *payload, NSError *error) {
}];

DebitReturn

DebitReturn allows the merchant to return funds from a prior debit sale back to the cardholder. Returns can be for the entire amount associated with the original sale or a partial amount. The transaction is placed in the current open batch. If a batch is not open, this transaction creates an open batch. This transaction can also be performed directly against Portico, see Transactions via Portico.

For added fraud protection, DebitReturn can be run utilizing the GatewayTxnId from a previous debit sale. When this feature is used, the gateway tracks returns against the original sale and applies several rules.

The following rules apply when returning by GatewayTxnId:

  • The total of all returns cannot exceed the original sale amount. This is true for processing a single return as well as multiple returns against the same original transaction.
  • A return amount must be greater than zero.
  • DebitReversal is not allowed against original transactions for which a full or partial return has been run.
  • The supplied card number (from the track data or token) and the card number of the original transaction must match.

Note: If the original transaction is in the current open batch, a DebitReversal may be used instead. However, only a return can be used once the batch is closed.

Debit Return Example

// see .Net/Java
var saleResponse = device.DebitSale(16m)
    .Execute();

var response = device.DebitReturn(10m)
    .WithTransactionId(saleResponse.TransactionId)
    .Execute();
import com.global.api.terminals.TerminalResponse;
import java.math.BigDecimal;

TerminalResponse response = device.debitSale(new BigDecimal("10"))
    .execute();
int tranID = response.getTransactionId();

TerminalResponse response2 = device.debitReturn(new BigDecimal("10"))
    .withTransactionId(tranID)
    .execute();
# see .Net/Java
# see .Net/Java
// see .Net/Java
HpsHpaDebitReturnBuilder *builder = [[HpsHpaDebitReturnBuilder alloc] initWithDevice:device];
builder.amount = [NSNumber numberWithDouble:10.0];
builder.referenceNumber = 5;

[builder execute:^(HpsHpaTerminalResponse *payload, NSError *error) {
}];

Gift Transactions

GiftSale

GiftCardSale is used to redeem value from a stored value account.

Note: Partial approvals are supported by default. If the account balance is non-zero but insufficient to cover the full redemption amount, the remaining balance is drained and the amount still owed is returned in the response for additional payment. The merchant may accept any additional tender to cover the amount still owed. If the account holder is unable to provide additional payment and the purchase is cancelled, this transaction should be voided to return the balance back to the account. See the “split tender card amount” and “split tender balance due amount” fields in the response.

Gift Sale Example

// see .Net/Java
var response = device.GiftSale(10m)
    .Execute();
import com.global.api.terminals.TerminalResponse;
import java.math.BigDecimal;

TerminalResponse response = device.giftSale(new BigDecimal("10"))
    .execute();
# see .Net/Java
# see .Net/Java
// see .Net/Java
HpsHpaGiftSaleBuilder *builder = [[HpsHpaGiftSaleBuilder alloc] initWithDevice:device];
builder.amount = [NSNumber numberWithDouble:10.0];
builder.referenceNumber = 1;
builder.giftCard = card;

[builder execute:^(HpsHpaGiftResponse *payload, NSError *error) {
}];

GiftVoid

GiftCardVoid is used to cancel a prior successful transaction. When voiding a transaction, all changes to the account are reversed, including any additional value added by rewards programs or automated promotions. This transaction can also be performed directly against Portico, see Transactions via Portico.

This can be used on prior transactions of the following types:

  • GiftCardAddValue
  • GiftCardSale

Gift Void Example

// see .Net/Java
var saleResponse = device.GiftSale(10m)
    .Execute();

var voidResponse = device.GiftVoid()
    .WithTransactionId(saleResponse.TransactionId)
    .Execute();
import com.global.api.terminals.TerminalResponse;
import java.math.BigDecimal;

TerminalResponse saleResponse = device.giftSale(new BigDecimal("10"))
    .execute();

TerminalResponse voidResponse = device.giftVoid()
    .withTransactionId(saleResponse.getTransactionId())
    .execute();
# see .Net/Java
# see .Net/Java
// see .Net/Java
HpsHpaGiftVoidBuilder *vbuilder = [[HpsHpaGiftVoidBuilder alloc] initWithDevice:device];
vbuilder.referenceNumber = 13;
vbuilder.transactionId = payload.transactionId;

[vbuilder execute:^(HpsHpaGiftResponse *payload, NSError *error){
}];

GiftAddValue

GiftCardAddValue loads an amount onto a stored value account. Depending on the gift processor, this request may also be used to automatically activate the account.

Gift AddValue Example

// see .Net/Java
var response = device.GiftAddValue()
    .WithAmount(10m)
    .Execute();
import com.global.api.terminals.TerminalResponse;
import java.math.BigDecimal;

TerminalResponse response = device.giftAddValue()
    .withAmount(new BigDecimal("10"))
    .execute();
# see .Net/Java
# see .Net/Java
// see .Net/Java
HpsHpaGiftAddValueBuilder *builder = [[HpsHpaGiftAddValueBuilder alloc] initWithDevice:device];
builder.amount = [NSNumber numberWithDouble:13.0];
builder.referenceNumber = 7;
builder.giftCard = card;

[builder execute:^(HpsHpaGiftResponse *payload, NSError *error) {
}];

GiftBalance

GiftCardBalance is used to retrieve the balance(s) for each currency supported by a stored value account.

Gift Balance Example

// see .Net/Java
var response = device.GiftBalance()
    .Execute();
import com.global.api.terminals.TerminalResponse;

TerminalResponse response = device.giftBalance()
    .execute();
# see .Net/Java
# see .Net/Java
// see .Net/Java
HpsHpaGiftBalanceBuilder *builder = [[HpsHpaGiftBalanceBuilder alloc] initWithDevice:device];
builder.referenceNumber = 15;
builder.giftCard = card;

[builder execute:^(HpsHpaGiftResponse *payload, NSError *error) {
}];

Supporting Information

Handling Tips

When handling tips there are three options:

  1. Sales transaction that includes the full amount (Sale + Tip)
  2. Auth/Capture transaction where you authorize for the sale amount and when performing a capture you add in the tip amount at that time.
  3. An indivual using the Portico Virtual Terminal (VT) to do a sales transaction edit. (email our Specialty Products Group
  4. Peforming an SDK Sales Transaction Edit using the credentials of the device the transaction was performed on.

Transactions via Portico

The SDK has all the capabilities to allow you to do transactions such as Reversals, Voids, Edits, and Returns for Credit, Debit, Gift and Loyalty directly against the Portico gateway. However it is important to note that when you choose to go this route, the credentials used must match the credentials of the terminal the original transaction was placed on.

You can find the credentials on a Pax device configured for Portico by going to MENU > HOST SETTINGS > HOST PARAMETERS on the physical device, but for HeartSIP devices, you must contact Heartland support to obtain this information.

SSL

PAX semi-integrated terminals support SSL communication to the POS system. The terminal needs to have the following SSL PEM certificates installed.

  1. serverca.pem
  2. servercert.pem
  3. serverkey.pem

Here are the PEM file requirements

  1. “serverca.pem” is for terminal to verify the certificate from Client.
  2. “servercert.pem” is the local certificates, make sure the fist certificate is the local certificate used by terminal and the others are CA certificates. So generally you just need to copy all certificates defined in “ca.pem” that customer provided and pasted this as appended to “servercert.pem”.
  3. “serverkey.pem” is the private key, just make sure the key started in “—–BEGIN RSA PRIVATE KEY—–” and ended with “—–END RSA PRIVATE KEY—–”. The PEM certificates files can be upload to the BroadPOS TMS system under the terminal software model under the “Communication” tab.

Self-signed Certificates

During the development and testing of your integration you may use a self-signed certificate. There are a number of ways of creating such a certificate, much of which depends on the operating system you are using. For Windows users you can generate a SSL cert using either IIS or as follows :

  1. Download OpenSSL binaries for 64bit Windows: https://slproweb.com/download/Win64OpenSSL-1_0_2h.exe

    Download OpenSSL

  2. Open up a DOS prompt ( START > RUN > cmd [enter] )

    Open DOS prompt

  3. Set the OPENSSL_CONF and RANDFILE environment variables:

    set RANDFILE = c:\.rnd
    set OPENSSL_CONF=c:\openssl-win64\bin\openssl.cfg
    

    Set environment variables

  4. Change directory to the OpenSSL bin directory

    cd c:\openssl-win64\bin
    

    Open OpenSSL directory

  5. Run OpenSSL

    c:\openssl-win64\bin> openssl
    

    Run OpenSSL

  6. Enter the following command at the ‘OpenSSL>’ prompt

    req –new –x509 –days 1826 –newkey rsa:4096 –keyout pax.key –out paxcertificate.crt
    

    Enter OpenSSL command

    NOTE: The values entered for cert information are an example, you would enter your own values

    • req = Certificate Request
    • -new = new request
    • -x509 = generate a self-signed certificate
    • -day = num of days cert is good for, 1826 = 5 years
    • -newkey = generate a new rsa key of 4096 size
    • -keyout = file to send private key to
    • -out = file to write cert info to
  7. Send the two .pem files to Heartland who will loaded it into your terminal via BroadPOS.

    Necessary PEM files

    BroadPOS configuration

  8. Once Heartland has notified you that your terminal software has been updated, clear out any open batches and reboot the device. The device should auto-update during boot with the SSL information now configured within the terminal.

Static vs Dynamic IPs

Unless otherwise specified during configuration the Pax Terminal will use DHCP to obtain an IP address. Should you want to change this to a static IP you can update this configuration via the terminal by navigating to MENU > DOWN ARROW > MAIN COMMUNICATION > LAN PARAMETERS > LAN TYPE > STATIC. Keep in mind that if you change this via the terminal only then those are kept with the terminal and not loaded on our BroadPOS systems. This means that should the terminal need to redownload its parameters again the settings will be lost. To prevent this contact Heartland with your final settings so they they can be updated in our BroadPOS system.