1. REST API for <EFTLink>REST API for Oracle Retail EFTLink
  2. Use Cases
  3. Reversal

Reversal

You can perform a Refund/Payment Reversal (Void) request using the REST API for Oracle Retail EFTLink as long as a logon request was successfully performed [for details see the Use Case Logon] and a Refund/Payment [see Use Case Perform a Card Payment as an example] was performed which can be referenced.

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 Reversal (Void) request and response.

To perform a Payment Reversal (Void) request:

URL: wss://localhost:8443/reversal

Sample request from client:

{
       "POSdata":
       {
                "TransactionNumber":"217",
                "StoreID":"731",
                "LanguageCode":"eng"
      },
      "TotalAmount":
      {
             "Currency":"GBP",
             "text":"50.00"
      },
      "OriginalTransaction":
      {
             "TimeStamp":"2020-07-08 12:50:18",
             "STAN":"732164",
             "TerminalId":"1",
             "AcquirerTransactionReference":"732164",
             "ApprovalCode":"154310"
      },
      "PaymentProviderName":"",
      "RequestType":"",
      "RequestSubType":"",
      "ApplicationSender":"XSTORE",
      "WorkstationID":"1",
 }

Note:

There is an additional object required, "OriginalTransaction". 
{
      "TimeStamp":"2020-07-08 12:50:18",
      "STAN":"732164",
      "TerminalId":"1",
      "AcquirerTransactionReference":"732164",
      "ApprovalCode":"154310"
}

The "OriginalTransaction" object will contain the STAN and AcquirerTransactionReference which will be required for the payment provider to match against the original payment in order to perform the reversal/void. Also please note that the void is only possible against payments which have not been captured (submitted to the bank). Typically transactions are captured at the end of each business day which means there is usually only a 24 hour window of opportunity to perform the reversal/void.

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="3" WorkstationID="1" ApplicationSender="XSTORE" RequestType="PaymentReversal">
  <POSdata LanguageCode="en">
    <POSTimeStamp>2020-07-10T09:46:01</POSTimeStamp>
    <StoreID>731</StoreID>
    <TransactionNumber>217</TransactionNumber>
  </POSdata>
  <OriginalTransaction STAN="732164" TerminalID="1" AcquirerTransactionReference="732164" ApprovalCode="154310"/>
  <TotalAmount Currency="GBP">50.00</TotalAmount>
</CardServiceRequest>

Note:

The customer does not necessarily need to be present when the reversal/void is performed. The card interaction with the payment device is not typically required.

SSL socket channel 1 on the client will receive the following request:

<?xml version="1.0" encoding="UTF-8"?>
<DeviceRequest RequestID="3.1" WorkstationID="1" ApplicationSender="MICROS" RequestType="Output">
  <Output OutDeviceTarget="CashierDisplay">
    <TextLine>VOIDING TRANSACTION</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":"3.1",
       "Output":
       {
              "OutDeviceTarget":"CashierDisplay",
              "TextLine":"VOIDING TRANSACTION"
       },
       "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":"3.1",
        "OverallResult":"Success"
}

SSL socket channel 1 on the client will receive the following response:

<?xml version="1.0" encoding="UTF-8"?>
<DeviceResponse RequestID="3.1" WorkstationID="1" OverallResult="Success" ApplicationSender="MICROS" RequestType="Output">
  <Output OutDeviceTarget="CashierDisplay" OutResult="Success"/>
</DeviceResponse>

SSL socket channel 1 may receive another notification as follows:

<?xml version="1.0" encoding="UTF-8"?>
<DeviceRequest RequestID="3.2" WorkstationID="1" ApplicationSender="MICROS" RequestType="Output">
  <Output OutDeviceTarget="CashierDisplay">
    <TextLine>Reversal Approved</TextLine>
  </Output>
</DeviceRequest>

This will be converted to the following JSON request and sent over the web socket channel to the client:

{
      "RequestType":"Output",
      "ApplicationSender":"MICROS",
      "WorkstationID":"1",
      "RequestID":"3.2",
      "Output":
      {
              "OutDeviceTarget":"CashierDisplay",
              "TextLine":"Reversal Approved"
      },
      "Input":
      {
            "Command":
            {
                "PII":false,
                "Command":"GetAnyKey"
            },
            "CustomerOptions":[]
      }
}

SSL socket channel 1 on the client will receive the following response:

<?xml version="1.0" encoding="UTF-8"?>
<DeviceResponse RequestID="3.2" WorkstationID="1" OverallResult="Success" ApplicationSender="MICROS" RequestType="Output">
  <Output OutDeviceTarget="CashierDisplay" OutResult="Success"/>
</DeviceResponse>

Note:

The response should be sent as soon as the text to display has been rendered on the client user interface.

If the EFTLink payment Core is configured to provide a merchant copy of the receipt a device request will be sent back on SSL socket channel 1 as follows:

<?xml version="1.0" encoding="UTF-8"?>
<DeviceRequest RequestID="3.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> Merchant Copy</TextLine>
    <TextLine/>
    <TextLine>Merchant ID : Simulator123456</TextLine>
    <TextLine>Terminal ID : 12345678</TextLine>
    <TextLine/>
    <TextLine>Trans. Type : VOID</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 : 10/07/2020 09:46</TextLine>
    <TextLine>Trace No.   : 589201</TextLine>
    <TextLine>RRN         : 979181</TextLine>
    <TextLine>Offline Auth: N</TextLine>
    <TextLine>Auth Code   : 427884</TextLine>
    <TextLine/>
    <TextLine>App Label   : Personal Account</TextLine>
    <TextLine>AID         : A000000#####0801</TextLine>
    <TextLine>AC          : 52A80ACE8E0D9CA4</TextLine>
    <TextLine/>
    <TextLine>AMOUNT      : ??50.00</TextLine>
    <TextLine> TOTAL      : ??50.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 back on the web socket channel as follows:

{
       "RequestType":"Output",
       "ApplicationSender":"MICROS",
       "WorkstationID":"1",
       "RequestID":"3.3",
       "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 : VOID\n\n
              
              Cardh. Name : Mr A BMSTESTCARDA5603\n
              Card No.    : XXXXXXXXXXXX0002\n
              Card Type   : VISA\n
              Exp. Date   : 9912\n\n
              
              Trans. Time : 10/07/2020 09:46\n
              Trace No.   : 589201\n
              RRN         : 979181\n
              Offline Auth: N\n
              Auth Code   : 427884\n\n
              
              App Label   : Personal Account\n
              AID         : A000000025010801\n
              AC          : 52A80ACE8E0D9CA4\n\n
              
              AMOUNT      : ??50.00\n 
              TOTAL       : ??50.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":"3.3",
       "OverallResult":"Success"
}

SSL socket channel 1 on the client will receive the following response:

<?xml version="1.0" encoding="UTF-8"?>
<DeviceResponse RequestID="3.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:

Note:

In this instance the EFTLink Core is configured for combined receipts which means the customer copy of the receipt will be embedded in the CardServiceResponse as follows. 
<?xml version="1.0" encoding="UTF-8"?>
<CardServiceResponse RequestID="3" WorkstationID="1" OverallResult="Success" ApplicationSender="XSTORE" RequestType="PaymentReversal">
  <Terminal STAN="732164" TerminalID="12345678" MerchantID="Simulator123456"/>
  <Tender>
    <TotalAmount Currency="GBP">50.00</TotalAmount>
    <Authorization CardType="0" AcquirerID="UNKNOWN" AcquirerTransactionReference="732164" TimeStamp="2020-07-10T09:46:04"/>
  </Tender>
  <CardValue CardType="0">
    <Token>C342189########5477</Token>
  </CardValue>
  <PaymentProviderName>oracle.eftlink.opiretail.OPIRetailCore</PaymentProviderName>
  <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 : VOID</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 : 10/07/2020 09:46</TextLine>
  <TextLine>Trace No.   : 589201</TextLine>
  <TextLine>RRN         : 979181</TextLine>
  <TextLine>Offline Auth: N</TextLine>
  <TextLine>Auth Code   : 427884</TextLine>
  <TextLine/>
  <TextLine>App Label   : Personal Account</TextLine>
  <TextLine>AID         : A000000#####0801</TextLine>
  <TextLine>AC          : 52A80ACE8E0D9CA4</TextLine>
  <TextLine/>
  <TextLine>AMOUNT      : ??50.00</TextLine>
  <TextLine> TOTAL      : ??50.00</TextLine>
  <TextLine/>
  <TextLine>Approved</TextLine>
  <TextLine/>
  <TextLine>I agree to the terms of my</TextLine>
  <TextLine>credit agreement.</TextLine>
</CardServiceResponse>

This will then be converted to JSON and sent to the client on the web socket channel:

{
      "Terminal":
      {
               "TerminalID":"12345678",
               "MerchantID":"Simulator123456",
               "STAN":"732164"
      },
      "Tender":
      {
              "TotalAmount":
              {
                   "Currency":"GBP",
                   "text":"50.00"
              },
              "Authorization":
              {
                     "AcquirerID":"UNKNOWN",
                     "AcquirerTransactionReference":"732164",
                     "TimeStamp":"Fri Jul 10 09:46:04 BST 2020",
                     "CardType":"0",
                     "EntryMode":"0"
              }
      },
      "CardValue":
      {
             "ICC":{},
             "Category":"0",
             "Token":"C342189118228895477",
             "CardType":"0",
             "EntryMode":"0"
      },
      "PaymentProviderName":"oracle.eftlink.opiretail.OPIRetailCore",
      "RequestType":"3",
      "ApplicationSender":"XSTORE",
      "WorkstationID":"1","RequestID":"3",
      "OverallResult":"Success",
      "Success":true,
      "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 : VOID\n\n
      
      Cardh. Name : Mr A BMSTESTCARDA5603\n
      Card No.    : XXXXXXXXXXXX0002\n
      Card Type   : VISA\n
      Exp. Date   : 9912\n\n
      
      Trans. Time : 10/07/2020 09:46\n
      Trace No.   : 589201\n
      RRN         : 979181\n
      Offline Auth: N\n
      Auth Code   : 427884\n\n
      
      App Label   : Personal Account\n
      AID         : A000000025010801\n
      AC          : 52A80ACE8E0D9CA4\n\n
      
      AMOUNT      : ??50.00\n 
      TOTAL       : ??50.00\n\n
      
      Approved\n\n
     
     I agree to the terms of my\n
     credit agreement."
}