Perform a Payment [PAY]

Method Name: PAY

Performs a payment

Request

Level	Node Name	Node Value(s)	Notes
1	Payment
2	Action	PAY REFUND VOID	Perform a Payment Perform a Refund Voids a previous Payment
2	Phase	NONE (default)	It is the default phase and it is the one normally used for electronic payments.
		BEGIN	It starts a payment transaction (use only if multiple interactions are needed)
		DO	It performs a payment step (use only if multiple interactions are needed)
		COMMIT	It commits a payment transaction (use only if multiple interactions are needed)
		ROLLBACK	it rollbacks a payment transaction (use only if multiple interactions are needed)
2	PaymentChannel	STD MVP NHS	Specify the payment channel to be used. STD = Standard (default) MVP = Meal Voucher Provider NHS = National Health Service
2	PrintLocation	ECR EFT	Specify where the payment receipt will be printed: ECR - On ECR EFT - On EFT
2	Reference	<string>	An optional string that can be passed to the provider and/or printed on the payment receipt
2	MerchantCode	<string>	Code of the Merchant
2	StoreCode	<string>	Code of the Store
2	TillCode	<string>	Code of the Till
2	OperatorId	<string>	Code of the Operator that performed the payment transaction
2	Amount	<currency>	Amount of the Payment requested. Does not include the Tip Amount
2	Currency	<string>	Currency Code of the Payment Transaction based on ISO4217Alpha standard
2	TipAmount	<currency>	Amount of the tip if sent by the ECR
2	RequestTipAmount	<boolean>	If true, the Tip Amount will be requested on the EFT
2	MaxAmount	<currency>	Max Amount payable
2	MaxItems	<integer>	Max number of redeemable Items (in case of Meal Vouchers)
2	TokenizeCard	<boolean>	If true the card will be tokenized so that it can be used for future or recurring payments
2	TokenReference	<string>	A string that will be used to generate the token
2	Attributes	<string>	Additional attributes requested by the payment provider. In case of serialized vouchers, this field must contain the code of the voucher to be redeemed
2	ReceiptColCount	<integer>	Used only if the EFT returns the receipt text with dynamic alignment.
2	RefundReference		Only in case of Refund
3	PaymentId	<string>	Id of the original payment receipt
3	PaymentDateTime	<datetime>	Date/Time of the original payment receipt
1	Receipt	<ReceiptObject>	Receipt

Example

XML

<Payment>
  <PrintLocation>ECR</PrintLocation>
  <Reference>Test Payment</Reference>
  <StoreCode>S01</StoreCode>
  <TillCode>001</TillCode>
  <Amount>0.02</Amount>
  <Currency>EUR</Currency>
</Payment>
<Receipt>
  ...
</Receipt>

Response

Level	Node Name	Node Value(s)	Notes
1	DeviceID	<string>	Device ID
1	PaymentDateTime	<datetime>	Date/Time of the Payment
1	PaymentNumber	<string>	Id of the Payment Transaction
1	PaymentAmount	<currency>	Amount of the Payment
1	PaymentCurrency	<string>	Currency of the Payment based on ISO4217Alpha standard
1	ExchangeRate	<currency>	Exchange Rate
1	PaymentAmountCurrency	<currency>	DCC Amount of the Payment
1	PaymentCurrencyCurrency	<string>	DCC Currency of the Payment based on ISO4217Alpha standard
1	TippedAmount	<currency>	Amount of the Tip
1	RemainingBalance	<currency>	Residual Balance of the Card
1	MaskedPAN	<string>	Masked PAN of the Card
1	SerialNumber	<string>	Serial Number of the Card
1	PaymentNetwork	bank cheque visa amex mastercard jcb cup diners maestro alipay discover doku dragonpay molpay satispay scalapay nhs other	The network to which the payment has been performed
1	PaymentNetwork	edenred day sodexo pellegrini bluticket jakala miglunch quiticket cir sodexo ep repas gemeaz ristomat agape lunchtime quiwelfare	Meal voucher providers
1	TransactionType	CHIP MAGSTRIPE MANUAL CLESS CLESSMAGSTRIPE CLESSCHIP RFID OTHER	Mode of the payment transaction
1	AuthCode	<string>	Authorization Code released by the payment provider
1	TraceAuditId	<string>	Trace Audit Id released by the payment provider
1	NumberOfItems	<integer>	Number of “items” redeemed in payment. It is used, for example, in case of meal voucher payment to return the number of meal vouchers used.
1	SingleItemAmount	<currency>	Unit value of the redeemed items.
1	SignatureRequested	<boolean>	If True, Customer must sign the payment receipt
1	CustomerCountryCode	<string>	Customer Country Code based on ISO3166-Alpha2 standard
1	CardToken	<string>	Token to be used for following payments (if TokenizeCard=true in the Request)
1	RefundReference	<string>	String to passed back when a refund is performed
1	ReceiptText	<string>	Text of the Payment Receipt. Lines are separated by CR/LF
1	CashierReceiptText	<string>	Text of the Payment Receipt for the Cashier. If empty it is equal to ReceiptText
1	PaymentLink	<string>	Text with the URL for making the payment (used in Klarna)

Example

XML

<ReceiptPrinterManagerResponse>
  <DeviceId>05041966</DeviceId>
  <PaymentDateTime>2020-07-14T22:06:05.910Z</PaymentDateTime>
  <PaymentNumber>079565</PaymentNumber>
  <PaymentAmount>0.02</PaymentAmount>
  <PaymentCurrency>EUR</PaymentCurrency>
  <ExchangeRate>0</ExchangeRate>
  <PaymentAmountCurrency>0</PaymentAmountCurrency>
  <MaskedPAN>4242********424242</MaskedPAN>
  <PaymentNetwork>visa</PaymentNetwork>
  <TransactionType>CLESSCHIP</TransactionType>
  <AuthCode>565910</AuthCode>
  <TraceAuditId>001326</TraceAuditId>
  <ReceiptText>.....</ReceiptText>
  <Error>False</Error> <ErrorText/>
  <LogFileName/>
</ReceiptPrinterManagerResponse>

Notes on Phases

As said, phases are only to be used in case the payment transaction cannot be performed with a single communication with the payment provider.

This is sometimes the case when using serialized vouchers.

In this scenario the POS software should:

OPEN the payment phase
for each voucher to be used
- request to the operator to scan the voucher barcode
- DO the validation of the voucher
- check the validation result
when completed, COMMIT the payment transaction or (and only if allowed by the payment provider) ROLLBACK the transaction

With normal payments (that are usually performed in a single phase) just leave the Phase node empty (it will default to DO)