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)

Environment	Description	END URL
Test – SandBOX	Only for testing purposes. The SandBox does not process the payment requests by real payment gateways. *Do not use SandBox for your store in production*. Requires tester account credential.	https://sandbox.dev.eticsoft.net/etivpos/?/v2/
Prod – Emlak Katılım SanalPOS	Use only for production purposes. This is where the real amounts are processed by capturing from real credit cards. *Do not use the Prod for testing*. Requires Emlak Katılım Bankası merchant account	https://sanalposapi.emlakkatilim.com.tr/?/v4

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.

Parameter	Type / Length	Description	Mandatory	Sample
publicKey	string	Merchant API public key	YES	publikKey_ABCD..
hash	string (64)	Hash (see also calculating hash)	YES	bcae6830adff3d…
date	string (19)	GMT-0 Date formatted YYYY-MM-DD HH:II:SS	YES	2021:01:30 23:55:01
random	int (6)	Random integer number (using for calculating hash) between 100000 and 999999	YES	123456

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

Emlak Katılım Payment Gateway (eticVpos) API Reference