Perform a Card Payment
You can perform a card payment request using the REST API for Oracle Retail EFTLink as long as a logon request was successfully performed. For more details, see the use case Logon.
Note:
The following use case will also describe interactions which include how to handle the device requests and responses which may occur during the payment request and response.To perform a payment request:
URL: wss://localhost:8443/paymentSample request from client:
{
"POSdata":
{
"TransactionNumber":"217",
"StoreID":"731",
"LanguageCode":"eng"
},
"TotalAmount":
{
"Currency":"GBP",
"text":"5.00"
},
"PaymentProviderName":"",
"RequestType":"",
"RequestSubType":"",
"ApplicationSender":"XSTORE",
"WorkstationID":"1",
}This will then be converted to the following IFSF XML request and sent over the SSL socket channel 0:
<?xml version="1.0" encoding="UTF-8"?>
<CardServiceRequest RequestID="2" WorkstationID="1" ApplicationSender="XSTORE" RequestType="CardPayment">
<POSdata LanguageCode="en">
<POSTimeStamp>2020-06-26T15:36:57</POSTimeStamp>
<StoreID>731</StoreID>
<TransactionNumber>217</TransactionNumber>
</POSdata>
<TotalAmount Currency="GBP">5.00</TotalAmount>
</CardServiceRequest>In this use case the payment will be authorized but there will be data in the payment provider's response which may require more interaction with the client in order to finalise the transaction.
SSL socket channel 1 on the client will receive the following request:
<?xml version="1.0" encoding="UTF-8"?>
<DeviceRequest RequestID="2.1" WorkstationID="1" ApplicationSender="MICROS" RequestType="Output">
<Output OutDeviceTarget="CashierDisplay">
<TextLine>Transaction Approved</TextLine>
</Output>
</DeviceRequest>This will then be converted to JSON and sent to the client on the web socket channel:
{
"RequestType":"Output",
"ApplicationSender":"MICROS",
"WorkstationID":"1",
"RequestID":"2.1",
"Output":
{
"OutDeviceTarget":"CashierDisplay",
"TextLine":"Transaction Approved"
},
"Input":
{
"Command":
{
"PII":false,
"Command":"GetAnyKey"
},
"CustomerOptions":
[]
}This particular device request is a message to display. The client must respond with an acknowledgement on the same web socket channel, the following JSON is the response to the device request:
{
"Output":
{
"OutDeviceTarget":"CashierDisplay",
"OutResult":"Success"
},
"RequestType":"Output",
"ApplicationSender":"MICROS",
"WorkstationID":"1",
"RequestID":"2.1",
"OverallResult":"Success"
}SSL socket channel 1 on the client will receive the following response:
<?xml version="1.0" encoding="UTF-8"?>
<DeviceResponse RequestID="2.1" WorkstationID="1" OverallResult="Success" ApplicationSender="MICROS" RequestType="Output">
<Output OutDeviceTarget="CashierDisplay" OutResult="Success"/>
</DeviceResponse>Note:
This response should be sent as soon as the text to display has been rendered on the client user interface.EFTLink will receive receipt data from the payment provider. This data needs to be sent back to the client so that it can print the receipt for the customer. Typically a merchant copy is printed first before the customer copy. The client should be able to receive this data at any point before it receives the final authorization response for the payment request.
SSL socket channel 1 on the client will receive the following merchant receipt print request:
<?xml version="1.0" encoding="UTF-8"?>
<DeviceRequest RequestID="2.2" WorkstationID="1" ApplicationSender="MICROS" RequestType="Output">
<Output OutDeviceTarget="Printer">
<TextLine>Demo Res</TextLine>
<TextLine>ORACLE Demo Store</TextLine>
<TextLine>888 Test Ave., Columbia,MD</TextLine>
<TextLine/>
<TextLine> Merchant Copy</TextLine>
<TextLine/>
<TextLine>Merchant ID : Simulator123456</TextLine>
<TextLine>Terminal ID : 12345678</TextLine>
<TextLine/>
<TextLine>Trans. Type : SALE</TextLine>
<TextLine/>
<TextLine>Cardh. Name : Mr A BMSTESTCARDA5603</TextLine>
<TextLine>Card No. : XXXXXXXXXXXX0002</TextLine>
<TextLine>Card Type : VISA</TextLine>
<TextLine>Exp. Date : 9912</TextLine>
<TextLine/>
<TextLine>Trans. Time : 26/06/2020 15:37</TextLine>
<TextLine>Trace No. : 400814</TextLine>
<TextLine>RRN : 851388</TextLine>
<TextLine>Offline Auth: N</TextLine>
<TextLine>Auth Code : 830842</TextLine>
<TextLine/>
<TextLine>App Label : Personal Account</TextLine>
<TextLine>AID : A000000#####0801</TextLine>
<TextLine>AC : 52A80ACE8E0D9CA4</TextLine>
<TextLine/>
<TextLine>AMOUNT : ??5.00</TextLine>
<TextLine> TOTAL : ??5.00</TextLine>
<TextLine/>
<TextLine>Approved</TextLine>
<TextLine/>
<TextLine/>
<TextLine>I agree to the terms of my</TextLine>
<TextLine>credit agreement.</TextLine>
</Output>
</DeviceRequest>This will then be converted to JSON and sent to the client on the web socket channel:
Note:
"OutDeviceTarget":"Printer" denotes a print request to the client, so the client must be able to interpret this as a request to print the data to the printer. The data to be printed is harvested from the "TextLine" key.{
"RequestType":"Output",
"ApplicationSender":"MICROS",
"WorkstationID":"1",
"RequestID":"2.2",
"Output":
{
"OutDeviceTarget":"Printer",
"TextLine":
"Demo Res\n
ORACLE Demo Store\n
888 Test Ave., Columbia,MD\n\n
Merchant Copy\n\n
Merchant ID : Simulator123456\n
Terminal ID : 12345678\n\n
Trans. Type : SALE\n\n
Cardh. Name : Mr A BMSTESTCARDA5603\n
Card No. : XXXXXXXXXXXX0002\n
Card Type : VISA\n
Exp. Date : 9912\n\n
Trans. Time : 26/06/2020 15:37\n
Trace No. : 400814\n
RRN : 851388\n
Offline Auth: N\n
Auth Code : 830842\n\n
App Label : Personal Account\n
AID : A000000025010801\n
AC : 52A80ACE8E0D9CA4\n\n
AMOUNT : ??5.00\n
TOTAL : ??5.00\n\n
Approved\n\n\n
I agree to the terms of my\n
Credit agreement."
},
"Input":
{
"Command":
{
"PII":false,
"Command":"GetAnyKey"
},
"CustomerOptions":[]
}
}The client should acknowledge the print request by sending the following JSON object on the same WebSocket channel:
Note:
EFTLink can wait up to 3 minutes to receive the device response before continuing the transaction. If the time out expires EFTLink will continue with the remainder of the transaction workflow.{
"Output":
{
"OutDeviceTarget":"CashierDisplay",
"OutResult":"Success"
},
"RequestType":"Output",
"ApplicationSender":"MICROS",
"WorkstationID":"1",
"RequestID":"2.2",
"OverallResult":"Success"
}SSL socket channel 1 on the client will receive the following response:
<?xml version="1.0" encoding="UTF-8"?>
<DeviceResponse RequestID="2.2" WorkstationID="1" OverallResult="Success" ApplicationSender="MICROS" RequestType="Output">
<Output OutDeviceTarget="Printer" OutResult="Success"/>
</DeviceResponse>Note:
The customer receipt will typically follow the merchant receipt if the EFTLink Core is not configured for combined receipt functionality. For this use case this does not consider the combined receipt flow.SSL socket channel 1 on the client will receive the following device request for the client to print the customer copy of the payment receipt:
<?xml version="1.0" encoding="UTF-8"?>
<DeviceRequest RequestID="2.3" WorkstationID="1" ApplicationSender="MICROS" RequestType="Output">
<Output OutDeviceTarget="Printer">
<TextLine> Demo Res</TextLine>
<TextLine>ORACLE Demo Store</TextLine>
<TextLine>888 Test Ave., Columbia,MD</TextLine>
<TextLine/>
<TextLine> Customer Copy</TextLine>
<TextLine/>
<TextLine>Merchant ID : Simulator123456</TextLine>
<TextLine>Terminal ID : 12345678</TextLine>
<TextLine/>
<TextLine>Trans. Type : SALE</TextLine>
<TextLine/>
<TextLine>Cardh. Name : Mr A BMSTESTCARDA5603</TextLine>
<TextLine>Card No. : XXXXXXXXXXXX0002</TextLine>
<TextLine>Card Type : VISA</TextLine>
<TextLine>Exp. Date : 9912</TextLine>
<TextLine/>
<TextLine>Trans. Time : 26/06/2020 15:37</TextLine>
<TextLine>Trace No. : 400814</TextLine>
<TextLine>RRN : 851388</TextLine>
<TextLine>Offline Auth: N</TextLine>
<TextLine>Auth Code : 830842</TextLine>
<TextLine/>
<TextLine>App Label : Personal Account</TextLine>
<TextLine>AID : A000000#####0801</TextLine>
<TextLine>AC : 52A80ACE8E0D9CA4</TextLine>
<TextLine/>
<TextLine>AMOUNT : ??5.00</TextLine>
<TextLine> TOTAL : ??5.00</TextLine>
<TextLine/>
<TextLine>Approved</TextLine>
<TextLine/>
<TextLine>I agree to the terms of my</TextLine>
<TextLine>credit agreement.</TextLine>
</Output>
</DeviceRequest>This will then be converted to JSON and sent to the client on the web socket channel:
{
"RequestType":"Output",
"ApplicationSender":"MICROS",
"WorkstationID":"1",
"RequestID":"2.3",
"Output":
{
"OutDeviceTarget":"Printer",
"TextLine":
" Demo Res\n
ORACLE Demo Store\n
888 Test Ave., Columbia,MD\n\n
Customer Copy\n\n
Merchant ID : Simulator123456\n
Terminal ID : 12345678\n\n
Trans. Type : SALE\n\n
Cardh. Name : Mr A BMSTESTCARDA5603\n
Card No. : XXXXXXXXXXXX0002\n
Card Type : VISA\n
Exp. Date : 9912\n\n
Trans. Time : 26/06/2020 15:37\n
Trace No. : 400814\n
RRN : 851388\n
Offline Auth: N\n
Auth Code : 830842\n\n
App Label : Personal Account\n
AID : A000000025010801\n
AC : 52A80ACE8E0D9CA4\n\n
AMOUNT : ??5.00\n
TOTAL : ??5.00\n\n
Approved\n\n
I agree to the terms of my\n
credit agreement."
},
"Input":
{
"Command":
{
"PII":false,
"Command":"GetAnyKey"
},
"CustomerOptions":[]
}
}The following acknowledgement should then be sent over the websocket channel once the receipt has been printed by the client:
{
"Output":
{
"OutDeviceTarget":"CashierDisplay",
"OutResult":"Success"
},
"RequestType":"Output",
"ApplicationSender":"MICROS",
"WorkstationID":"1",
"RequestID":"2.3",
"OverallResult":"Success"
}This will then be converted and sent back on channel 1 to EFTLink:
<?xml version="1.0" encoding="UTF-8"?>
<DeviceResponse RequestID="2.3" WorkstationID="1" OverallResult="Success" ApplicationSender="MICROS" RequestType="Output">
<Output OutDeviceTarget="Printer" OutResult="Success"/>
</DeviceResponse>Finally the client will receive the following payment response on channel 0 as follows:
<?xml version="1.0" encoding="UTF-8"?>
<CardServiceResponse RequestID="2" WorkstationID="1" OverallResult="Success" ApplicationSender="XSTORE" RequestType="CardPayment">
<Terminal STAN="851388" TerminalID="12345678" MerchantID="Simulator123456"/>
<Tender>
<TotalAmount Currency="GBP">5.00</TotalAmount>
<Authorization CardPAN="XXXXXX******0002" ExpiryDate=###### CardType="80" CardCircuit="VISA" EntryMode="ICC" AcquirerID="UNKNOWN" AcquirerTransactionReference="851388" TimeStamp="2020-06-26T15:37:12" ApprovalCode="830842"/>
</Tender>
<CardValue CardType="80" EntryMode="ICC" LoyaltyEligible="true">
<CardPAN>XXXXXX******0002</CardPAN>
<EndDate>####</EndDate>
<CardCircuit>VISA</CardCircuit>
<Token>VaultCardToken123</Token>
<VaultCardToken>VaultCardToken123</VaultCardToken>
</CardValue>
<PaymentProviderName>oracle.eftlink.opiretail.OPIRetailCore</PaymentProviderName>
</CardServiceResponse>This will then be converted to JSON and sent to the client on the web socket channel:
{
"Terminal":
{
"TerminalID":"12345678",
"MerchantID":"Simulator123456"
},
"Tender":
{
"TotalAmount":
{
"Currency":"GBP",
"text":"5.00"
},
"Authorization":
{
"AcquirerID":"UNKNOWN",
"AcquirerTransactionReference":"851388",
"TimeStamp":"Fri Jun 26 15:37:12 BST 2020",
"ApprovalCode":"830842",
"CardType":"80",
"EntryMode":"3",
"CardPAN":"XXXXXX******0002",
"ExpiryDate":"1299"
}
},
"CardValue":
{
"ICC":{},
"CardPAN":"XXXXXX******0002",
"EndDate":"1299",
"CardCircuit":"VISA",
"Category":"0",
"Token":"C411673288324019380",
"TransactionReference":"1299",
"CardType":"80",
"EntryMode":"2"
},
"PaymentProviderName":"oracle.eftlink.opiretail.OPIRetailCore",
"RequestType":"1",
"ApplicationSender":"XSTORE",
"WorkstationID":"1",
"RequestID":"2",
"OverallResult":"Success",
"Success":true
}