Clearent Hosted Payment Page

Documentation and examples

Overview Security Considerations Configuration Styling / Branding Examples

Security Requirements

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.

{ "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.

{ "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.

{ "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.

{ "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.

{ "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.

{ "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.

<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

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.

<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>

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:

Validating expiration date

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

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