Documentation
WebsiteHelp

Lightbox

The Payment Lightbox displays a popup for customer payment from the merchant’s website.

Suggest Edits

Lightbox uses a Javascript method call to display a payment popup where customers can enter their payment details. When the transaction has completed, the customer will be returned 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 Payment 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 Lightbox

  1. Create a variable object and populate with the transaction details and signature:
  • MerchantID
  • TransactionType
  • MerchantReference
  • Amount
  • Currency
  • UserID (optional)
  • ChecksumHash
  1. Implement the JavaScript payment method call.
    • The following tag needs to be included on the merchant's website page that will be requesting the payment:
      <script type="text/javascript" src="https://sandbox.ecentric.co.za/HPP/API/js"></script>
    • Use the following method call in order to open the Payment Lightbox:
      window.hpp.payment(object, successCallbackFn, failureCallbackFn)
  2. The object values are specified in the Hosted Payment Data fields page.

Step 4: Process the response

When payment is complete, the Lightbox will close and post a message back to the call back functions based on the object result “Success” or “Failure”.

The expected successful and failure transaction response fields are listed below. (See Hosted Payment 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:

  • MerchantReference: generated by the merchant and sent in the request (usually the order number)
  • Result: generated by Ecentric and will be "Success"
  • FailureMessage: generated by Ecentric if an error occurs. Result will be "Success" if no error occurred
  • Checksum: generated by Ecentric
  • TransactionID: generated by Ecentric for the transaction response
  • Amount: generated by the Merchant and sent in the request
  • TransactionDetails: an array containing the tender details
    • 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)
      • Source: value will be "Acquirer" for all Card Payments responses from the Bank
      • Code: value will be "00" for a Successful transaction
      • Description: value will be "Approved or completed successfully" for a successful tender transaction
      • ClientMesage: value will be "Approved. " for a Successful tender transaction
    • TransactionID: generated by Ecentric for the payment
    • TransactionStatus: value will be "Success" for a successful transaction
  • 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"

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 of the outcome of each transaction. See Transaction Notification Service for more information.

Updated about 2 months ago