Semi-integrated Devices

The Heartland SDK is compatible with PAX semi-integrated devices that connect with Heartland, providing a variety of methods which make performing transactions with PAX Semi-integrated devices, such as the PAX S300 Integrated retail pinpad, simple and easy. 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.

Setting HTTP Connection

see .Net/Java
// C#
device = new PaxDevice(new ConnectionConfig {
ConnectionMode = ConnectionModes.HTTP,
IpAddress = "10.12.220.172",
Port = "10009"
});

var response = device.Initialize();
// Java
ConnectionConfig config = new ConnectionConfig();
config.setConnectionMode(ConnectionModes.HTTP);
config.setIpAddress("10.12.220.172");
config.setPort(10009);

device = new PaxDevice(config);
InitializeResponse response = device.initialize();
see .Net/Java
see .Net/Java
see .Net/Java
// ObjC PAX
HpsConnectionConfig *config = [[HpsConnectionConfig alloc] init];
config.ipAddress = @"10.12.220.172";
config.port = @"10009";
config.connectionMode = HpsConnectionModes_HTTP;

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

Setting TCP/IP Connection

see .Net/Java
// C#
device = new PaxDevice(new ConnectionConfig {
ConnectionMode = ConnectionModes.TCP_IP,
IpAddress = "10.12.220.172",
Port = "10009",
TimeOut = 10000
});

var response = device.Initialize();
// Java
ConnectionConfig config = new ConnectionConfig();
config.setConnectionMode(ConnectionModes.TCP_IP);
config.setIpAddress("10.12.220.172");
config.setPort(10009);

device = new PaxDevice(config);
InitializeResponse response = device.initialize();
see .Net/Java
see .Net/Java
see .Net/Java
// ObjC PAX
HpsConnectionConfig *config = [[HpsConnectionConfig alloc] init];
config.ipAddress = @"10.12.220.172";
config.port = @"10009";
config.connectionMode = HpsConnectionModes_TCP_IP;

HpsPaxDevice * device = [[HpsPaxDevice alloc] initWithConfig:config];
// ObjC SIP
HpsConnectionConfig *config = [[HpsConnectionConfig alloc] init];
config.ipAddress = @"10.12.220.130";
config.port = @"12345";
config.connectionMode = HpsConnectionModes_TCP_IP;
HpsHeartSipDevice * device = [[HpsHeartSipDevice alloc] initWithConfig:config];

The following credit transactions to the terminal are supported:

Credit Transactions

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.

CreditSale Parameters:

Parameter Description
ReferenceNumber The ECR reference number, This is an unique code in ECR side.
Amount Amount of transaction

Credit Sale Fluent Methods:

Method Parameter Description
WithReferenceNumber( ) int Reference number that can be used to identify a transaction within the terminal.
WithAmount( ) decimal Amount of the transaction.
WithCard( ) HpsCreditCard Contains the details on the credit card used. If a card is not provided the device will request a swipe.
WithToken( ) string In lieu of providing a card you can use a single or multiuse token.
WithAddress( ) HpsAddress Contains the details of the cardholder’s address
WithRequestMultiUseToken() bool Indicates if the response should contain a multiuse token (MUT). Calls using a MUT will fail if you are supplying a MUT in the .WithToken() method. Ensure your acount has requested MUT token ability, this capability is not enabled by default and will cause an error response to be returned if not enabled. To enable look for the link in your developer portal profile.
WithDetails( ) HpsTransactionDetails Merchant usable fields that can be used to store additional information about the transaction.
WithAllowDuplicates( ) bool Can be used to turn off duplicate transaction checking, useful during testing.

Credit Sale Example

see .Net/Java
// C#
var response = device.CreditSale(1, 11m)
.Execute();
// Java
CreditResponse response = device.creditSale(1, new BigDecimal(11))
.execute();
see .Net/Java
see .Net/Java
see .Net/Java
// ObjC PAX
HpsPaxCreditSaleBuilder *builder = [[HpsPaxCreditSaleBuilder alloc] initWithDevice:device];
builder.amount = [NSNumber numberWithDouble:11.0];
builder.referenceNumber = 1;
builder.creditCard = card;
builder.address = address;

[builder execute:^(HpsPaxCreditResponse *payload, NSError *error) {}];
// ObjC SIP
HpsHeartSipCreditSaleBuilder *builder = [[HpsHeartSipCreditSaleBuilder alloc] initWithDevice:device];
builder.amount = [NSNumber numberWithDouble:11.52];
builder.referenceNumber = 1;

[builder execute:^(id <IHPSDeviceResponse> 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).

CreditVerify Parameters:

Parameter Description
ReferenceNumber The ECR reference number, This is an unique code in ECR side.
Amount Amount of transaction

CreditVerify Fluent Methods:

Method Parameter Description
WithCard( ) HpsCreditCard Contains the details on the credit card used. If a card is not provided the device will request a swipe.
WithAddress( ) HpsAddress Contains the details of the cardholder’s address
WithRequestMultiUseToken() bool Indicates if the response should contain a multiuse token (MUT). Calls using a MUT will fail if you are supplying a MUT in the .WithToken() method. Ensure your acount has requested MUT token ability, this capability is not enabled by default and will cause an error response to be returned if not enabled. To enable look for the link in your developer portal profile.
WithReferenceNumber( ) int Reference number that can be used to identify a transaction within the terminal.

Credit Verify Example

see .Net/Java
// C#
var response = device.CreditVerify(1)
.Execute();

// a ResponseCode of 85 (CARD OK) is expected
// Java
CreditResponse response = device.creditVerify(1)
.execute();

// a ResponseCode of 85 (CARD OK) is expected
see .Net/Java
see .Net/Java
see .Net/Java
// ObjC PAX
HpsPaxCreditVerifyBuilder *builder = [[HpsPaxCreditVerifyBuilder alloc] initWithDevice:device];
builder.referenceNumber = 1;
builder.creditCard = card;
builder.address = address;

[builder execute:^(HpsPaxCreditResponse *payload, NSError *error) {}];
// ObjC SIP
HpsHeartSipDevice *device = [self setupDevice];
HpsHeartSipCreditVerifyBuilder *builder = [[HpsHeartSipCreditVerifyBuilder alloc]initWithDevice:device];
builder.referenceNumber = 1;

[builder execute:^(id<IHPSDeviceResponse>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.

CreditVoid Parameters:

Parameter Description
referenceNumber The Portico Gateway Transaction Id

CreditVoid Fluent Methods:

Method Parameter Description
WithTransactionId( ) int The transaction id of the transaction to void. This value is obtained from the CreditSale’s resposne object, PaxDeviceResponse.TransactionId.
WithReferenceNumber() int Reference number that can be used to identify a transaction within the terminal.

Credit Void Example

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

var voidResponse = device.CreditVoid(1).WithTransactionId(saleResponse.TransactionId).Execute();
// Java
CreditResponse saleResponse = device.creditSale(1, new BigDecimal(16))
.execute();

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

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

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

}];
// ObjC SIP
HpsHeartSipCreditSaleBuilder *builder = [[HpsHeartSipCreditSaleBuilder alloc] initWithDevice:device];
builder.amount = [NSNumber numberWithDouble:11.52];
builder.referenceNumber = 1;
[builder execute:^(id <IHPSDeviceResponse> payload, NSError *error){

HpsHeartSipCreditVoidBuilder *voidbuilder = [[HpsHeartSipCreditVoidBuilder alloc]initWithDevice:device];
voidbuilder.transactionId = [NSNumber numberWithInt:((HpsHeartSipDeviceResponse *)payload).transactionId];

[voidbuilder execute:^(id<IHPSDeviceResponse>payload, NSError *error) {}];

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.

CreditAuth Parameters:

Parameter Description
ReferenceNumber The ECR reference number, This is an unique code in ECR side.
Amount Amount of transaction

CreditAuth Fluent Methods:

Method Parameter Description
WithReferenceNumber( ) int Reference number that can be used to identify a transaction within the terminal.
WithAmount( ) decimal Amount of the transaction.
WithCard( ) HpsCreditCard Contains the details on the credit card used. If a card is not provided the device will request a swipe.
WithToken( ) string In lieu of providing a card you can use a single or multiuse token.
WithAddress( ) HpsAddress Contains the details of the cardholder’s address
WithRequestMultiUseToken() bool Indicates if the response should contain a multiuse token (MUT). Calls using a MUT will fail if you are supplying a MUT in the .WithToken() method. Ensure your acount has
WithDetails( ) HpsTransactionDetails Merchant usable fields that can be used to store additional information about the transaction.
WithAllowDuplicates( ) bool Can be used to turn off duplicate transaction checking, useful during testing.
WithAuthCode( ) string The host authorization code.
WithTransactionId( ) int The transaction id of the transaction to void. This value is obtained from the CreditSale’s resposne object, PaxDeviceResponse.TransactionId.

Credit Auth Example

see .Net/Java
// C#
var response = device.CreditAuth(1, 12m)
.Execute();
// Java
CreditResponse response = device.creditAuth(1, new BigDecimal("12"))
.execute();
see .Net/Java
see .Net/Java
see .Net/Java
// ObjC PAX
HpsPaxCreditAuthBuilder *builder = [[HpsPaxCreditAuthBuilder alloc] initWithDevice:device];
builder.amount = [NSNumber numberWithDouble:12.0];
builder.referenceNumber = 1;
builder.allowDuplicates = YES;
builder.creditCard = card;
builder.address = address;

[builder execute:^(HpsPaxCreditResponse *payload, NSError *error) {
}];
// ObjC SIP
HpsHeartSipCreditAuthBuilder *builder = [[HpsHeartSipCreditAuthBuilder alloc] initWithDevice:device];
builder.amount = [NSNumber numberWithDouble:11.52];
builder.referenceNumber = 1;

[builder execute:^(id <IHPSDeviceResponse> payload, NSError *error){
}];

CreditCapture

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

CreditCapture Parameters:

Parameter Description
ReferenceNumber The ECR reference number, This is an unique code in ECR side.
Amount Amount of transaction

CreditCapture Fluent Methods:

Method Parameter Description
WithAmount( ) decimal Amount of the transaction.
WithGratuity( ) decimal Amount of gratuity.
WithTransactionId( ) int The transaction id of the transaction to void. This value is obtained from the CreditSale’s resposne object, PaxDeviceResponse.TransactionId.
WithReferenceNumber( ) int Reference number that can be used to identify a transaction within the terminal.

Credit Capture Example

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

var captureResponse = device.CreditCapture(2, 12m)
.WithTransactionId(response.TransactionId)
.Execute();
// Java
CreditResponse response = device.creditAuth(1, new BigDecimal("12"))
.execute();

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

[cbuilder execute:^(HpsPaxCreditResponse *cpayload, NSError *cerror) {
}];
// ObjC SIP
HpsHeartSipCreditCaptureBuilder *caputureBuilder = [[HpsHeartSipCreditCaptureBuilder alloc]initWithDevice:device];
caputureBuilder.transactionId = transactionId;

[caputureBuilder execute:^(id<IHPSDeviceResponse>response, NSError *error) {
}];

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.

CreditReturn Parameters:

Parameter Description
ReferenceNumber The ECR reference number, This is an unique code in ECR side.
Amount Amount of transaction

CreditReturn Fluent Methods:

Method Parameter Description
WithReferenceNumber( ) int Reference number that can be used to identify a transaction within the terminal.
WithAmount( ) decimal Amount of the transaction.
WithCard( ) HpsCreditCard Contains the details on the credit card used. If a card is not provided the device will request a swipe.
WithToken( ) string In lieu of providing a card you can use a single or multiuse token.
WithTransactionId( ) int The transaction id of the transaction to void. This value is obtained from the CreditSale’s resposne object, PaxDeviceResponse.TransactionId.
WithAddress( ) HpsAddress Contains the details of the cardholder’s address
WithDetails( ) HpsTransactionDetails Merchant usable fields that can be used to store additional information about the transaction.
WithAllowDuplicates( ) bool Can be used to turn off duplicate transaction checking, useful during testing.
WithAuthCode( ) string The host authorization code.

Credit Return Example

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

var returnResponse = device.CreditReturn(2, 14m)
.WithTransactionId(saleResponse.TransactionId)
.Execute();
// Java
CreditResponse saleResponse = device.creditSale(1, new BigDecimal(16))
.execute();

CreditResponse returnResponse = device.creditReturn(2, new BigDecimal(16))
.withTransactionId(saleResponse.getTransactionId())
.execute();
see .Net/Java
see .Net/Java
see .Net/Java
// ObjC PAX
HpsPaxCreditReturnBuilder *rbuilder = [[HpsPaxCreditReturnBuilder alloc] initWithDevice:device];
rbuilder.amount = [NSNumber numberWithDouble:11.0];
rbuilder.referenceNumber = 2;
rbuilder.transactionId = transactionId;
rbuilder.authCode = authorizationCode;

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

Credit Refund Example

// ObjC SIP
HpsHeartSipCreditRefundBuilder *builder = [[HpsHeartSipCreditRefundBuilder alloc]initWithDevice:device];
builder.amount = [NSNumber numberWithDouble:11.52];
builder.referenceNumber = 1;
[builder execute:^(id<IHPSDeviceResponse>payload, NSError *error) {
}];

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.

DebitSale Parameters:

Parameter Description
ReferenceNumber The ECR reference number, This is an unique code in ECR side.
Amount Amount of transaction

DebitSale Fluent Methods:

Method Parameter Description
WithReferenceNumber( ) int Reference number that can be used to identify a transaction within the terminal.
WithAmount( ) decimal Amount of the transaction.
WithCashBack( ) decimal The cash back amount.
WithDetails( ) HpsTransactionDetails Merchant usable fields that can be used to store additional information about the transaction.
WithAllowDuplicates( ) bool Can be used to turn off duplicate transaction checking, useful during testing.

Debit Sale Example

see .Net/Java
// C#
var response = device.DebitSale(5, 10m)
.Execute();
// Java
DebitResponse response = device.debitSale(5, new BigDecimal(10))
.execute();
see .Net/Java
see .Net/Java
see .Net/Java
// ObjC PAX
HpsPaxDebitSaleBuilder *builder = [[HpsPaxDebitSaleBuilder alloc] initWithDevice:device];
builder.amount = [NSNumber numberWithDouble:10.0];
builder.referenceNumber = 5;

[builder execute:^(HpsPaxDebitResponse *payload, NSError *error) {
}];
// ObjC SIP
HpsHeartSipDebitSaleBuilder *builder = [[HpsHeartSipDebitSaleBuilder alloc] initWithDevice:device];
builder.amount = [NSNumber numberWithDouble:10.22];
builder.referenceNumber = 5;
builder.allowDuplicates = YES;

[builder execute:^(id<IHPSDeviceResponse>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.

DebitReturn Parameters:

Parameter Description
ReferenceNumber The ECR reference number, This is an unique code in ECR side.
Amount Amount of transaction

DebitReturn Fluent Methods:

Method Parameter Description
WithTransactionId( ) int The transaction id of the transaction to void. This value is obtained from the CreditSale’s resposne object, PaxDeviceResponse.TransactionId.
WithReferenceNumber( ) int Reference number that can be used to identify a transaction within the terminal.
WithAmount( ) decimal Amount of the transaction.

Debit Return Example

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

var response = device.DebitReturn(2, 10m)
.WithTransactionId(saleResponse.TransactionId)
.Execute();
// Java
DebitResponse response = device.debitSale(1, new BigDecimal(10))
.execute();
int tranID = response.getTransactionId();

DebitResponse response2 = device.debitReturn(2, new BigDecimal(10))
.withTransactionId(tranID)
.execute();
see .Net/Java
see .Net/Java
see .Net/Java
// ObjC PAX
HpsPaxDebitReturnBuilder *builder = [[HpsPaxDebitReturnBuilder alloc] initWithDevice:device];
builder.amount = [NSNumber numberWithDouble:10.0];
builder.referenceNumber = 5;

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

Debit Refund Example

// ObjC SIP
HpsHeartSipDebitRefundBuilder *builder = [[HpsHeartSipDebitRefundBuilder alloc] initWithDevice:device];
builder.amount = [NSNumber numberWithDouble:10.22];
builder.referenceNumber = 5;

[builder execute:^(id<IHPSDeviceResponse> 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.

GiftSale Parameters:

Parameter Description
ReferenceNumber The ECR reference number, This is an unique code in ECR side.
Amount Amount of transaction

GiftSale Fluent Methods:

Method Parameter Description
WithReferenceNumber( ) int Reference number that can be used to identify a transaction within the terminal.
WithAmount( ) decimal Amount of the transaction.
WithGratuity( ) decimal Amount of gratuity.
WithCard( ) HpsGiftCard Contains the details on the card used. If a card is not provided the device will request a swipe.
WithCurrency( ) currencyType Determines if points or USD is used.
WithDetails( ) HpsTransactionDetails Merchant usable fields that can be used to store additional information about the transaction.

Gift Sale Example

see .Net/Java
// C#
var response = device.GiftSale(1, 10m)
.Execute();
// Java
GiftResponse response = device.giftSale(1, new BigDecimal(10))
.execute();
see .Net/Java
see .Net/Java
see .Net/Java
// ObjC PAX
HpsPaxGiftSaleBuilder *builder = [[HpsPaxGiftSaleBuilder alloc] initWithDevice:device];
builder.amount = [NSNumber numberWithDouble:10.0];
builder.referenceNumber = 1;
builder.giftCard = card;

[builder execute:^(HpsPaxGiftResponse *payload, NSError *error) {
}];
// ObjC SIP
HpsHeartSipGiftSaleBuilder *builder = [[HpsHeartSipGiftSaleBuilder alloc] initWithDevice:device];
builder.amount = [NSNumber numberWithDouble:10.0];
builder.referenceNumber = 1;

[builder execute:^(id<IHPSDeviceResponse> 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

GiftVoid Parameters:

Parameter Description
ReferenceNumber The Portico Gateway transaction id

GiftVoid Fluent Methods:

Method Parameter Description
WithTransactionId( ) int The transaction id of the transaction to void. This value is obtained from the CreditSale’s resposne object, PaxDeviceResponse.TransactionId.
WithReferenceNumber( ) int Reference number that can be used to identify a transaction within the terminal.
WithCard( ) HpsGiftCard Contains the details on the card used. If a card is not provided the device will request a swipe.
WithCurrency( ) currencyType Determines if points or USD is used.

Gift Void Example

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

var voidResponse = device.GiftVoid(2)
.WithTransactionId(saleResponse.TransactionId)
.Execute();
// Java
final GiftResponse saleResponse = device.giftSale(1, new BigDecimal(10)).execute();

GiftResponse voidResponse = device.giftVoid(2)
.withTransactionId(saleResponse.getTransactionId())
.execute();
see .Net/Java
see .Net/Java
see .Net/Java
// ObjC PAX
HpsPaxGiftVoidBuilder *vbuilder = [[HpsPaxGiftVoidBuilder alloc] initWithDevice:device];
vbuilder.referenceNumber = 13;
vbuilder.transactionId = payload.transactionId;

[vbuilder execute:^(HpsPaxGiftResponse *payload, NSError *error){
}];
// ObjC SIP
HpsHeartSipGiftVoidBuilder *vbuilder = [[HpsHeartSipGiftVoidBuilder alloc] initWithDevice:device];
vbuilder.referenceNumber = 13;
vbuilder.transactionId = transactionId;

[vbuilder execute:^(id <IHPSDeviceResponse> 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.

GiftAddValue Parameters:

Parameter Description
ReferenceNumber The ECR reference number, This is an unique code in ECR side.

GiftAddValue Fluent Methods:

Method Parameter Description
WithReferenceNumber( ) int Reference number that can be used to identify a transaction within the terminal.
WithAmount( ) decimal Amount of the transaction.
WithCard( ) HpsGiftCard Contains the details on the card used. If a card is not provided the device will request a swipe.
WithCurrency( ) currencyType Determines if points or USD is used.

Gift AddValue Example

see .Net/Java
see .Net
// C#
var response = device.GiftAddValue(1)
.WithAmount(10m)
.Execute();
// Java
// See Pax Tests for more examples
GiftResponse response = device.giftAddValue(1)
.withAmount(new BigDecimal(10))
.execute();
see .Net/Java
see .Net/Java
see .Net/Java
// ObjC PAX
HpsPaxGiftAddValueBuilder *builder = [[HpsPaxGiftAddValueBuilder alloc] initWithDevice:device];
builder.amount = [NSNumber numberWithDouble:13.0];
builder.referenceNumber = 7;
builder.giftCard = card;

[builder execute:^(HpsPaxGiftResponse *payload, NSError *error) {
}];
// ObjC SIP
HpsHeartSipGiftAddValueBuilder *builder = [[HpsHeartSipGiftAddValueBuilder alloc] initWithDevice:device];
builder.amount = [NSNumber numberWithDouble:11.0];
builder.referenceNumber = 7;

[builder execute:^(id <IHPSDeviceResponse> payload, NSError *error) {
}];

GiftBalance

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

GiftBalance Parameters:

Parameter Description
ReferenceNumber The ECR reference number, This is an unique code in ECR side.

GiftBalance Fluent Methods:

Method Parameter Description
WithReferenceNumber( ) int Reference number that can be used to identify a transaction within the terminal.
WithCard( ) HpsGiftCard Contains the details on the card used. If a card is not provided the device will request a swipe.
WithCurrency( ) currencyType Determines if points or USD is used.

Gift Balance Example

see .Net/Java
// C#
var response = device.GiftBalance(1)
.Execute();
// Java
GiftResponse response = device.giftBalance(1)
.execute();
see .Net/Java
see .Net/Java
see .Net/Java
// ObjC PAX
HpsPaxGiftBalanceBuilder *builder = [[HpsPaxGiftBalanceBuilder alloc] initWithDevice:device];
builder.referenceNumber = 15;
builder.giftCard = card;

[builder execute:^(HpsPaxGiftResponse *payload, NSError *error) {
}];
// ObjC SIP
HpsHeartSipGiftBalanceBuilder *builder = [[HpsHeartSipGiftBalanceBuilder alloc] initWithDevice:device];
builder.referenceNumber = 15;

[builder execute:^(id <IHPSDeviceResponse> payload, NSError *error) {
}];

Reference

Communication Protocols

While the SDK shields you from the underlying communication protocol with the terminal it is worth understanding the basics of how request/responses are transmitted. The terminal uses a VISA1 protocol consisting of a framed packet and an acknowledgement flow. Below is a description of the protocol design. The command would be formatted as such :

<STX><COMMAND REQUEST PACKET><ETX><LRC>

Control Characters    
Name Hex Description
STX 0x02 The start of the transaction message request or response
ETX 0x03 The end of the transaction message request or response
ACK 0x06 The acknowledge symbol informs that the message is received correctly
NAK 0x15 The not acknowledge symbol informs that the message is not received correctly
ENQ 0x05  
FS 0x1C The field separator that used to separate the data segments
US 0x1F The Unit separator that used to separate certain sub-fields In Extend Data
GS 0x1D The Group separator that used to separate a group filed
RS 0x1E Record Separator
EOT 0x04 The end of transmission symbol informs that the transaction is complete
COMMA 0x2C  
COLON 0x3A  
  0x7C Group separator for PassThru Data.
LRC   Longitudinal Redundancy Check

A longitudinal redundancy check is a form of redundancy check that is applied independently to each of a parallel group of bit streams. The data must be divided into transmission blocks, to which the additional check data is added:

Calculation

Set LRC = 0 For each character c in the string Do Set LRC = LRC XOR c End Do

The check begins after the STX and proceeds and includes the ETX.

Developer TIP:

When using software that logs communication to and from the device you may see it formatted in the following ways:

[02]T00[1c]1.31[1c]01[1c]250[1c][1c]11[1c][1c][1c][1c][1c][03]

<STX> T00 <FS> 1.31 <FS> 01 <FS> 250 <FS> <FS> 11 <FS> <FS> <FS> <FS> <FS> <ETX>

It’s important to note that it is written this way because attempting to display the actual ascii characters values causes display rendering issues. Make sure that when you go to encode a message that you replace the bracketed values with their actuall ascii characters.

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.

SSL

PAX semi-integrated terminal supports SSL communication to the POS system. The terminal needs to have the following SSL PEM certification 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

Developer Keys

  1. Open up a dos prompt ( START : RUN : cmd [enter] )

Developer Keys

  1. Set the OPENSSL_CONF and RANDFILE environment variables: set RANDFILE = c:.rnd set OPENSSL_CONF=c:\openssl-win64\bin\openssl.cfg

Developer Keys

  1. Change directory to the OpenSSL bin directory cd c:\openssl-win64\bin

Developer Keys

  1. Run OpenSSL c:\openssl-win64\bin> openssl

Developer Keys

  1. Enter the following command at the ‘OpenSSL>’ prompt req –new –x509 –days 1826 –newkey rsa:4096 –keyout pax.key –out paxcertificate.crt

Developer Keys

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

  1. Send the two .pem files to Heartland who will loaded it into your terminal via BroadPOS.

Developer Keys

Developer Keys

  1. 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 be 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.