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

<?php
// RequestIdProvider
use GlobalPayments\Api\Terminals\Interfaces\IRequestIdProvider;

class RequestIdProvider implements IRequestIdProvider
{

    public function getRequestId()
    {
        return 10000 + random_int(0, 99999);
    }
}

// Device connection
use GlobalPayments\Api\Services\DeviceService;
use GlobalPayments\Api\Terminals\ConnectionConfig;
use GlobalPayments\Api\Terminals\Enums\ConnectionModes;
use GlobalPayments\Api\Terminals\Enums\DeviceType;

$config = new ConnectionConfig();
$config->ipAddress = '10.138.141.32';
$config->port = '12345';
$config->deviceType = DeviceType::HPA_ISC250;
$config->connectionMode = ConnectionModes::TCP_IP;
$config->timeout = 300;
$config->requestIdProvider = new RequestIdProvider();

$device = DeviceService::create($config);
// RequestIdProvider
using GlobalPayments.Api.Terminals;

public class RandomIdProvider : IRequestIdProvider {
    private Random random;

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

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

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

public class RandomIdProvider implements IRequestIdProvider {
    private Random random;

    public RandomIdProvider() {
        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.138.141.32");
deviceConfig.setPort(12345);
deviceConfig.setTimeout(30000);
deviceConfig.setRequestIdProvider(new RandomIdProvider());

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

HpsConnectionConfig *config = [[HpsConnectionConfig alloc] init];
config.ipAddress = @"10.138.141.32";
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

<?php
$response = $device->creditSale(11)
    ->execute();
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

<?php
$response = $device->creditVerify()
    ->execute();
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 refund. Once a batch is closed, associated transactions can no longer be voided. In these cases, a CreditRefund 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

<?php
$saleResponse = $device->creditSale(16)
    ->execute();
				
$response = $device->creditVoid()
    ->withTransactionId($saleResponse->transactionId)
    ->execute();				
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

<?php
$response = $device->creditAuth(12)
    ->execute();
var response = device.CreditAuth(12m)
    .Execute();
import com.global.api.terminals.TerminalResponse;
import java.math.BigDecimal;

TeminalResponse response = device.creditAuth(new BigDecimal("12"))
	.withAllowDuplicates(true)
    .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

<?php
$authResponse = $device->creditAuth(12)
    ->execute();
				
$response = $device->creditCapture(12)
    ->withTransactionId($authResponse->transactionId)
    ->execute();				
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) {
}];

CreditRefund

CreditRefund allows the merchant to return funds back to the cardholder. Refund 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, CreditRefund can be run utilizing the GatewayTxnId from a previous sale. When this feature is used, the gateway tracks refunds against the original sale and applies several rules.

The following rules apply when refunding 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 refunds cannot exceed the original sale amount. This is true for processing a single refund as well as multiple refunds against the same original transaction.
  • A refund amount must be greater than zero.
  • The refund must be run within 90 days.
  • CreditReversal, CreditVoid, and CreditTxnEdit are not allowed against original transactions for which a full or partial refund has been run.
  • A refund can be voided. If this results in the total refund 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 refund can be used once the batch is closed.

Credit Refund Example

<?php
$saleResponse = $this->device->creditSale(10)
    ->execute();
				
$response = $this->device->creditRefund()
    ->withTransactionId($saleResponse->transactionId)
    ->execute();				
var saleResponse = device.CreditSale(16m)
    .Execute();

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

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

TeminalResponse refundResponse = device.creditRefund(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

<?php
$response = $device->debitSale(10)
    ->execute();
var response = device.DebitSale(10m)
    .Execute();
import com.global.api.terminals.TerminalResponse;
import java.math.BigDecimal;

TerminalResponse response = device.debitSale(new BigDecimal("10"))
    .withAllowDuplicates(true)
	.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) {
}];

DebitRefund

DebitRefund allows the merchant to return funds from a prior debit sale back to the cardholder. Refunds 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, DebitRefund can be run utilizing the GatewayTxnId from a previous debit sale. When this feature is used, the gateway tracks refunds against the original sale and applies several rules.

The following rules apply when returning by GatewayTxnId:

  • The total of all refunds cannot exceed the original sale amount. This is true for processing a single refund as well as multiple refunds against the same original transaction.
  • A refund amount must be greater than zero.
  • DebitReversal is not allowed against original transactions for which a full or partial refund 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 refund can be used once the batch is closed.

Debit Refund Example

<?php
$saleResponse = $this->device->debitSale(16)
    ->execute();
				
$response = $this->device->debitRefund(10)
    ->withTransactionId($saleResponse->transactionId)
    ->execute();				
var saleResponse = device.DebitSale(16m)
    .Execute();

var response = device.DebitRefund(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.debitRefund(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

<?php
$response = $device->giftSale(10)
    ->execute();
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

<?php
$responseSale = $device->giftSale(10)
    ->execute();
				
$response = $device->giftVoid()
    ->withTransactionId($responseSale->transactionId)
    ->execute();				
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

<?php
$response = $device->giftAddValue()
    ->withAmount(10)
    ->execute();
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

<?php
$response = $device->giftBalance()
    ->execute();
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) {
}];

EOD

The EOD (End of Day) processing command is used to initiate the device’s end of day processing from the POS. During EOD, any stored offline transactions (Pending SAF, attachments and reversals) are uploaded to the host.

The response will denote with the status of each transaction as (SUCCESS/FAIL/NOT APPLICABLE). Transactions supported are REVERSAL, OFFLINE DECLINE, TRANSACTION CERTIFICATE, ADD ATTACHMENT, SENDSAF, BATCH CLOSE, EMV PDL and HEARTBEAT

EOD Example

<?php
$response = $device->eod();
var response = _device.EndOfDay();
import com.global.api.terminals.abstractions.IEODResponse;

IEODResponse response = device.endOfDay();
# see .Net/Java
# see .Net/Java
// see .Net/Java
HpsHpaEodBuilder *builder= [[HpsHpaEodBuilder alloc] initWithDevice:device];
builder.referenceNumber = [device generateNumber];

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

Line Items

The POS may display information about the items being rung up by the clerk such as a description, cost, and running total, on the SIP device by using the LineItem command. The command should be sent for each item that is rung up, along with optional running text if desired.

NOTE: Line items are currently only supported on the iSC250. This feature cannot be used in conjunction with the card acquisition on demand feature.

Line Items Example

<?php
use GlobalPayments\Api\Terminals\HPA\Entities\LineItem;

$lineItemDetails = new LineItem();
$lineItemDetails->leftText = 'Green Beans, canned';
$lineItemDetails->rightText = '$0.59';
$lineItemDetails->runningLeftText = 'TOTAL';
$lineItemDetails->runningRightText = '$1.19';

$response = $device->lineItem($lineItemDetails);
//LineItem
var response = _device.LineItem("Green Beans");

//LineItem With Parameters
 var response = _device.LineItem("Green Beans", "$0.59", "TOTAL", "$1.19");
import com.global.api.terminals.abstractions.IDeviceResponse;

//LineItem
IDeviceResponse response = device.addLineItem("Green Beans", "$0.59", "TOTAL", "$1.19");

//LineItem With Parameters
IDeviceResponse response = device.addLineItem("Green Beans", "$0.59", "TOTAL", "$1.19");
# see .Net/Java
# see .Net/Java
// see .Net/Java
HpsHpaLineItemBuilder *builder= [[HpsHpaLineItemBuilder alloc] initWithDevice:device];
builder.referenceNumber = [device generateNumber];
builder.textLeft = @"Green Beans, canned";
builder.textRight = @"$0.59";
builder.r_textLeft = @"TOTAL";
builder.r_textRight = @"$1.19";

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

SAF Transactions

Store and Forward processing enables merchants to continue to process transactions when communications between the SIP device and the Portico host are down.

SAF (Store and Forward) transactions are stored in a local transaction file and piggybacked onto the next online transaction. A response is required for each transaction being sent. If a response is not received, it remains in the local transaction file to be sent on the next online transaction. To minimize delays in processing the next online transaction only one SAF is piggybacked onto the next online transaction.

All remaining SAF transactions are sent to the host when the POS sends a SendSAF request or End of Day processing is performed. If the SAF is declined, or receives an invalid response, it is marked as declined in the local transaction file. This allows processing further transactions for the merchant and avoids getting stuck on failed SAF transactions. If partially approved, it is marked as partially approved.

NOTE: for SAF approved transactions the ResponseCode and ResponseText elements are not sent in the transaction response so the POS cannot use the ResponseCode to determine if the transaction was approved. SAF approved transactions are identified by the StoreAndForward element being returned with a ResultCode of “0” and a ResultText of “APPROVED”. If a transaction is not eligible for SAF and is declined (as would happen if the SAF amount limit is exceeded) then the StoreAndForward element is not returned. The ResultCode will be set to an error code and the ResultText will have an error message.

NOTE: By using SAF, the merchant accepts the risk of storing transactions for later transmission to Portico.

The POS may request a SAF Report with the GetSAF command. The SAF Report contains summary and detail information for pending and declined SAFs. Note that declined SAFs are kept in the local transaction file until the local transaction file is cleared during End of Day processing. Hence if multiple GetSAF commands are performed before End of Day processing, the same declined SAF transactions will be reported.

SAF reports are also generated during End of Day processing. For these SAF Reports the reports include not only the pending and declined transactions but also the approved and partially approved transactions. Again these transactions remain in the local transaction file until the local transaction file is cleared during End of Day processing.

SAF Example

<?php
$response = $device->sendSaf();
var response = _device.SendStoreAndForward();
import com.global.api.terminals.abstractions.ISAFResponse;

ISAFResponse response = device.sendStoreAndForward();
# see .Net/Java
# see .Net/Java
// see .Net/Java
HpsHpaSafBuilder *builder= [[HpsHpaSafBuilder alloc] initWithDevice:device];
builder.referenceNumber = [device generateNumber];

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

SendFile

The Send File command is used to send a file to HeartSIP. A typical use case is to send merchant specific Logo and Banner image files.

File Name : IDLELOGO.JPG Pixel Dimensions (HxW): 272x480 (iSC250) 240x320(iPP350) Purpose: Displayed when the SIP device is in an idle state. The SIP device boots up into an idle state. Every command from the POS puts SIP device in an active state, and it returns to an idle state by a Reset command

File Name : BANNER.JPG Pixel Dimensions (HxW): 40x320 (iPP350) Purpose: Displayed at the top of the SIP device screen at all times during POS driven activities. It is not shown when doing HeartSIP driven activities such as auto EOD processing

File Name : BANNER.JPG Pixel Dimensions (HxW): 60x480 (iSC250) Purpose: Displayed at the top of the SIP device screen at all times during POS driven activities. It is not shown when doing HeartSIP driven activities such as auto EOD processing

SendFile Example

<?php
use GlobalPayments\Api\Terminals\HPA\Entities\Enums\HpaSendFileType;
use GlobalPayments\Api\Terminals\HPA\Entities\SendFileData;

$sendFileInfo = new SendFileData();
$sendFileInfo->imageLocation = 'BANNER.JPG';
$sendFileInfo->imageType = HpaSendFileType::BANNER;

$response = $this->device->sendFile($sendFileInfo);
using GlobalPayments.Api.Terminals.HPA.Responses;

//Logo
SipSendFileResponse response = (SipSendFileResponse)_device.SendFile(SendFileType.Logo, @"C:\temp\IDLELOGO.JPG");

//Banner
SipSendFileResponse response = (SipSendFileResponse)_device.SendFile(SendFileType.Banner, @"C:\temp\BANNER.JPG");
import com.global.api.terminals.abstractions.IDeviceResponse;

//Logo
IDeviceResponse response = device.sendFile(SendFileType.Logo,"C:\\temp\\IDLELOGO.jpg");

//Banner
IDeviceResponse response = device.sendFile(SendFileType.Banner,"C:\\temp\\BANNER.jpg");
# see .Net/Java
# see .Net/Java
// see .Net/Java
HpsHpaSendFileBuilder *builder = [[HpsHpaSendFileBuilder alloc] initWithDevice:device];
builder.referenceNumber = [device generateNumber];
//builder.fileName = @"BANNER.JPG"; or builder.fileName = @"IDLELOGO.jpg";
builder.filePath =  @"file Path here";

[builder executeSendFileNameRequest:^(id<IHPSDeviceResponse> payload, NSError *error) {
if([payload.deviceResponseCode isEqualToString:@"00"]){
builder.referenceNumber = [device generateNumber];
[builder executeSendFileDataRequest:^(id<IHPSDeviceResponse>DuplicatePayload, 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 three .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.

Looking for API Sandbox Keys?Register and receive your keys immediately.