Security Requirements
- Your website must use HTTPS.
- Do not publish your public Key outside of your code.
- For payments on the hosted payment button will only work on the website you registered when onboarding to a Hosted Payment Account.
Browser Support
Clearent’s Hosted Payments Page solution will work with
- Chrome
- Firefox
- Edge
- Safari
Ending Support For IE 11 Browser and Legacy Edge
On August 17, 2020
Microsoft announced that they would be ending support for IE 11 or legacy Edge in Microsoft Teams and M365. We believe that focusing on modern browsers that
provide a faster, more secure, more robust browsing experience is the right decision.
Beginning July 1st, 2021, we will no longer be providing coding shims (polyfills) for missing functionality in IE 11 or legacy Edge. Please note, legacy Edge refers to the
older pre-Chromium Edge browser released prior to January 2020. Modern Edge browser is supported.
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.
<![CDATA[
{
"code":"200",
"status":"success",
"exchange-id":"ID-CLADEVGSOPS02-cgw01-58790-1447188033740-0-1146",
"links":[
{
"rel":"transaction",
"href":"/rest/v2/transactions?id=1107313",
"id":"1107313"
}
],
"payload":{
"transaction":{
"amount":"3.33",
"id":"1107313",
"type":"SALE",
"result":"APPROVED",
"card":"XXXXXXXXXXXX1111",
"csc":"999",
"authorization-code":"TAS425",
"batch-string-id":"165",
"display-message":"Transaction approved",
"result-code":"000",
"exp-date":"1020"
},
"payloadType":"transaction"
},
"signature":"30640230679d69790f582c7bb22920eb0541cc84a37f3aa6dcd"
}
]]>
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.
<![CDATA[
{
"code":"200",
"status":"success",
"exchange-id":"ID-CLADEVGSOPS02-cgw01-58790-1447188033740-0-1730",
"links":[
{
"rel":"transaction",
"href":"/rest/v2/transactions?id=1107328",
"id":"1107328"
}
],
"payload":{
"transaction":{
"amount":"3.33",
"id":"1107328",
"type":"SALE",
"result":"APPROVED",
"billing":{
"street":"333 Oak Trail",
"city":"Springfield",
"state":"ME",
"zip":"55105",
"first-name":"Joe",
"last-name":"Burns"
},
"card":"XXXXXXXXXXXX1111",
"csc":"999",
"authorization-code":"TAS902",
"avs-result-code":"Y",
"batch-string-id":"166",
"display-message":"Transaction approved",
"result-code":"000",
"exp-date":"1019"
},
"payloadType":"transaction"
},
"signature":"3064dcb5feaffadfc237835272c7685"
}
]]>
Failed Transaction
Below is an example of a failed transaction response.
<![CDATA[
{
"code":"402",
"status":"fail",
"exchange-id":"ID-CLADEVGSOPS02-cgw01-58790-1447188033740-0-1169",
"links":[
{
"rel":"transaction",
"href":"/rest/v2/transactions?id=1107315",
"id":"1107315"
}
],
"payload":{
"transaction":{
"amount":"3.33",
"id":"1107315",
"type":"SALE",
"result":"INVALID_REQUEST",
"card":"XXXXXXXXXXXX1111",
"csc":"666",
"display-message":"Declined by Issuer - Invalid card security code",
"result-code":"018",
"exp-date":"1020"
},
"error":{
"error-message":"INVALID_REQUESTSYSTEM_ERROR_OTHER HPP Request",
"result-code":"073"
},
"payloadType":"error"
},
"signature":"306402b09b373a84edbb935ed11a6849a6711ba4c16abe1338dd6f"
}
]]>
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.
<![CDATA[
{
"code":"401",
"status":"fail",
"payload":{
"error":{
"error-message":"UNAUTHORIZED",
"result-code":"042",
"time-stamp":"Tue Nov 10 21:24:04 UTC 2015"
},
"payloadType":"error"
}
}
]]>
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.
<![CDATA[
{
"code":"200",
"status":"success",
"exchange-id":"ID-CLADEVGSOPS02-cgw01-58790-1447188033740-0-1125",
"links":[
{
"rel":"transaction",
"href":"/rest/v2/transactions?id=1107310",
"id":"1107310"
},
{
"rel":"token",
"href":"/rest/v2/tokens/1100845274213121111",
"id":"1136587273219921111"
}
],
"payload":{
"transaction":{
"amount":"64.50",
"id":"1107310",
"type":"SALE",
"result":"APPROVED",
"billing":{
"street":"222 Main Street",
"city":"Springfield",
"state":"ME",
"zip":"55105",
"first-name":"John",
"last-name":"Adams"
},
"card":"XXXXXXXXXXXX1111",
"csc":"999",
"authorization-code":"TAS403",
"avs-result-code":"Y",
"batch-string-id":"165",
"display-message":"Transaction approved",
"result-code":"000",
"exp-date":"1019"
},
"payloadType":"transaction"
},
"signature":"306502310087aaee89b8c706ceb98c986b4de66a5"
}
]]>
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.
<![CDATA[
{
"code":"200",
"status":"success",
"exchange-id":"ID-CLADEVGSOPS02-cvl01-59475-1447185739748-0-163",
"payload":{
"tokenResponse":{
"created":"2015-11-10T21:03:20.518Z",
"token-id":"1145845280641111111",
"times-used":"0",
"status":"Active",
"last-four-digits":"1111",
"card-type":"VISA",
"description":"Travel Visa",
"avs-address":"123 Maple Lane",
"avs-zip":"55105",
"avs-result-code":"Y"
},
"payloadType":"token"
}
}
]]>
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.
<![CDATA[
<script>
// called after successful complete
function ClearentOnSuccess(responseRaw,ResponseJSON){
console.log("transaction successful");
console.log(responseRaw);
console.log(ResponseJSON);
// use JS short-circuiting to determine if we have a transaction id
if(ResponseJSON.payload && ResponseJSON.payload.transaction && ResponseJSON.payload.transaction.id){
console.log("transaction id = " + ResponseJSON.payload.transaction.id);
}else{
console.log("transaction id not found");
}
}
</script>
]]>
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.
<![CDATA[
<script>
// called after failed complete
function ClearentOnError(responseRaw,ResponseJSON){
console.log("transaction failed");
console.log(responseRaw);
console.log(ResponseJSON);
// use JS short-circuiting to determine if we have an error message
if(ResponseJSON.payload && ResponseJSON.payload.error && ResponseJSON.payload.error['error-message']){
console.log("error = " + ResponseJSON.payload.error['error-message']);
}else{
console.log("unable to determine error");
}
// use JS short-circuiting to determine if we have a transaction id
if(ResponseJSON.payload && ResponseJSON.payload.transaction && ResponseJSON.payload.transaction.id){
console.log("transaction id = " + ResponseJSON.payload.transaction.id);
}else{
console.log("transaction id not found");
}
}
</script>
]]>
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:
<![CDATA["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