Documentation
WebsiteHelp

Hosted Data Fields

Suggest Edits

Data Fields for a payment

 

The list below details the required and optional fields, that must be populated and passed to Ecentric in order to access the payment page.

 

Required Fields

Field Name

Format

Description

MerchantID

GUID

A merchant ID will be provided by Ecentric Payment Systems (i.e. 5285C2C3-8B50-47F1-BCE7-10ECE659A7F2).

 

N.B. This field will be supplied in uppercase and should remain in uppercase. Changing the case of the Merchant ID will negatively affect the generation of the checksum.

TransactionType

string

Either the word “Payment” or “Authorize” or "CardVerification"

Amount

integer

The total amount to be paid in cents. (i.e. R20.95 will be 2095)

Currency

string

The ISO 4217 alpha currency code (i.e. ZAR). Only ZAR is supported.

MerchantReference

string

This field is also referred to as the Order Number.

 

This field is client generated.

 

The Order Number should be ALPHANUMERIC and should not contain any special characters, just letters and/or numbers [a...z], [A...Z], [0...9]

 

Maximum of 50 characters are allowed.

 

We will pass this value back to the response page unaltered (e.g. Order2123).

 

For Card Not Present (CNP) transactions:

  • The first 12 characters of this field will be sent to the acquirer/bank as the Retrieval Reference Number (RRN). Only a maximum of 12 characters are sent due an acquirer/bank limitation to support more characters for this field.
  • The first 12 characters should be unique as duplicate RRN’s may cause a transaction to fail acquirer/bank validation. Merchants need to ensure that they do not resend the same merchant reference through to Ecentric if the user initiates the payment (after adding items to a shopping cart), cancels, and then goes to pay again.
  • Settlement rules taken into account more fields than only the RRN and hence transactions with merchant references longer than 12 characters may still be settled.
  • The bank mark-off file showing settled transactions will show the 12 character RRN and not the merchant reference. Hence if required, other fields need to be used to reconcile the RRN to the merchant reference.

 

For MasterPass transactions:

The bank mark-off file showing settled transactions will show the RRN generated from MasterPass. Hence if required, other fields need to be used to reconcile the RRN to the merchant reference.

UserID

string

Unique key generated by Merchant for each user.

Optional field.

If wallet used then pass UserID else don’t add to checksum.

Checksum

string

A SHA256 hash, calculated by combining all required fields (pipe-delimited “|”) and the key provided by Ecentric Payment Systems.

 

This ensures that the data has not been tampered with.

 

N.B. the hash calculation needs to be uppercased after the hashing has been completed.

 

Request with no wallet example

Key|MerchantID|TransactionType|Amount|Currency|MerchantReference

is

SecretKey|5285C2C3-8B50-47F1-BCE7-10ECE659A7F2|Payment|2095|ZAR|Order2123, which generates “C5E865E3B077D88C674C18C8037AA4E925E55138E0C81B08176F3EC0B625428B”.

 


Request example with no wallet example

 <form action="https://sandbox.ecentric.co.za/HPP" method="POST" >
   <input type="hidden" name="MerchantID" value="C1381D37-7191-4815-B92E-519933174972">
   <input type="hidden" name="TransactionType" value="Payment">
   <input type="hidden" name="MerchantReference" value="Ord31242">
   <input type="hidden" name="Amount" value="2095">
   <input type="hidden" name="Currency" value="ZAR">
   <input type="hidden" name="Checksum" value="60D7C8D6144886AC9D6F38EAD0ECA380">
 </form>

Optional Fields

Field Name

Format

Description

Channel

string

Identifies the source of the call. For merchants who have multiple websites, this can be used to identify the originating site, i.e. “Website1”. This field will be used for reporting.

AccountNumberPaid

string

For merchant use - to display to customer  (i.e.ACC123456)

ItemQty

integer

For merchant use - to display to customer. Comma delimited (i.e. 1,2,3)

ItemDescription

string

For merchant use - to display to customer. Comma delimited (i.e. Widgets 1,Widgets 2,Widgets 3)

ItemAmount

string

For merchant use - to display to customer. Comma delimited (i.e. 2095,1295,1555)

ShippingCost

integer

For merchant use - to display to customer (i.e. 195)

Discount

integer

For merchant use - to display to customer (i.e. 0)

Tax

integer

For merchant use - to display to customer (i.e. 595)

RecipientEmail

string

Customer email address for Ecentric payment receipt

RecipientFirstName

string

For merchant use - to display to customer (i.e. John)

RecipientLastName

string

For merchant use - to display to customer (i.e. Doe)

BillingAddress1

string

For merchant use - to display to customer (i.e. Ecentric)

BillingAddress2

string

For merchant use - to display to customer (i.e. 240 Main Road)

BillingCity

string

For merchant use - to display to customer (i.e. Cape Town)

BillingSuburb

string

For merchant use - to display to customer (i.e. Rondebosch)

BillingPostcode

string

For merchant use - to display to customer (i.e. 7700)

BillingRegion

string

For merchant use - to display to customer (i.e. Western Cape)

BillingCountryCode

string

The country numeric code according to the ISO 3166-1 standard

(CountryCode = 710 for South Africa)

MerchantAddressLine1

string

Business address line 1. For aggregators this will contain the address of the sub merchant

MerchantPostCode

string

Business post code. For aggregators this will contain the postal code of the sub merchant

ShippingAddress1

string

For merchant use - to display to customer (i.e. Ecentric)

ShippingAddress2

string

For merchant use - to display to customer (i.e. 240 Main Road)

ShippingCity

string

For merchant use - to display to customer (i.e. Cape Town)

ShippingSuburb

string

For merchant use - to display to customer (i.e. Rondebosch)

ShippingPostcode

string

For merchant use - to display to customer (i.e. 7700)

ShippingRegion

string

For merchant use - to display to customer (i.e. Western Cape)

ShippingCountryCode

string

The country numeric code according to the ISO 3166-1 standard

(CountryCode = 710 for South Africa)

TrialSubscription

nullable boolean

This is used when a merchant is offering Trial Subscriptions. Valid values are "true" or "false"

cardAcceptorTerminalId

string

Used to identify a terminal

MerchantCategoryCode

integer

Used to pass a merchant specific MerchantCategoryCode (MCC). (i.e 1234)

CardonFileScenario

string

An identifier allowing a merchant to indicate which specific CIT (customer initiated) or MIT (merchant initiated) transaction is being performed

MerchantURL

string

This is the website address of the sub merchant. Applicable to aggregators. Max length is 255 characters

MerchantCountryCode

integer

The country numeric code according to the ISO 3166-1 standard

(CountryCode = 710 for South Africa)
MerchantPhone string The phone number of the sub merchant. Applicable to aggregators. Max length 16 characters
SubMerchantID string This is the unique ID of the sub merchant. Only applicable to aggregators. Max length is 15 characters
VerificationAction VerificationActionType The VerificationAction to be applied to the card. If left blank when the TransactionType is CardVerification, it will default to NonPaymentAuthentication. The amount used will be R0 (Zero Rand).


Request example with optional parameters

 <form action="https://sandbox.ecentric.co.za/HPP" method="POST" >
   <input type="hidden" name="MerchantID" value="C1381D37-7191-4815-B92E-519933174972">
   <input type="hidden" name="TransactionType" value="Payment">
   <input type="hidden" name="MerchantReference" value="Ord31243">
   <input type="hidden" name="Amount" value="2095">
   <input type="hidden" name="Currency" value="ZAR">
   <input type="hidden" name="ItemQty" value="1">
   <input type="hidden" name="ItemDescription" value="Widgets 1">
   <input type="hidden" name="ItemAmount" value="2095">
   <input type="hidden" name="MerchantCategoryCode" value="5399">
   <input type="hidden" name="Checksum" value="EC678EED5040471F7BE94FE582A34F1D">
 </form>

Return Fields

Field Name

Format

Description

TransactionID

GUID

The unique transaction ID generated by the gateway for this transaction.

This field would be blank if one of the following application level failure messages should occur:

  • Transaction cancelled;
  • General error occurred; or
  • Session timed out.

MerchantReference

string

This field is also referred to as the Order Number.

 

This field is client generated.

 

Maximum of 50 characters are allowed.

 

We will pass this value back to the response page unaltered (e.g. Order2123).

 

For Card Not Present (CNP) transactions:

  • The first 12 characters of this field will be sent to the acquirer/bank as the Retrieval Reference Number (RRN). Only a maximum of 12 characters are sent due an acquirer/bank limitation to support more characters for this field.
  • The first 12 characters should be unique as duplicate RRN’s may cause a transaction to fail acquirer/bank validation. Merchants need to ensure that they do not resend the same merchant reference through to Ecentric if the user initiates the payment (after adding items to a shopping cart), cancels, and then goes to pay again.
  • Settlement rules taken into account more fields than only the RRN and hence transactions with merchant references longer than 12 characters may still be settled.
  • The bank mark-off file showing settled transactions will show the 12 character RRN and not the merchant reference. Hence if required, other fields need to be used to reconcile the RRN to the merchant reference.

For MasterPass transactions:

The bank mark-off file showing settled transactions will show the RRN generated from MasterPass. Hence if required, other fields need to be used to reconcile the RRN to the merchant reference.

Result

string

This field will read contain either “Success” or “Failure”

Example Response

Success

<form action=" http://www.mycompany.co.za/success.aspx" method="POST" >

<input type="hidden" name="MerchantReference" value="Ord31244">

<input type="hidden" name="Result" value="Success">

<input type="hidden" name="FailureMessage" value="">

<input type="hidden" name="Checksum" value="4DE750A775FA63DC76BD9ACBD64065C8">

<input type="hidden" name="TransactionID" value="6297E2D7-705A-4FD1-876C-084AB58B7F48">

<input type="hidden" name="Amount" value="2095">

</form>

Failure

<form action=" http://www.mycompany.co.za/failure.aspx" method="POST" >

<input type="hidden" name="MerchantReference" value="Ord31245">

<input type="hidden" name="Result" value=" Failure">

<input type="hidden" name="FailureMessage" value="Bank declined transaction.">

<input type="hidden" name="Checksum" value=" 747DF62AA150D450BA4BBD05D3A3C76D">

<input type="hidden" name="TransactionID" value="6297E2D7-705A-4FD1-876C-084AB58B7F49">

<input type="hidden" name="Amount" value="0">

</form>

FailureMessage

string

If there was an error during processing, this field will contain the error description.

Amount

integer

The total amount to be paid in cents. (e.g. R20.95 will be 2095). This value will be 0 if failure message.

Checksum

string

A SHA256 hash, calculated by combining all fields (pipe-delimited “|”) and the key provided by Ecentric Payment Systems. (i.e. Key|TransactionID|MerchantReference |Result|FailureMessage|Amount

is

SecretKey|C1381D37-7191-4815-B92E-519933174972|Order2123|Success|12300

, which generates “5B0C47339BD2C5B43DE5496E3C8304B8C2AC70710C0E127648711341A6B8A107”.
This ensures that the data has not been tampered with.

 

N.B. the hash calculation needs to be uppercased after the hashing has been completed.

 

 

 

Updated about 1 month ago