1. Home
  2. Docs
  3. Emlak Katılım Payment Gat...
  4. Introduction
  5. Basics & References

Basics & References

Basics & References

EticVpos API is compatible with the RESTFUL API references that communicate over the HTTP POST method and uses JSON encoded data for both requesting & responding to resource-oriented URL endpoints. 

Authentications & Tokens 

The EticVpos API does not use the TOKENS for Auth. Instead, it uses only API KEYS and a HASH value to identify the requester for each request.

Backend URL(s)

EnvironmentDescriptionEND URL            
Test – SandBOXOnly for testing purposes. The SandBox does not process the payment requests by real payment gateways.
Do not use SandBox for your store in productionRequires tester account credential.
Prod – Emlak Katılım SanalPOSUse only for production purposes. This is where the real amounts are processed by capturing from real credit cards.
Do not use the Prod for testingRequires Emlak Katılım Bankası merchant account 

General Request Structure:

The JSON formatted data should be assigned to the “POST” (HTTP POST array). The request has two sub-nodes with the header and data names.

The header node is always having the same structure that will be used for authentication controls. The data node structure is depending on the api function.

  "header": { AUTH RELATED INFO (apiKey, date, hash value etc.) },
  "data": { TRANSACTION RELATED INFO (credit card number, orders etc.) },

General Response Structure:

The EticVpos always responses with the same JSON formatted data as it requested. The response has also same two sub-nodes as the header and data nodes. The head node caries the result of the request with the result_code and result_message parameters which are conditioners for the flow. It has also a hash, rand, and the date properties which are standing for the security control.

  "header": { RESULT RELATED INFO (result_code, result_message, date, hash value etc.) },
  "data": { ADDITONAL INFO (transaction given id, 3D Secure URL etc.) },

Request “header” Node  Parameters

The header node of request parameters is the same for all API request functions.

ParameterType   /  Length      DescriptionMandatorySample
publicKeystringMerchant API public keyYESpublikKey_ABCD..
hashstring (64)Hash (see also calculating hash)YESbcae6830adff3d…
datestring (19)GMT-0 Date formatted YYYY-MM-DD HH:II:SSYES2021:01:30 23:55:01
randomint (6)Random integer number (using for calculating hash) between 100000 and 999999YES123456

Request Structure Example

HTTP POST to <ENDURL>/transaction/payment/

  "header": {
    "publicKey": "publikKey_ABCDsomestrings...",
    "hash": "a28hka003so3b...",
    "date": "2021-12-30 14:08:58",
    "random": 569874
  "data": {
    "credit_card": {
      "cc_number": "4111111111111111",
      "cc_expire": 202108,
      "cc_cvv": 398,
      "cc_holder": "John Doe"
  "amount": 867.01,

API Keys and the merchantID

EticVpos API uses two different API keys (public & private) and the ID number of the merchant while authorization. Only the publicKey of those parameters must be sent in requests. The private key and the merchantID must be kept as secret and never placed in request.

  • The publicKey must be placed in the “header” node of all requests.
  • The privateKey is a secret key that must be kept hidden. Never send it in the requests. It is used while calculating the HASH value. 
  • The merchantID is the ID number of the merchant that must be hidden and. Never send it in the requests. It is used while calculating the HASH value.

Calculating The HASH Value

The HASH value is calculating by the SHA256 (Secure Hash Algorithm 2) function by following the hash string as an argument

Hash Argument String = publicKey+privateKey+merchantID+date(YYYY-MM-DD HH:MM:SS)+random Number

Will be something like “publicabcd1234privatedefg4567812352021-08-20 15:34:087256

Hash = SHA256(“publicabcd123481235privatedefg45672021-08-20 15:34:087256”)

The function will return a string like “e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855” that is the final HASH value.

The final hash value must be assigned to the “hash” key of the “head” node of the “request”.