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

Example

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

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
scalapay
nhs
other

The network to which the payment has been performed

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

Example

<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>
XML

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)