Consumer-Facing Display Terminals

Our SDK supports communication with Semi-Integrated Devices. It uses the ConnectionConfig object to define device communication protocols.

You must specify a ConnectionMode and supply any additional required parameters to configure the connection. Refer to your device’s documentation for supported connection modes.

We support the full range of credit transactions to the terminal that merchants need.

Credit sale

A 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

Credit verification

A creditVerify transaction checks whether the cardholder account is in good standing with the issuer.
This is a zero-dollar transaction with no authorization. It allows you to verify cards without the penalties that VISA and other issuers now impose on one-dollar authorizations.

Processing is performed differently for each card type:

• VISA: Account verification is completed by the the Issuer.
• MasterCard: An account status check is completed by the Issuer.
• Discover: Account verification is completed by the the Issuer.
• AmEx/Other: An AVS-only verification is completed. This ensures that the account is valid but requires the AVS data to be supplied (zip code at a minimum).

Credit verification example

Credit void

A creditVoid transaction is used to cancel an open creditAuth transaction or remove a transaction from the current open batch. The original transaction must be a creditAuth, creditSale, or creditRefund.

Once a batch is closed, the 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.

The `creditVoid' transaction can also be performed directly through Portico. See our documentation for details: Transactions via Portico.

Credit void example

Credit authorization

You can use a creditAuth transaction to authorize a credit card transaction without adding it to the batch to be settled. If you prefer to have the authorization automatically added to the batch, use creditSale instead.

Credit authorization example

Credit capture

Use a creditCapture transaction to add a previously approved open authorization to the current open batch.

Credit capture example

Credit refund

Use a creditRefund transaction to return funds to the cardholder. This can be used to refund the full amount or a part of it. This transaction will be placed in the current open batch. If no batch is open, it will create one.

You can use Portico directly to perform a creditRefund transaction. See our documentation for details: Transactions via Portico.

For added fraud protection, you can also run the creditRefund using the GatewayTxnId from a previous sale. When you use this feature, the gateway tracks the refund against the original sale and applies the following rules:

• The original transaction must be creditAuth, creditSale, creditOfflineAuth, creditOfflineSale, or RecurringBilling.
• The original transaction must be in a batch. It can’t be an open authorization waiting to be added to a batch.
• The total of all refunds can’t exceed the original sale amount. This is true for processing a single refund as well as multiple refunds against the same original transaction.
• The refund amount must be greater than zero.
• The refund must be run within 90 days of the original transaction.
• creditReversal, creditVoid, and creditTxnEdit cannot be used for original transactions that have been fully or partially refunded.
• A refund can be voided. If the total refund amount is adjusted back to zero, creditVoid, creditReversal, and creditTxnEdit are allowed on the original transaction again.
• If CardData is supplied, the card number must match the original transaction.

Note: If the original transaction is in the open batch, you can use creditVoid or creditReversal. When the batch is closed, you must use creditRefund.

Credit refund example

Debit sale

A debitSale transaction authorizes a debit card transaction. This type of transaction is automatically added to the batch to be settled. If no batch is open, it will create one.

Debit sale example

Debit refund

A debitRefund allows the merchant to return funds from a prior debit sale back to the cardholder. Refunds can be made for the entire amount associated with the original sale or a partial amount. This type of transaction is automatically added to the batch to be settled. If no batch is open, it will create one.

You can use Portico directly to perform a debitRefund transaction. See our documentation for details: Transactions via Portico.

For added fraud protection, you can also run the debitRefund using the gatewayTxnId from a previous sale. When you use this feature, the gateway tracks the refund against the original sale and applies the following rules:

• 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 cannot be used for 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, you can use a debitReversal. But if the batch is closed, you must use a debtRefund instead.

Debit refund example

Gift card sale

A giftSale is used to redeem value from a stored value account.

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 canceled, 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.

Voiding a gift card transaction

You can use a GiftCardVoid transaction to cancel a prior successful GiftSale or GiftCardAddValue transaction. When voiding the transaction, all changes to the stored value account are reversed, including any additional value added by rewards programs or automated promotions.

You can use Portico directly to perform a CreditRefund transaction. See our documentation for details: Transactions via Portico.

Adding funds to a stored gift card account

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

EOD processing example

Send line-item details for a transaction

The POS can send line-item details to the PayApp device with a lineItemDisplay transaction. These details can include a description, cost, and running total.

Each line item includes:

• Required left-side value (max 30 characters)
• Optional right-side value (max 30 characters)

Line items example

Store-and-forward (SAF) processing enables merchants to continue to process transactions when communications between the PayApp device and the Portico host are down.

SAF transactions are stored in a local transaction file and piggybacked onto the next online transaction. A response is required for each transaction sent. If a response is not received, the SAF transaction remains in the local transaction file to be sent with the next online transaction.

To minimize delays in processing the next online transaction, only one SAF can be sent with the next online transaction. All remaining SAF transactions are sent to the host when the POS sends a SendSAF request or performs EOD processing.

If the SAF is declined, or receives an invalid response, it is marked as declined in the local transaction file. This avoids the EOD processing getting stuck on failed SAF transactions so the system can continue processing transactions for the merchant. If partially approved, it is marked as partially approved.

Important SAF behavior

For SAF approved transactions, the ResponseCode and ResponseText elements are not sent in the transaction response. As a result, the POS cannot use the ResponseCode to determine if the transaction was approved. Here's what to look for:

• Approvals: SAF-approved transactions are identified by the StoreAndForward element being returned with a ResultCode of “0” and a ResultText of "APPROVED”.
• Declines: If a transaction is not eligible for SAF and is declined (as would happen if the SAF amount limit is exceeded) the StoreAndForward element is not returned. The ResultCode will be set to an error code and the ResultText will contain an error message.

SAF reports

You can use the GetSAF command to request an SAF report from the POS. The SAF report contains a summary and detailed 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 EDO processing. So, if multiple GetSAF commands are performed before EOD, the same declined SAF transactions will be reported.

SAF reports are also generated as part of the EOD processing. These SAF 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 EOD processing.

SAF example

Edit a transaction

You can edit a transaction to change the amount of an approved charge or authorization. This is often needed when a customer wants to add a tip to the transaction.

Edit transaction example