Payment

public class Payment

Represents an individual payment within the context of the transaction

Methods

create

public static Payment create()

Factory method to create a payment instance. Please note that the Amounts and RequestedAmounts instances are also created at this time with empty values.

getAccountType

public AccountType getAccountType()

The account type used to complete this payment. This may be empty.

getAcquirerId

public String getAcquirerId()

The ID of the acquirer used for the payment. This may be empty.

getAcquirerName

public String getAcquirerName()

The name of the acquirer used for the payment. This may be empty.

getAdditionalAcquirerData

public String getAdditionalAcquirerData()

Deprecated on 2021-02-01. Please use setSaleNote() instead.

getAllowedPaymentOperations

public ArrayList<PaymentOperation> getAllowedPaymentOperations()

Get the allowed payment operations A list of operations that can be performed on this payment. If null (or an empty optional for c++), then the allowed operations are unknown. If an empty list, then there are no further operations allowed.

getAlternativePaymentId

public String getAlternativePaymentId()

Alternative payment method used in the payment.

getAmountAvailableForRefund

public Decimal getAmountAvailableForRefund()

Get the amount available for refund

getAmountDue

public Decimal getAmountDue()

Get the difference amount due. Mainly used in the cases where FSA and Non-FSA amounts transaction is involved. Once the FSA amount is approved with FSA card, the difference amount due will be populated in here.

getAmounts

public AmountTotals getAmounts()

Get the approved amounts in the payment. Please note that these amounts are independent from the requested amounts.

getAppSpecificData

public String getAppSpecificData()

Stores the information necessary to perform other operations on this payment at a later time, such as completing a pre-auth or refunding a specific payment. If the payment object is stored offline, only this field must be saved and restored to complete later operations. This field is limited to 255 characters, and the value should not be modified.

getAuthCode

public String getAuthCode()

Get The payment Authorization Code, it usually provided by the payment processing service or acquirer.This may be added during the transaction, but once set should not be changed.

getAuthResponseText

public String getAuthResponseText()

Get descriptive text accompanying the authorization code from payment processor. This is usually present when the transaction has failed authorization, providing the reason for the failure. This is optional.

getAuthResult

public AuthorizationResult getAuthResult()

Get Result of transaction authorization. This is provided by the payment application or payment service provider. This may be empty.

getAuthorizationMethod

public AuthorizationMethod getAuthorizationMethod()

Get the ways by which the payment is authorized. This may be empty.

getCardInformation

public CardInformation getCardInformation()

If the payment involves a card / contactless, this provides the relevant information. This might be empty.

getCashbackAmount

public Decimal getCashbackAmount()

Get the amount of cashback as a GAAP-standard BigDecimal. This is optional. This may also refer to a cash advance amount, based on the payment type.

getCashierId

public String getCashierId()

Get the ID of the cashier, this should be set when the transaction is initiated and may not be changed. This may be empty.

getCashierName

public String getCashierName()

The Name of the cashier that is starting the current session. This is optional.

getContextData

public String getContextData()

Refer to setContextData().

getCurrency

public String getCurrency()

The currency used for this payment. The format is three contiguous capital letters per ISO 4217 “Codes for representation of currencies and funds”.

getCustomerNote

public String getCustomerNote()

An optional Reference/Customer Note

getDynamicCurrencyConversions

public ArrayList<DynamicCurrencyConversion> getDynamicCurrencyConversions()

Refer to setDynamicCurrencyConversions(DynamicCurrencyConversion).

getEbtVoucherNum

public String getEbtVoucherNum()

Get The payment EBT Voucher Num, it usually provided by the payment processing service or acquirer.This may be added during the transaction, but once set should not be changed.

getExpiryDate

public String getExpiryDate()

End of the validity period for the pre-authorization or deferred payment. The payment can be completed and/or updated until this date. This returns an ISO 8601 date string, e.g., 2020-08-04.

getFeesAmount

public Decimal getFeesAmount()

Get the amount of fees as a GAAP-standard BigDecimal.

getGratuityAmount

public Decimal getGratuityAmount()

Get the amount of gratuity or Tip if applicable as a GAAP-standard BigDecimal. This is optional

getHasRestrictedItem

public Boolean getHasRestrictedItem()

The method used to determing if the basket has a restricted item. By default we assume it doesnt.

getHostAuthCode

public String getHostAuthCode()

Get authorization code from the host payment if there is a gateway or other host between the terminal and the acquirer.

getInstallment

public Installment getInstallment()

Refer to setInstallment(Installment)

Return:

Installment object containing installment related information.

getInvoice

public String getInvoice()

Get the ID of the invoice. This is set when the payment is initiated and may not be changed. This may be empty.

getLane

public String getLane()

Get the ID or name of the current device. This is set when the transaction is initiated and may not be changed. This may be empty.

getLocalPaymentId

public String getLocalPaymentId()

An ID generated and assigned by the POS for managing the payment events. This ID is only relevant to the POS, and is used by the POS’ internal tracking. This enables a PaymentCompletedEvent to be matched to a specific payment within the POS’ own reporting system.

getMaximumCompletionAmount

public Decimal getMaximumCompletionAmount()

Get the maximum completion amount

getMedicalAmounts

public MedicalAmounts getMedicalAmounts()

Gets the optional medical amounts requested by the POS

getMerchantAccount

public MerchantAccount getMerchantAccount()

Refer to setMerchantAccount(MerchantAccount)

Return:

MerchantAccount object containing merchant account related information.

getMerchantId

public String getMerchantId()

Get Merchant identifier

getOperationsHistory

public ArrayList<PaymentOperationHistory> getOperationsHistory()

Get history of operations performed on a payment to modify it, including, but not limited to pre-authorizations A list of operations that have been performed on this payment. If null (or an empty optional for c++), then the operations history is unknown. If an empty list, then there is no history.

getOrderType

public OrderType getOrderType()

The type of the order for this payment.

getPaymentAmount

public Decimal getPaymentAmount()

Get the amount of the payment was approved for as a GAAP-standard BigDecimal. This is provided set during the authorization process.

getPaymentId

public String getPaymentId()

The payment id, set by the gateway/processor or the alternate payment type provider. For cash payments, this might be set to the local payment ID.

getPaymentMethod

public String getPaymentMethod()

The method used to pay. This may be empty.

getPaymentType

public PaymentType getPaymentType()

The payment type used to complete this payment. This may be empty.

getReceipts

public HashMap<ReceiptType, Receipt> getReceipts()

Get the receipts for the payment after the payment is completed. This is possibly empty or only containg one type depending on the success of the payment and the configuration of the payment application.

getReconciliationId

public String getReconciliationId()

Get the reconciliation id, set by the nexo payment response

getRedeemedUnits

public String getRedeemedUnits()

Get the number of units of alternate currency consumed, in the case of an alternate payment type. This is optional.

getReferenceLocalPaymentId

public String getReferenceLocalPaymentId()

Get the related local payment ID of the payment that was refunded or voided. See getReferencePaymentId() for more information on how a reference ID is used, and getLocalPaymentId() for more information on how the local ID is used. This may be empty.

getReferencePaymentId

public String getReferencePaymentId()

Get the related payment ID of the payment that was refunded or voided. For example, Payment1 is made, and the customer desires a refund. Payment2 will be created for the refund, and the payment ID from Payment1 will be set as the reference payment ID of Payment2. For voids, refunds, and other follow-on payments, this is required if the AppSpecificData from the original payment is not provided, otherwise this is optional.

getReferenceTimestamp

public String getReferenceTimestamp()

Get the related payment timestamp of the payment that was refunded or voided. For example, Payment1 is made, and the customer desires a refund. Payment2 will be created for the refund, and the payment timestamp from Payment1 will be set as the reference payment timestamp of Payment2. For voids, refunds, and other follow-on payments, this is required if the AppSpecificData from the original payment is not provided, otherwise this is optional.

getRequestedAmounts

public AmountTotals getRequestedAmounts()

Get the requested payment amounts, set when a payment is requested by the POS and independent from the approved amounts.

getRequestedCardPresentationMethods

public ArrayList<PresentationMethod> getRequestedCardPresentationMethods()

Gets the requested card presentation methods. Valid presentation methods include: MAG_STRIPE, CHIP, CTLS_CARD (note that this will allow any type of CTLS presentation), KEYED This is optional and if no presentation methods are requested, by default all card presentation methods supported by the device hardware will be allowed.

getRequestedPaymentType

public PaymentType getRequestedPaymentType()

Refer to setRequestedPaymentType(paymentType).

getRequestedTokenParameters

public ArrayList<TokenParameters> getRequestedTokenParameters()

Set the requested token parameters of the payment.

getRequestedTokenizationMethod

public TokenizationMethod getRequestedTokenizationMethod()

Deprecated on 2022-03-01. Please use getRequestedTokenParameters() instead.

getRetrievalReferenceNumber

public String getRetrievalReferenceNumber()

The Retrieval Reference Number from the payment/reversal response. This may be empty.

getSaleNote

public String getSaleNote()

An optional Reference/Sales Note

getSignature

public Image getSignature()

Get the signature image provided by the payment application if the Authorization Method contains Signature. This will be empty for all other Authorization Methods.

getStoredValueAction

public StoredValueAction getStoredValueAction()

Get stored value action. This may be empty.

getStoredValueCardInformation

public StoredValueCardInformation getStoredValueCardInformation()

Get stored card information, if the payment involves a gift card.

getTaxAmount

public Decimal getTaxAmount()

Get the amount of tax as a GAAP-standard BigDecimal. This is optional

getTerminalData

public String getTerminalData()

Get optional terminal data

getTerminalId

public String getTerminalId()

Get Terminal identifier

getTimestamp

public String getTimestamp()

Get the timestamp of payment completion. This is provided by the application which processes the payment.

getTotalsGroupId

public String getTotalsGroupId()

Refer to setTotalsGroupId().

getTransactionType

public TransactionType getTransactionType()

Refer to setTransactionType

getVasCommands

public VasCommands getVasCommands()

The method used to obtain the VasCommands

getVenue

public String getVenue()

Get the ID of the venue. This is set when the transaction is initiated and may not be changed. This may be empty.

isDuplicate

public boolean isDuplicate()

Returns true if this payment was identified as a duplicate of a previous payment.

isForceOffline

public Boolean isForceOffline()

True if this was forced offline, false if it was explicitly forced online, otherwise this is empty.

isOnline

public boolean isOnline()

True if the payment was authorized online with the host, or false if this was authorized offline.

isStoredValueCard

public boolean isStoredValueCard()

Get whether is gift card

setAccountType

public void setAccountType(AccountType accountType)

The account type used to complete this payment.

setAcquirerId

public void setAcquirerId(String acquirerId)

Set the acquirer identifier to be used for this payment if there are multiple acquirers configured.

setAcquirerName

public void setAcquirerName(String acquirerName)

Set the acquirer name

setAdditionalAcquirerData

public void setAdditionalAcquirerData(String acquirerData)

Deprecated on 2021-02-01. Please use setSaleNote() instead.

setAlternativePaymentId

public void setAlternativePaymentId(String apmId)

Set alternative payment method used in the payment.

setAppSpecificData

public void setAppSpecificData(String data)

Set the data from a previous payment object to perform another operation on that payment or to look up a specific payment when querying transactions.

setAuthCode

public void setAuthCode(String authCode)

Set The payment Authorization Code, it usually provided by the payment processing service or acquirer.This may be added during the transaction, but once set should not be changed.

setAuthResponseText

public void setAuthResponseText(String responseText)

Set descriptive text accompanying the authorization code from payment processor. This is usually present when the transaction has failed authorization, providing the reason for the failure. This is optional.

setAuthResult

public void setAuthResult(AuthorizationResult authorizationResult)

Result of transaction authorization. This is provided by the payment application or payment service provider. This may be empty.

setAuthorizationMethod

public void setAuthorizationMethod(AuthorizationMethod authorizationMethod)

Set the ways by which the payment is authorized. This is optional

setCardInformation

public void setCardInformation(CardInformation cardInformation)

Set card information if the card information is known by the POS, otherwise this should be empty.

setCashierId

public void setCashierId(String cashierId)

Set the ID of the cashier that is starting this payment. This is optional.

setCashierName

public void setCashierName(String cashierName)

Set the Name of the cashier that is starting this payment. This is optional.

setContextData

public void setContextData(String contextData)

An arbitrary string set by the POS to provide context or state information back to itself when the payment is completed. This is optional.

setCurrency

public void setCurrency(String currency)

This overrides the currency set in the transaction. See getCurrency() for more information. This is optional.

setCustomerNote

public void setCustomerNote(String customerNote)

See getCustomerNote() for information on how this is used. This is optional.

setDuplicate

public void setDuplicate(boolean isDuplicate)

See isDuplicate().

setDynamicCurrencyConversions

public void setDynamicCurrencyConversions(ArrayList<DynamicCurrencyConversion> conversions)

Set the actual currency conversions that are being applied to the transaction.

setEbtVoucherNum

public void setEbtVoucherNum(String ebtVoucherNum)

Set The payment Ebt Voucher Num, it usually provided by the payment processing service or acquirer.This may be added during the transaction, but once set should not be changed.

setForceOffline

public void setForceOffline(Boolean forceOffline)

Set to true to force the current payment to be authorized offline, set to false to force the payment to be performed online, or empty to let the payment application decide. This is only a recommendation, it is possible for the payment application configuration to override this value.

setHasRestrictedItem

public void setHasRestrictedItem(Boolean hasRestrictedItem)

Set if the basket has a restricted item.

setHostAuthCode

public void setHostAuthCode(String hostAuthCode)

Refer to getHostAuthCode.

setInstallment

public void setInstallment(Installment installment)

Set the payment/transaction to an installment type and sets the installment information Refer to Installment.

setInvoice

public void setInvoice(String invoice)

Set the ID of the invoice. This is set when the payment is initiated and may not be changed. This may be empty.

setLane

public void setLane(String lane)

Set the ID or name of the current lane. This is set when the payment is initiated and may not be changed. This may be empty.

setLocalPaymentId

public void setLocalPaymentId(String paymentId)

See getLocalPaymentId() for information on how this is used. This is optional.

setMedicalAmounts

public void setMedicalAmounts(MedicalAmounts medicalAmounts)

Set the amounts eligible for FSA. This is optional, need to have only if FSA eligible items are there.

setMerchantAccount

public void setMerchantAccount(MerchantAccount merchantAccount)

Set the payment/transaction to an merchant account type and Id information Refer to MerchantAccount.

setMerchantId

public void setMerchantId(String merchantId)

Set the MID for the acquirer. This is generally configured within the payment application, and is not set by the POS.

setOnline

public void setOnline(boolean online)

Set by the application that performs the authorization with the host.

setOrderType

public void setOrderType(OrderType orderType)

The order type used to fulfill this payment.

setPaymentId

public void setPaymentId(String paymentId)

Set payment ID, This is set by the gateway/processor in the case of a credit/debit payment, or the alternate payment type provider. For cash payments, this may be set to the local payment ID.

setPaymentMethod

public void setPaymentMethod(String paymentMethod)

This is required for the application which processes the payment, and is generally not set by the POS.

setPaymentType

public void setPaymentType(PaymentType paymentType)

The payment type used to complete this payment.

setReceipt

public void setReceipt(Receipt receipt)

Set the receipt for a payment. This is set by the application which processes the payment, so that the required transaction data can be present on the final receipt, otherwise this is not used. This is automatically added to the return receipts map according to the type of the receipt, which means that setting the receipt with the same type a second time will replace any other receipt with the same type that was already stored.

setReconciliationId

public void setReconciliationId(String reconciliationId)

An optional string set as an reconciliation id provided by the host, acquirer, or terminal indicating which batch will settle this payment when settlement is performed.

setRedeemedUnits

public void setRedeemedUnits(String units)

Set the number of units of alternate currency consumed, in the case of an alternate payment type. This is optional.

setReferenceLocalPaymentId

public void setReferenceLocalPaymentId(String paymentId)

See getReferenceLocalPaymentId() for information on how this is used. This is optional.

setReferencePaymentId

public void setReferencePaymentId(String paymentId)

See getReferencePaymentId() for information on how this is used. This is optional.

setReferenceTimestamp

public void setReferenceTimestamp(String timestamp)

See getReferenceTimestamp() for information on how this is used. This is optional.

setRequestedAmounts

public void setRequestedAmounts(AmountTotals amountTotals)

Set the amounts for the customer, either to be charged to the customer or cleared from the customer, depending on the transaction type. This is required.

setRequestedCardPresentationMethods

public void setRequestedCardPresentationMethods(ArrayList<PresentationMethod> presentationMethods)

Sets the requested card presentation methods. Valid presentation methods include: MAG_STRIPE, CHIP, CTLS_CARD (note that this will allow any type of CTLS presentation), KEYED This is optional and if no presentation methods are requested, by default all card presentation methods supported by the device hardware will be allowed.

Parameters:
  • requestedCardPresentationMethods – The requested card presentation methods

setRequestedPaymentType

public void setRequestedPaymentType(PaymentType paymentType)

Request a specific type of payment. This is required to bypass the payment selection screen when the payment application is handling the payment, otherwise this is optional.

setRequestedTokenParameters

public void setRequestedTokenParameters(ArrayList<TokenParameters> requestedTokens)

Set the requested token parameters of the payment.

setRequestedTokenizationMethod

public void setRequestedTokenizationMethod(TokenizationMethod tokenizationMethod)

Deprecated on 2022-03-01. Please use setRequestedTokenParameters() instead.

setRetrievalReferenceNumber

public void setRetrievalReferenceNumber(String retrievalReferenceNumber)

Set by the application which authorizes the payment with the host.

setSaleNote

public void setSaleNote(String saleNote)

See getSaleNote() for information on how this is used. This is optional.

setSignature

public void setSignature(Image image)

Set the image of the signature collected from the payee. This is provided by the application which processes the payment.

setStoredValueAction

public void setStoredValueAction(StoredValueAction storedValueAction)

Set stored value action. This is optional.

setStoredValueCardInformation

public void setStoredValueCardInformation(StoredValueCardInformation cardInformation)

Set stored card information if the payment involves a gift or other stored value card and the POS already knows the card information to be used for the payment, otherwise this should be empty.

setTerminalData

public void setTerminalData(String terminalData)

Set optional terminal data

setTerminalId

public void setTerminalId(String terminalId)

Set the TID for the acquirer. This is generally configured within the payment application, and is not set by the POS

setTimestamp

public void setTimestamp(String timestamp)

Set the timestamp of payment completion. This is provided by the application that performs the authorization with the host.

setTotalsGroupId

public void setTotalsGroupId(String totalsGroupId)

Group this payment to other payments by an arbitrary ID. This is useful for looking up payments later and for creating reports. This must be set before performing the payment.

setTransactionType

public void setTransactionType(TransactionType transactionType)

This provides a mechanism for the POS to set the type of transaction being requested.

setVasCommands

public void setVasCommands(VasCommands vasCommands)

Refer to getVasCommands().

setVenue

public void setVenue(String venue)

Set the ID of the venue. This is set when the payment is initiated and may not be changed. This may be empty.