REST Example: Processing a Tip Adjust

Endpoints

Generate a bearer token before sending each request. For more information, see Generating a Bearer Token for Authentication.

Test:

POST https://terminalstest.cybersource.com/v1/cloud/transactions

Production:

POST https://terminals.cybersource.com/v1/cloud/transactions

Request

{
    "serialNumber": "1850000000",
    "request": {
      "type" : "TipAdjustRequest",
      "transactionId" : "c6174c80b81f4413a4b9f2065c5431c7",
      "amountDetails" : {
        "amount" : "4.00",
        "currency" : "USD"
      }
   }
}

Response to a Successful Request

The response includes the data that is required to generate and print a receipt. The receipt data is located in the receipts section of the response and contains a pre-formatted, compliant receipt that is ready to use. The receipt data also includes the individual receipt line items that are required to build your own receipt. Find merchant- and customer-specific data here:

Merchant-specific receipt data is located under

merchantReceipt

Customer-specific receipt data is located under

customerReceipt

{
  "type" : "TipAdjustResponse",
  "message" : "Payment approved",
  "transactionDetails" : {
    "id" : "c6174c80b81f4413a4b9f2065c5431c7",
    "merchantReferenceCode" : "1ce594be142142f4913cca805830a176",
    "submitTimeUtc" : "2024-03-20T09:19:41+0000",
    "captured" : true,
    "amountDetails" : {
      "currency" : "USD",
      "amount" : "24.00",
      "capturedAmount" : "24.00",
      "refundableAmount" : "24.00",
      "includedTipAmount" : "4.00"
    }
  },
  "processingDetails" : {
    "status" : "APPROVED",
    "verificationMethod" : "NONE",
    "entryMode" : "NFC_ICC",
    "card" : {
      "expirationMonth" : "12",
      "expirationYear" : "2025",
      "type" : "VISA",
      "maskedPan" : "476173XXXXXX0119",
      "countryCode" : "840"
    }
  },
  "additionalInformation" : {
    "instrumentId" : "7030000000022690119",
    "requestId" : "7109265975966653104007"
  },
  "linkedOperations" : [ ],
  "tipAdjustStatus" : "ADJUSTED",
  "receipts" : {
    "merchantReceipt" : {
      "preformattedReceipt" : "Merchant Receipt\nCP Test\nSample Street\n55555 New York\nUnited States\n1234567\n\nCapture\nPurchase Amount: $20.00\nTip Amount: $4.00\nTotal Amount: $24.00\nPlease retain receipt!\n\nCard: Payworks VISA\nAccount: **** **** **** 0119\nEntry Mode: Contactless\nAID: A0000000031010\nVerification: None\n\nAuthorization: 002000\nMerchant ID: **37599\nTerminal ID: ****7478\n\n\nc6174c80b81f4413a4b9f2065c5431c7\n\n10:23:17: 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" : "55555"
          },
          "MERCHANT_DETAILS_CITY" : {
            "label" : "City",
            "value" : "New York"
          },
          "MERCHANT_DETAILS_COUNTRY" : {
            "label" : "Country",
            "value" : "United States"
          },
          "MERCHANT_DETAILS_CONTACT" : {
            "label" : "Contact",
            "value" : "1234567"
          },
          "MERCHANT_DETAILS_ADDITIONAL_INFORMATION" : {
            "label" : "Additional Information",
            "value" : ""
          },
          "PAYMENT_DETAILS_SCHEME_OR_LABEL" : {
            "label" : "Card",
            "value" : "Payworks VISA"
          },
          "PAYMENT_DETAILS_MASKED_ACCOUNT" : {
            "label" : "Account",
            "value" : "**** **** **** 0119"
          },
          "PAYMENT_DETAILS_EMV_APPLICATION_ID" : {
            "label" : "AID",
            "value" : "A0000000031010"
          },
          "PAYMENT_DETAILS_SOURCE" : {
            "label" : "Entry Mode",
            "value" : "Contactless"
          },
          "PAYMENT_DETAILS_CUSTOMER_VERIFICATION" : {
            "label" : "Verification",
            "value" : "None"
          },
          "CLEARING_DETAILS_AUTHORIZATION_CODE" : {
            "label" : "Authorization",
            "value" : "002000"
          },
          "CLEARING_DETAILS_MERCHANT_IDENTIFIER" : {
            "label" : "Merchant ID",
            "value" : "**37599"
          },
          "CLEARING_DETAILS_TERMINAL_ID" : {
            "label" : "Terminal ID",
            "value" : "****7478"
          },
          "RECEIPT_TYPE" : {
            "label" : "Receipt Type",
            "value" : "Merchant Receipt"
          },
          "TRANSACTION_TYPE" : {
            "label" : "Type",
            "value" : "Capture"
          },
          "SUBJECT" : {
            "label" : "Description",
            "value" : ""
          },
          "IDENTIFIER" : {
            "label" : "PWID",
            "value" : "c6174c80b81f4413a4b9f2065c5431c7"
          },
          "AMOUNT_AND_CURRENCY" : {
            "label" : "Amount",
            "value" : "$24.00"
          },
          "DATE" : {
            "label" : "Date",
            "value" : "20/03/2024"
          },
          "TIME" : {
            "label" : "Time",
            "value" : "10:23:17"
          },
          "STATUS_TEXT" : {
            "label" : "Information",
            "value" : "Please retain receipt!"
          }
        },
        "signatureLineRequired" : false,
        "tipLineRequired" : false,
        "totalLineRequired" : false
      }
    },
    "customerReceipt" : {
      "preformattedReceipt" : "Cardholder Receipt\nCP Test\nSample Street\n55555 New York\nUnited States\n1234567\n\nCapture\nPurchase Amount: $20.00\nTip Amount: $4.00\nTotal Amount: $24.00\nPlease retain receipt!\n\nCard: Payworks VISA\nAccount: **** **** **** 0119\nEntry Mode: Contactless\nAID: A0000000031010\nVerification: None\n\nAuthorization: 002000\nMerchant ID: **37599\nTerminal ID: ****7478\n\n\nc6174c80b81f4413a4b9f2065c5431c7\n\n10:23:17: 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" : "55555"
          },
          "MERCHANT_DETAILS_CITY" : {
            "label" : "City",
            "value" : "New York"
          },
          "MERCHANT_DETAILS_COUNTRY" : {
            "label" : "Country",
            "value" : "United States"
          },
          "MERCHANT_DETAILS_CONTACT" : {
            "label" : "Contact",
            "value" : "1234567"
          },
          "MERCHANT_DETAILS_ADDITIONAL_INFORMATION" : {
            "label" : "Additional Information",
            "value" : ""
          },
          "PAYMENT_DETAILS_SCHEME_OR_LABEL" : {
            "label" : "Card",
            "value" : "Payworks VISA"
          },
          "PAYMENT_DETAILS_MASKED_ACCOUNT" : {
            "label" : "Account",
            "value" : "**** **** **** 0119"
          },
          "PAYMENT_DETAILS_EMV_APPLICATION_ID" : {
            "label" : "AID",
            "value" : "A0000000031010"
          },
          "PAYMENT_DETAILS_SOURCE" : {
            "label" : "Entry Mode",
            "value" : "Contactless"
          },
          "PAYMENT_DETAILS_CUSTOMER_VERIFICATION" : {
            "label" : "Verification",
            "value" : "None"
          },
          "CLEARING_DETAILS_AUTHORIZATION_CODE" : {
            "label" : "Authorization",
            "value" : "002000"
          },
          "CLEARING_DETAILS_MERCHANT_IDENTIFIER" : {
            "label" : "Merchant ID",
            "value" : "**37599"
          },
          "CLEARING_DETAILS_TERMINAL_ID" : {
            "label" : "Terminal ID",
            "value" : "****7478"
          },
          "RECEIPT_TYPE" : {
            "label" : "Receipt Type",
            "value" : "Cardholder Receipt"
          },
          "TRANSACTION_TYPE" : {
            "label" : "Type",
            "value" : "Capture"
          },
          "SUBJECT" : {
            "label" : "Description",
            "value" : ""
          },
          "IDENTIFIER" : {
            "label" : "PWID",
            "value" : "c6174c80b81f4413a4b9f2065c5431c7"
          },
          "AMOUNT_AND_CURRENCY" : {
            "label" : "Amount",
            "value" : "$24.00"
          },
          "DATE" : {
            "label" : "Date",
            "value" : "20/03/2024"
          },
          "TIME" : {
            "label" : "Time",
            "value" : "10:23:17"
          },
          "STATUS_TEXT" : {
            "label" : "Information",
            "value" : "Please retain receipt!"
          }
        },
        "signatureLineRequired" : false,
        "tipLineRequired" : false,
        "totalLineRequired" : false
      }
    }
  }
}

Response to an Unsuccessful Request

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

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