Hosted Payment Page (HPP)

Redirect customers seamlessly to Ecentric's secure environment to complete the payment process.

The Hosted Payment Page is called via a signed HTML form POST from a merchant website. Customers are then seamlessly redirected to a secure page with the merchants’ branding where they can enter their payment details. When the transaction has completed, the customer will be redirected back to the merchant website.

Implementation

Step 1: Generate transaction details

The following fields are required:

• MerchantID provided by Ecentric
• TransactionType
  • Once-off payments: should have one of the following: “Authorize”, “Payment” or “CardVerification”
  • Recurring Payments should have one of the options: “RecAuth”, “RecPayment” or “RecVoid”
• MerchantReference value generated by the merchant (usually the order number) and is required to be unique for each transaction as it will be used to identify customer transactions. The data type is ALPHANUMERIC, meaning it can only contain letters or numbers (or a combination of both) and must not contain any spaces or special characters. For references greater than 8 characters, the first 8 characters of the reference must be unique for each transaction. Example: Test1234
• Amount should be in cents without any decimal point. Example: 6500 (for R65.00)
• Currency value should be “ZAR”

There are also a number of optional fields that can be found in Hosted Data Fields.

For returning customers, use the following optional field:

• UserID: is a value generate by the merchant and is a unique reference to identify returning customers. The data type is ALPHANUMERIC only (no spaces or special characters). When a UserID is present, the Payment Page will present an option to save the card details for that particular customer, so that they do not have to enter the card details again when making a payment. The customer will only need to enter their CVV number when making a subsequent payment.

Step 2 : Generate signature

To ensure the authenticity and integrity of the data, generate a signature using a SHA-256 cryptographic hash function of the transaction details together with the secret key.

Use the following details when generating a SHA256 signature (also called a checksum):

• Secret Key provided by Ecentric
• MerchantID
• TransactionType
• Amount
• Currency
• MerchantReference

Use your preferred method to generate a SHA256 hash (please see our C# Example here).

📘

Important:

Calculate the hash value by concatenating the variables using pipe ('|' ) delimiters and then convert to upper case.

1. Signature elements to be used for processing once-off payments:
   (SecretKey|MerchantGUID|TransactionType|Amount|CurrencyCode|MerchantReference)

2. Signature elements to be used for processing payments for returning customers. The UserID should be included in the calculation:
   (SecretKey|MerchantGUID|TransactionType|Amount|CurrencyCode|MerchantReference|UserID)

Step 3: Call HPP

Send an HTML form POST with the transaction details (specified below) and signature to the endpoint URL:

• MerchantID
• TransactionType
• MerchantReference
• Amount
• Currency
• UserID (optional)
• ChecksumHash

Example:

<form action="https://sandbox.ecentric.co.za/hpp/" method="post">
 <input type="text" name="MerchantID" value="MerchantGUID">
 <input type="text" name="TransactionType" value="Payment">
 <input type="text" name="MerchantReference" value="Testing123">
 <input type="text" name="Amount" value="6500">
 <input type="text" name="Currency" value="ZAR">
 <input type="text" name="Checksum" value="CHECKSUM">
 <button type="submit" onclick="form[0].submit()">submit</button>
<form>

Step 4: Process the response

The Gateway will return an HTML form POST with the response back to the Success or Failure URLs that were provided by the merchant. The expected successful and failure transaction response fields are listed below. (See Hosted Data Fields for further details regarding each field).

The response will include a checksum value generated by Ecentric using the calculation elements below. It is recommended that merchants implement their own checksum calculation and compare it to the value received in order to verify that the response data originated from Ecentric and has not been tampered with.

Signature elements to be used to calculate the checksum in the response:
(SecretKey|TransctionID|MerchantReference|Result|FailureMessage|Amount)

Successful Transaction Result:

Field	Description
MerchantReference	Generated by the merchant and sent in the request (usually the order number)
Result	Result will be "Success" for successful transactions
FailureMessage	This will be the failure message if an error occurs. Result will be "Success" if no error occurred
Checksum	Generated by Ecentric using the elements in the response as described above
TransactionID	Generated by Ecentric for the transaction response
Amount	The transaction amount
TransactionDetails	An array containing the tender details
MerchantID	Sent by the merchant in the request transaction
Currency	Currency will be "ZAR" as sent in the request
Token	Generated by Ecentric and ONLY returned in transaction responses where a saved card is used. Otherwise the value returned is "null"
AuthCode	ONLY returned in responses where a saved card was used. Otherwise value returned is "null"

TransactionDetails

Fields	Description
Amount	Amount paid in cents
PaymentService	Generated by Ecentric and will contain “CardNotPresent” for card payments (see Payment service for more details)
ResponseDetail	Object containing message response details (see Response Codes for details on the values below)
TransactionID	Generated by Ecentric for the payment
TransactionStatus	The value will be "Success" for a successful transaction

ResponseDetail

Field	Description
Source	The source will be "Acquirer" for all Card Payments responses from the Bank
Code	The code will be "00" for a Successful transaction
Description	The description will be "Approved or completed successfully" for a successful tender transaction
ClientMesage	The value will be "Approved" for a Successful tender transaction

Failed Transaction Result:

• MerchantReference: generated by the merchant and sent in the request (usually the order number)
• Result: generated by Ecentric and will be "Failure" for failed responses
• FailureMessage: generated by Ecentric describing the error that occurred
• Checksum: generated by Ecentric
• TransactionID: generated by Ecentric for the transaction response
• SessionID: generated by Ecentric for the transaction response
• Amount: value will be "0" if an error occurred
• MerchantID: sent by merchant in the request transaction
• Currency: sent by merchant in the request
• Token: generated by Ecentric and ONLY returned in transaction responses where a saved card is used. Otherwise the value returned is "null"
• AuthCode: ONLY returned in responses where a saved card was used. Otherwise value returned is "null"
• TransactionDetails: empty array generated by Ecentric

OPTIONAL Step 5: Receive notifications

The Transaction Notification Service (previously known as a Payment Advice) is a webhook that provides the outcome of each transaction. See Transaction Notification Service for more information.