On This Page

Cashback

Use this information to process a cashback transaction when the app is in Local mode. This type of transaction enables customers to request that a specified amount of cash to be given to them as part of the transaction. A cashback transaction can be processed with or without a purchase.

Endpoints

The endpoint is the same for the test and production environments.

Test:

wss://{terminal IP address:port number}/

Production:

wss://{terminal IP address:port number}/

Required Fields for a Cashback

type: Set the value to
PaymentRequest
.
merchantReferenceCode: Set the value to a unique, user-defined reference code. The code can consist of up to 50 alphanumeric characters, underscores (_), and dashes (-). Avoid using formatting that resembles a telephone number (XXX-XXX-XXXX) or a Social Security number (XXX-XX-XXXX).
amountDetails.amount: Set the value to the transaction amount.
amountDetails.currency: Set the value to the currency code.
amountDetails.cashbackAmount: Set the value to the cashback amount.

REST Example: Cashback

Request

{
      "type" : "PaymentRequest",
      "merchantReferenceCode" : "bd74d30930e349548fd9d125f88291bc",
      "amountDetails" : {
        "amount" : "20.00",
        "currency" : "GBP",
        "cashbackAmount" : "5.00"
      }
}

Mid-Transaction Status Updates

During the transaction, you might receive one or more update responses indicating the current status of the transaction. You can choose to display these updates on your point-of-sale (POS) system.

{
      "type": "TransactionStatusResponse",
      "message": "Status update to display.",
      "canBeAborted": true/false
}

Response to a Successful Request

{
  "type" : "PaymentResponse",
  "message" : "Payment approved",
  "transactionDetails" : {
    "id" : "218b28d38bf3424ab4ade95b9be1c75b",
    "merchantReferenceCode" : "bd74d30930e349548fd9d125f88291bc",
    "submitTimeUtc" : "2024-03-20T08:55:37+0000",
    "captured" : true,
    "amountDetails" : {
      "currency" : "GBP",
      "amount" : "20.00",
      "capturedAmount" : "25.00",
      "refundableAmount" : "20.00",
      "cashbackAmount" : "5.00"
    }
  },
  "processingDetails" : {
    "status" : "APPROVED",
    "verificationMethod" : "PIN",
    "entryMode" : "ICC",
    "card" : {
      "expirationMonth" : "12",
      "expirationYear" : "2025",
      "type" : "MASTERCARD",
      "maskedPan" : "541333XXXXXX0011",
      "countryCode" : "276"
    }
  },
  "additionalInformation" : {
    "instrumentId" : "7030000000232230011",
    "requestId" : "7109249459396751504008"
  },
  "linkedOperations" : [ ],
  "tipAdjustStatus" : "NOT_ADJUSTABLE",
  "receipts" : {
    "merchantReceipt" : {
      "preformattedReceipt" : "Merchant Receipt\nCP Test\nSample Street\nUB3 2EA London\nUnited Kingdom\n1234567\n\nCashback\n£25.00\nPurchase Amount: £20.00\nCashback: £5.00\nPlease retain receipt!\n\nCard: Payworks MASTER\nAccount: **** **** **** 0011\nEntry Mode: Chip\nAID: A0000000041010\nCard Number: 0\nVerification: PIN\n\nAuthorization: 002500\nMerchant ID: **37599\nTerminal ID: ****0063\n\n\n218b28d38bf3424ab4ade95b9be1c75b\n\n09:55:46: 20/03/2024\n\n\n",
      "receiptData" : {
        "lines" : {
          "MERCHANT_DETAILS_PUBLIC_NAME" : {
            "label" : "Name",
            "value" : "CP Test"
          },
          "MERCHANT_DETAILS_ADDRESS" : {
            "label" : "Address",
            "value" : "Sample Street"
          },
          "MERCHANT_DETAILS_ZIP" : {
            "label" : "Zip",
            "value" : "UB3 2EA"
          },
          "MERCHANT_DETAILS_CITY" : {
            "label" : "City",
            "value" : "London"
          },
          "MERCHANT_DETAILS_COUNTRY" : {
            "label" : "Country",
            "value" : "United Kingdom"
          },
          "MERCHANT_DETAILS_CONTACT" : {
            "label" : "Contact",
            "value" : "1234567"
          },
          "MERCHANT_DETAILS_ADDITIONAL_INFORMATION" : {
            "label" : "Additional Information",
            "value" : ""
          },
          "PAYMENT_DETAILS_SCHEME_OR_LABEL" : {
            "label" : "Card",
            "value" : "Payworks MASTER"
          },
          "PAYMENT_DETAILS_MASKED_ACCOUNT" : {
            "label" : "Account",
            "value" : "**** **** **** 0011"
          },
          "PAYMENT_DETAILS_EMV_APPLICATION_ID" : {
            "label" : "AID",
            "value" : "A0000000041010"
          },
          "PAYMENT_DETAILS_SOURCE" : {
            "label" : "Entry Mode",
            "value" : "Chip"
          },
          "PAYMENT_DETAILS_ACCOUNT_SEQUENCE_NUMBER" : {
            "label" : "Card Number",
            "value" : "0"
          },
          "PAYMENT_DETAILS_CUSTOMER_VERIFICATION" : {
            "label" : "Verification",
            "value" : "PIN"
          },
          "CLEARING_DETAILS_AUTHORIZATION_CODE" : {
            "label" : "Authorization",
            "value" : "002500"
          },
          "CLEARING_DETAILS_MERCHANT_IDENTIFIER" : {
            "label" : "Merchant ID",
            "value" : "**37599"
          },
          "CLEARING_DETAILS_TERMINAL_ID" : {
            "label" : "Terminal ID",
            "value" : "****0063"
          },
          "RECEIPT_TYPE" : {
            "label" : "Receipt Type",
            "value" : "Merchant Receipt"
          },
          "TRANSACTION_TYPE" : {
            "label" : "Type",
            "value" : "Cashback"
          },
          "SUBJECT" : {
            "label" : "Description",
            "value" : ""
          },
          "IDENTIFIER" : {
            "label" : "PWID",
            "value" : "218b28d38bf3424ab4ade95b9be1c75b"
          },
          "DATE" : {
            "label" : "Date",
            "value" : "20/03/2024"
          },
          "TIME" : {
            "label" : "Time",
            "value" : "09:55:46"
          },
          "STATUS_TEXT" : {
            "label" : "Information",
            "value" : "Please retain receipt!"
          }
        },
        "signatureLineRequired" : false,
        "tipLineRequired" : false,
        "totalLineRequired" : false
      }
    },
    "customerReceipt" : {
      "preformattedReceipt" : "Cardholder Receipt\nCP Test\nSample Street\nUB3 2EA London\nUnited Kingdom\n1234567\n\nCashback\n£25.00\nPurchase Amount: £20.00\nCashback: £5.00\nPlease retain receipt!\n\nCard: Payworks MASTER\nAccount: **** **** **** 0011\nEntry Mode: Chip\nAID: A0000000041010\nCard Number: 0\nVerification: PIN\n\nAuthorization: 002500\nMerchant ID: **37599\nTerminal ID: ****0063\n\n\n218b28d38bf3424ab4ade95b9be1c75b\n\n09:55:46: 20/03/2024\n\n\n",
      "receiptData" : {
        "lines" : {
          "MERCHANT_DETAILS_PUBLIC_NAME" : {
            "label" : "Name",
            "value" : "CP Test"
          },
          "MERCHANT_DETAILS_ADDRESS" : {
            "label" : "Address",
            "value" : "Sample Street"
          },
          "MERCHANT_DETAILS_ZIP" : {
            "label" : "Zip",
            "value" : "UB3 2EA"
          },
          "MERCHANT_DETAILS_CITY" : {
            "label" : "City",
            "value" : "London"
          },
          "MERCHANT_DETAILS_COUNTRY" : {
            "label" : "Country",
            "value" : "United Kingdom"
          },
          "MERCHANT_DETAILS_CONTACT" : {
            "label" : "Contact",
            "value" : "1234567"
          },
          "MERCHANT_DETAILS_ADDITIONAL_INFORMATION" : {
            "label" : "Additional Information",
            "value" : ""
          },
          "PAYMENT_DETAILS_SCHEME_OR_LABEL" : {
            "label" : "Card",
            "value" : "Payworks MASTER"
          },
          "PAYMENT_DETAILS_MASKED_ACCOUNT" : {
            "label" : "Account",
            "value" : "**** **** **** 0011"
          },
          "PAYMENT_DETAILS_EMV_APPLICATION_ID" : {
            "label" : "AID",
            "value" : "A0000000041010"
          },
          "PAYMENT_DETAILS_SOURCE" : {
            "label" : "Entry Mode",
            "value" : "Chip"
          },
          "PAYMENT_DETAILS_ACCOUNT_SEQUENCE_NUMBER" : {
            "label" : "Card Number",
            "value" : "0"
          },
          "PAYMENT_DETAILS_CUSTOMER_VERIFICATION" : {
            "label" : "Verification",
            "value" : "PIN"
          },
          "CLEARING_DETAILS_AUTHORIZATION_CODE" : {
            "label" : "Authorization",
            "value" : "002500"
          },
          "CLEARING_DETAILS_MERCHANT_IDENTIFIER" : {
            "label" : "Merchant ID",
            "value" : "**37599"
          },
          "CLEARING_DETAILS_TERMINAL_ID" : {
            "label" : "Terminal ID",
            "value" : "****0063"
          },
          "RECEIPT_TYPE" : {
            "label" : "Receipt Type",
            "value" : "Cardholder Receipt"
          },
          "TRANSACTION_TYPE" : {
            "label" : "Type",
            "value" : "Cashback"
          },
          "SUBJECT" : {
            "label" : "Description",
            "value" : ""
          },
          "IDENTIFIER" : {
            "label" : "PWID",
            "value" : "218b28d38bf3424ab4ade95b9be1c75b"
          },
          "DATE" : {
            "label" : "Date",
            "value" : "20/03/2024"
          },
          "TIME" : {
            "label" : "Time",
            "value" : "09:55:46"
          },
          "STATUS_TEXT" : {
            "label" : "Information",
            "value" : "Please retain receipt!"
          }
        },
        "signatureLineRequired" : false,
        "tipLineRequired" : false,
        "totalLineRequired" : false
      }
    }
  }
}

Response to an Unsuccessful Request

When the request is unsuccessful, you receive an error response with details.

{
      "type": "ErrorResponse",
      "message": "Error message to display.",
      "developerDescription": "Detailed description of error."
}