Security Considerations

Security Requirements

  • Your website must use HTTPS.
  • Do not publish your public Key outside of your code.
  • Payments on the hosted payment button will only work on the website you registered when onboarding to a Hosted Payment Account.

Transaction Responses

The HPP application returns all responses as raw strings and as JSON formatted representations of the raw server responses. These raw transaction responses are signed by Clearent and the can be verified (see “Response Validation” section below). Below are examples of the various types of responses you will see from the HPP application.

Successful Transaction

Below is an example of a successful response from a basic sale example.

Successful Transaction With Billing Address Supplied

Below is an example of a successful response from a sale example that includes billing address.

See Configuration for more information and Examples for examples using billing address options.

Failed Transaction

Below is an example of a failed transaction response.

Unauthorized Request (No Transaction Attempted)

If an invalid, disabled, or expired key is used, not transaction is attempted and the error response will not include transaction data.

Successful Sale With Token

Below is an example of a successful response from a sale with the option to save the card for future use selected.

See Configuration for more information and Examples for examples of saving cards for future use.

Successful Token Request

Below is an example of a successful response from a token-only request.

See Configuration for more information and Examples for examples using a token-only request.

Response Validation

Successful Transactions

After each transaction request, the browser will receive a response from the Clearent transaction processing portal. If the transaction request was successful, the application looks for a callback function named “ClearentOnSuccess” and if found, calls this function. The function receives two parameters, the raw, signed response from the server (see “Clearent Hosted Payment Page Verification” below) and a JSON object representation of the the raw response. In the example below, we created a function to log the raw response, the JSON-formatted response, and the transaction id to the browser’s developer console.

You will pass this raw response to your server side solution to complete the transaction. Because the response comes from Clearent to the client-browser and then up to your server, you cannot trust that the response has not been tampered with. Never trust client-side data!

There are multiple ways to validate the response from the browser to insure that the response has not been tampered with and that you have indeed charged and received the expected amount from the client

  • The response will contain a hash signature that can be used to validate the response. The hash is made up of the response object. You can validate the signature on your server to validate the response parameters were not tampered with. This is imperative to your ensuring your transaction is valid. Make sure the response is valid AND that the transaction Id is unique. Clearent Hosted Payment Page Verification
  • You can use our API to do a GET with the transaction ID to ensure the response matches what the client side passed you. Each transaction ID is unique so once you have accepted a transaction ID for payment, you should never see the same transaction ID again.
  • You can validate the transactions manually using the Virtual Terminal. Again, you can search by transaction ID to validate the transaction details.

Failed Transactions

If the transaction was not successful, the browser will receive a response from the Clearent transaction processing portal containing an error message. The user will see a generic error message: “We were unable to process your payment. Please verify your card details and try again or contact us to complete your order.” This error message can be configured with different text if necessary.

For failed transactions, the application looks for a callback function named “ClearentOnError” and if found, calls this function. This function also receives the same two parameters as the ClearentOnSuccess function; the raw, signed response from the server (see “Clearent Hosted Payment Page Verification” below) and a JSON object representation of the the raw response.

In the example below, we created a function to log the raw response, the JSON-formatted response, the error-message (if present) and the transaction id (if present) to the browser’s developer console.

Upon examining the response from a failed transaction, you will notice the error messages in the response objects are intentionally vague. This is done to prevent scammers from using the service to test cards and security codes. If the card is invalid, or expiration invalid, or security code invalid, the response will simply contain, a generic message. You can use the transaction id to look up the transaction details in Virtual Terminal to examine the transaction in more detail.

The response will not contain transaction information if a transaction was not attempted. Possible reasons for non-attempted transactions are invalid or expired public key, or unrecoverable server error.

Browser Support

Clearent’s Hosted Payments Page solution will work with Chrome, Firefox, Safari, Edge, and IE11. It has been designed to work on desktops, notebooks, tablets, and mobile devices.

Troubleshooting

Error messages for this solution are very generic for security purposes as these errors are presented directly to the end user. Please make sure you log the exchange ID from the failed response and provide that to Clearent if you have questions about any errors you receive.

Example:

“exchange-id”:”ID-5ba9fd2f10ea-59988-1441133412260-0-1343″

Client Side CC Validation

In accordance with best security practices, all client data is validated on Clearent servers. We do perform basic client-side validation to improve the user-experience and reduce errors.

Validating card field

Credit card numbers are validated on the client as follows:

  • Get card token or card field value (remove any non-numeric characters)
  • Remaining digits must pass Luhn algorithm. This does not guarantee that the card is valid, simply that the card could be a valid card. This is done to help prevent typing errors.

Validating expiration date

Expiration date is required for all transactions unless the merchant is storing and presenting card tokens to the user

  • If card token is used, ignore this check
  • Get expiration date field (remove any non-numeric characters)
  • Entered value must be four digits, 2-digit month and 2-digit year (MMYY)
  • Entered year must be > current year OR (entered year must be >= current year AND entered month must be >= current month)

Validating CVC

By default, the card security code (CSC, CID, CVC, CVV, CVV2) is required for all transactions unless the merchant is storing and presenting card tokens to the user

  • If card token is used, ignore this check
  • Get CVC field (remove any non-numeric characters)
  • If card is Visa, MasterCard, Discover, Diner’s Club or JCB then the security code must be 3 digits
  • If card is American Express then security code must be 4 digits