Cashback and cash out

Shoppers using an EFTPOS (Electronic Funds Transfer at Point Of Sale) card in Australia can obtain a small amount of cash from their account, either:

• With their purchase (cashback).
• Without a purchase (cash out).

Endpoint

The URL used to send Terminal API messages depends on your type of implementation. For more information on the architectures available, see the Terminal API Overview.

Request

For a list of Payment Request fields, see PaymentRequest fields. The elements of a login request are wrapped in a PaymentRequest envelope.

Pass the following fields when making a PaymentRequest call to the Terminal API:

• PaymentTransaction.AmountsReq.RequestedAmount: The total amount to be paid by the shopper, including the amount for the purchase and for the cashback.
• PaymentTransaction.AmountsReq.CashBackAmount: The cashback amount.

The example below shows how you would make a request if a shopper purchased goods for 10 AUD, and wants to obtain a cashback of 2 AUD:

{
  "SaleToPOIRequest": {
    "MessageHeader": {
      "ProtocolVersion": "3.0",
      "MessageClass": "Service",
      "MessageCategory": "Payment",
      "MessageType": "Request",
      "ServiceID": "0501160930",
      "SaleID": "POSSystemID12345",
      "POIID": "P400Plus-540004072"
    },
    "PaymentRequest": {
      "SaleData": {
        "SaleTransactionID": {
          "TransactionID": "3375",
          "TimeStamp": "2018-05-01T14:09:30+00:00"
        }
      },
      "PaymentTransaction": {
        "AmountsReq": {
          "Currency": "AUD",
          "RequestedAmount": 1200,
          "CashBackAmount": 200
        }
      }
    }
  }
}

String serviceID = "YOUR_UNIQUE_ATTEMPT_ID";
String saleID = "YOUR_CASH_REGISTER_ID";
String POIID = "YOUR_TERMINAL_ID";
String transactionID = "YOUR_UNIQUE_TRANSACTION_ID";

SaleToPOIRequest saleToPOIRequest = new SaleToPOIRequest();
MessageHeader messageHeader = new MessageHeader();
messageHeader.setProtocolVersion("3.0");
messageHeader.setMessageClass( MessageClassType.SERVICE );
messageHeader.setMessageCategory( MessageCategoryType.PAYMENT );
messageHeader.setMessageType( MessageType.REQUEST );
messageHeader.setServiceID(serviceID);
messageHeader.setSaleID(saleID);
messageHeader.setPOIID(POIID);
saleToPOIRequest.setMessageHeader(messageHeader);

PaymentRequest paymentRequest = new PaymentRequest();
SaleData saleData = new SaleData();
TransactionIdentification saleTransactionID = new TransactionIdentification();
saleTransactionID.setTransactionID(transactionID);
saleTransactionID.setTimeStamp(DatatypeFactory.newInstance().newXMLGregorianCalendar(new GregorianCalendar()));
saleData.setSaleTransactionID(saleTransactionID);
paymentRequest.setSaleData(saleData);

PaymentTransaction paymentTransaction = new PaymentTransaction();
AmountsReq amountsReq = new AmountsReq();
amountsReq.setCurrency("AUD");
amountsReq.setRequestedAmount( BigDecimal.valueOf(1200) );
amountsReq.setCashBackAmount( BigDecimal.valueOf(200) );
paymentTransaction.setAmountsReq(amountsReq);
paymentRequest.setPaymentTransaction(paymentTransaction);
saleToPOIRequest.setPaymentRequest(paymentRequest);
terminalAPIRequest.setSaleToPOIRequest(saleToPOIRequest);

Response

For a list of Payment Response fields, see PaymentResponse fields.

The payment response contains information about the status of the cashback or cashout in the following fields:

{
  "SaleToPOIResponse": {
    "PaymentResponse": {
      "POIData": {
        "POITransactionID": {
          "TimeStamp": "2018-05-01T14:09:30.000Z",
          "TransactionID": "u6W7001525183770000.9815251837923768"
        }
      },
      "SaleData": {
        "SaleTransactionID": {
          "TimeStamp": "2018-05-01T14:09:30.000Z",
          "TransactionID": "3375"
        }
      },
      "PaymentResult": {
        "AuthenticationMethod": [
          "OnlinePIN"
        ],
        "PaymentAcquirerData": {
          "AcquirerPOIID": "P400Plus-540004072",
          "AcquirerTransactionID": {
            "TimeStamp": "2018-05-01T14:09:30.000Z",
            "TransactionID": "9815251837923768"
          },
          "MerchantID": "TestMerchantPOSAU1"
        },
        "PaymentInstrumentData": {
          "CardData": {
            "EntryMode": [
              "MagStripe"
            ],
            "PaymentBrand": "eftpos_australia_sav",
            "MaskedPan": "637204 **** 0025",
            "SensitiveCardData": {
              "ExpiryDate": "1220"
            }
          },
          "PaymentInstrumentType": "Card"
        },
        "AmountsResp": {
          "AuthorizedAmount": 400,
          "CashBackAmount": 20,
          "Currency": "AUD"
        }
      },
      "Response": {
        "Result": "Success",
        "AdditionalResponse": "tid=87253103&transactionType=GOODS_SERVICES_WITH_CASHBACK&pspReference=9815251837923768&cardHolderName=&offline=false&mid=000023000000015&note=Direct%20API%20REQUIRES%20payload%20crypto%20on%20live%2c%20cleartext%20allowed%20for%20testing%20only&cardHolderVerificationMethodResults=020300&cashBackAmountValue=20"
      }
    },
    "MessageHeader": {
      "ProtocolVersion": "3.0",
      "SaleID": "POSSystemID12345",
      "MessageClass": "Service",
      "MessageCategory": "Payment",
      "ServiceID": "0501160930",
      "POIID": "P400Plus-540004072",
      "MessageType": "Response"
    }
  }
}