Cashback and cash out

Outlines how to cashback or cash out a balance from a card using the Terminal API.


In specific regions, a customer can obtain a cash amount from their account along with their purchase (cashback), or obtain the cash without a purchase (cashout).

To perform cashbacks or cashouts, contact the POS Support Team to enable this feature.

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.

The SaleID and ServiceID in the MessageHeader should be unique. SaleID and ServiceID combinations are rejected if used recently, within 48 hours.

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

PaymentRequest - Cashback
{
  "SaleToPOIRequest": {
    "MessageHeader": {
      "ProtocolVersion": "3.0",
      "MessageClass": "Service",
      "MessageCategory": "Payment",
      "MessageType": "Request",
      "ServiceID": "0622145520",
      "SaleID": "POSTerminal",
      "POIID": "P400Plus-540004072"
    },
    "PaymentRequest": {
      "SaleData": {
        "SaleTransactionID": {
          "TransactionID": "9266",
          "TimeStamp": "2018-06-22T12:55:20+00:00"
        },
        "SaleReferenceID": "SalesRefABC",
        "SaleToAcquirerData": "redemptionType=cashback"
      },
      "PaymentTransaction": {
        "AmountsReq": {
          "Currency": "CAD",
          "RequestedAmount": 30
        }
      },
      "PaymentData": {
        "PaymentType": "Normal",
        "PaymentInstrumentData": {
          "PaymentInstrumentType": "StoredValue",
          "StoredValueAccountID": {
            "StoredValueAccountType": "GiftCard",
            "EntryMode": [
              "MagStripe"
            ],
            "StoredValueProvider": "givex",
            "StoredValueID": "6006491260550218066",
            "IdentificationType": "PAN",
            "ExpiryDate": "1117"
          }
        }
      }
    }
  }
}





 

If RequestedAmount is set to 0, the total value of the card is refunded and the remaining balance on the card is 0. (Givex and SVS).

If RequestedAmount is set to a non-zero value, you will get that amount back, assuming it is available on the card. (Givex only).

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:

PaymentResponse - Cashback
 {
  "SaleToPOIResponse": {
    "PaymentResponse": {
      "POIData": {
        "POITransactionID": {
          "TimeStamp": "2018-06-22T12:55:24.000Z",
          "TransactionID": "u6W7001529672124004.9815296721273135"
        }
      },
      "SaleData": {
        "SaleTransactionID": {
          "TimeStamp": "2018-06-22T12:55:20.000Z",
          "TransactionID": "9266"
        },
        "SaleReferenceID": "SalesRefABC"
      },
      "PaymentReceipt": [
        {
          "RequiredSignatureFlag": false,
          "DocumentQualifier": "CashierReceipt",
          "OutputContent": {
            "OutputFormat": "Text",
            "OutputText": [
              {
                "CharacterStyle": "Bold",
                "Text": "name=Adyen&key=header1",
                "EndOfLineFlag": true
              },
              {
                "Text": "name=www.adyen.com&key=header2",
                "EndOfLineFlag": true
              },
              {
                "Text": "key=filler",
                "EndOfLineFlag": true
              },
              {
                "CharacterStyle": "Bold",
                "Text": "name=MERCHANT%20COPY&key=merchantTitle",
                "EndOfLineFlag": true
              },
              {
                "Text": "key=filler",
                "EndOfLineFlag": true
              },
              {
                "Text": "name=Date&value=22%2f06%2f18&key=txdate",
                "EndOfLineFlag": true
              },
              {
                "Text": "name=Time&value=12%3a55%3a24&key=txtime",
                "EndOfLineFlag": true
              },
              {
                "Text": "key=filler",
                "EndOfLineFlag": true
              },
              {
                "Text": "name=Card&value=%2a%2a%2a%2a%2a%2a%2a%2a%2a%2a%2a%2a%2a%2a%2a%2a%2a5498&key=pan",
                "EndOfLineFlag": true
              },
              {
                "Text": "name=Pref.%20name&key=preferredName",
                "EndOfLineFlag": true
              },
              {
                "Text": "name=Card%20type&value=givex&key=cardType",
                "EndOfLineFlag": true
              },
              {
                "Text": "name=Payment%20method&value=givex&key=paymentMethod",
                "EndOfLineFlag": true
              },
              {
                "Text": "name=Payment%20variant&value=givex&key=paymentMethodVariant",
                "EndOfLineFlag": true
              },
              {
                "Text": "name=Entry%20mode&value=MSR&key=posEntryMode",
                "EndOfLineFlag": true
              },
              {
                "Text": "key=filler",
                "EndOfLineFlag": true
              },
              {
                "Text": "name=MID&value=30458&key=mid",
                "EndOfLineFlag": true
              },
              {
                "Text": "name=TID&value=P400Plus-540004072&key=tid",
                "EndOfLineFlag": true
              },
              {
                "Text": "name=PTID&value=87253103&key=ptid",
                "EndOfLineFlag": true
              },
              {
                "Text": "key=filler",
                "EndOfLineFlag": true
              },
              {
                "Text": "name=Auth.%20code&value=944931&key=authCode",
                "EndOfLineFlag": true
              },
              {
                "Text": "name=ATC&key=atc",
                "EndOfLineFlag": true
              },
              {
                "Text": "name=Tender&value=u6W7001529672124004&key=txRef",
                "EndOfLineFlag": true
              },
              {
                "Text": "name=Reference&value=9266&key=mref",
                "EndOfLineFlag": true
              },
              {
                "Text": "key=filler",
                "EndOfLineFlag": true
              },
              {
                "Text": "name=Type&value=GOODS_SERVICES&key=txtype",
                "EndOfLineFlag": true
              },
              {
                "CharacterStyle": "Bold",
                "Text": "name=TOTAL&value=CAD%2030.00%20%20&key=totalAmount",
                "EndOfLineFlag": true
              },
              {
                "Text": "key=filler",
                "EndOfLineFlag": true
              },
              {
                "CharacterStyle": "Bold",
                "Text": "name=APPROVED&key=approved",
                "EndOfLineFlag": true
              },
              {
                "Text": "key=filler",
                "EndOfLineFlag": true
              },
              {
                "Text": "key=filler",
                "EndOfLineFlag": true
              }
            ]
          }
        },
        {
          "RequiredSignatureFlag": false,
          "DocumentQualifier": "CustomerReceipt",
          "OutputContent": {
            "OutputFormat": "Text",
            "OutputText": [
              {
                "CharacterStyle": "Bold",
                "Text": "name=Adyen&key=header1",
                "EndOfLineFlag": true
              },
              {
                "Text": "name=www.adyen.com&key=header2",
                "EndOfLineFlag": true
              },
              {
                "Text": "key=filler",
                "EndOfLineFlag": true
              },
              {
                "CharacterStyle": "Bold",
                "Text": "name=CARDHOLDER%20COPY&key=cardholderHeader",
                "EndOfLineFlag": true
              },
              {
                "Text": "key=filler",
                "EndOfLineFlag": true
              },
              {
                "Text": "name=Date&value=22%2f06%2f18&key=txdate",
                "EndOfLineFlag": true
              },
              {
                "Text": "name=Time&value=12%3a55%3a24&key=txtime",
                "EndOfLineFlag": true
              },
              {
                "Text": "key=filler",
                "EndOfLineFlag": true
              },
              {
                "Text": "name=Card&value=%2a%2a%2a%2a%2a%2a%2a%2a%2a%2a%2a%2a%2a%2a%2a%2a%2a5498&key=pan",
                "EndOfLineFlag": true
              },
              {
                "Text": "name=Pref.%20name&key=preferredName",
                "EndOfLineFlag": true
              },
              {
                "Text": "name=Card%20type&value=givex&key=cardType",
                "EndOfLineFlag": true
              },
              {
                "Text": "name=Payment%20method&value=givex&key=paymentMethod",
                "EndOfLineFlag": true
              },
              {
                "Text": "name=Payment%20variant&value=givex&key=paymentMethodVariant",
                "EndOfLineFlag": true
              },
              {
                "Text": "name=Entry%20mode&value=MSR&key=posEntryMode",
                "EndOfLineFlag": true
              },
              {
                "Text": "key=filler",
                "EndOfLineFlag": true
              },
              {
                "Text": "name=MID&value=%2a%2a%2a%2a%2a%2a%2a%2a%2a0458&key=mid",
                "EndOfLineFlag": true
              },
              {
                "Text": "name=TID&value=P400Plus-540004072&key=tid",
                "EndOfLineFlag": true
              },
              {
                "Text": "name=PTID&value=87253103&key=ptid",
                "EndOfLineFlag": true
              },
              {
                "Text": "key=filler",
                "EndOfLineFlag": true
              },
              {
                "Text": "name=Auth.%20code&value=944931&key=authCode",
                "EndOfLineFlag": true
              },
              {
                "Text": "name=ATC&key=atc",
                "EndOfLineFlag": true
              },
              {
                "Text": "name=Tender&value=u6W7001529672124004&key=txRef",
                "EndOfLineFlag": true
              },
              {
                "Text": "name=Reference&value=9266&key=mref",
                "EndOfLineFlag": true
              },
              {
                "Text": "key=filler",
                "EndOfLineFlag": true
              },
              {
                "Text": "name=Type&value=GOODS_SERVICES&key=txtype",
                "EndOfLineFlag": true
              },
              {
                "CharacterStyle": "Bold",
                "Text": "name=TOTAL&value=CAD%2030.00%20%20&key=totalAmount",
                "EndOfLineFlag": true
              },
              {
                "Text": "key=filler",
                "EndOfLineFlag": true
              },
              {
                "CharacterStyle": "Bold",
                "Text": "name=APPROVED&key=approved",
                "EndOfLineFlag": true
              },
              {
                "Text": "key=filler",
                "EndOfLineFlag": true
              },
              {
                "Text": "name=Please%20retain%20for%20your%20records&key=retain",
                "EndOfLineFlag": true
              },
              {
                "Text": "key=filler",
                "EndOfLineFlag": true
              },
              {
                "Text": "key=filler",
                "EndOfLineFlag": true
              },
              {
                "Text": "name=Thank%20you&key=thanks",
                "EndOfLineFlag": true
              }
            ]
          }
        }
      ],
      "PaymentResult": {
        "PaymentAcquirerData": {
          "AcquirerPOIID": "P400Plus-540004072",
          "AcquirerTransactionID": {
            "TimeStamp": "2018-06-22T12:55:24.000Z",
            "TransactionID": "9815296721273135"
          },
          "MerchantID": "TestMerchantPOS"
        },
        "PaymentInstrumentData": {
          "StoredValueAccountID": {
            "IdentificationType": "PAN",
            "EntryMode": [
              "MagStripe"
            ],
            "StoredValueID": "603628173862001915498",
            "StoredValueAccountType": "GiftCard",
            "StoredValueProvider": "givex",
            "ExpiryDate": "1249"
          },
          "PaymentInstrumentType": "StoredValue"
        },
        "AmountsResp": {
          "AuthorizedAmount": 30,
          "Currency": "CAD"
        },
        "PaymentType": "Normal"
      },
      "Response": {
        "Result": "Success",
        "AdditionalResponse": "tid=87253103&transactionType=GOODS_SERVICES&pspReference=9815296721273135&currentBalanceCurrency=CAD&offline=false&giftcardTrack2=603628173862001915498&mid=30458&note=Direct%20API%20REQUIRES%20payload%20crypto%20on%20live%2c%20cleartext%20allowed%20for%20testing%20only&giftcardPAN=603628173862001915498&currentBalanceValue=15000"
      }
    },
    "MessageHeader": {
      "ProtocolVersion": "3.0",
      "SaleID": "POSTerminal",
      "MessageClass": "Service",
      "MessageCategory": "Payment",
      "ServiceID": "0622145520",
      "POIID": "P400Plus-540004072",
      "MessageType": "Response"
    }
  }
}