Meal Voucher Card Storage
The endpoint, HTTP method information, request and response parameters used in the meal voucher card storage solution are given below.
Request Parameters for Initializing Meal Voucher Card Storage
The init request must be made with the following parameters to start the meal voucher card storage process.
APM type. See: Alternative Payment Methods
Meal voucher card storage information.
Card number (Must be sent for APM types METROPOL and EDENRED.)
User reference number
GSM number (Must be sent for APM types METROPOL and TOKENFLEX.)
The address to be used to convey the meal voucher card storage result and necessary information to the merchant. (Must be sent for APM types SETCARD, TOKENFLEX, MULTINET and SODEXO.)
Response Parameters
Session ID of the transaction
Guide values regarding the step to be taken in the next stage
The HTML code content of the form to be displayed to the user. This value is sent as Base64-encoded and must be Base64 decoded by the merchant before display. (Will be returned for APM types MULTINET and SETCARD.)
Information about the URL where the payment process will continue. (Will be returned for APM types SODEXO and TOKENFLEX.)
Meal Card Tokenization Hash Verification
After the meal card tokenization process is initiated, the user selects the card to be stored and completes the operation on the screen. Once the process is finished, the result of the tokenization operation is sent to the callback URL provided by the merchant during the initialization (init) phase.
Parameters Sent to the Callback URL
A unique identifier for the transaction.
The card fingerprint.
The masked card number.
Indicates the status of the meal card tokenization operation. The value will be SUCCESS if the verification is successful; otherwise, it will be FAILURE.
Contains the ordered list of parameters used for hash calculation. The parameters should be split by the : character, and the corresponding parameter values should be concatenated in the given order before being included in the hash calculation.
The SHA-256 Hex encoded value generated by concatenating the Merchant Callback Key with the parameter values specified in hashParams, as described above. Sample code for generating the hash is provided below.
Mandatory Security Step: Hash Value Generation and Check
Malicious people can send requests to the merchant's Callback URL just like Craftgate did. For this reason, Do NOT TRUST ANY REQUEST COMING TO CALLBACK URL WITHOUT HASH CHECKING.
The required 32-character callback key can be obtained from the Merchant Callback Key field under Management → Merchant Settings in the Merchant Panel.
- Java
- Node.js
public boolean verifyHash(Map<String, String> callbackParams, String callbackKey) {
String hashValues = Arrays.stream(callbackParams.get("hashParams").split(":"))
.map(callbackParams::get)
.collect(Collectors.joining());
String calculatedHash = DigestUtils.sha256Hex(callbackKey + hashValues);
return calculatedHash.equals(callbackParams.get("hash"));
}
function verifyHash(callbackParams, callbackKey) {
const hashValues = callbackParams['hashParams'].split(':')
.map(param => callbackParams[param])
.join('');
const calculatedHash = crypto
.createHash('sha256')
.update(callbackKey + hashValues)
.digest('hex');
return calculatedHash === callbackParams['hash'];
}
Assume that the following callback payload is received and the Merchant Callback Key is merchantDummyCallbackKeySandbox1
The callback parameters are:
sessionId=60351fc9-c5ce-42a8-9332-6e15ebf5bbe8
status=SUCCESS
maskedCardNumber=7599********1920
fingerprint=ca31e9418f907fcfbb50fc7733ed2d93b83b30a05e49e64c83058813827a8426
hashParams=sessionId:status:maskedCardNumber:fingerprint
hash=095eb6428b6fd40543837ce009ede7c7f0a5b6006478e35825d8673fb3716b13
You should exclude any null values from the parameters listed in hashParams and concatenate the remaining values as strings.
In this example, the input to the hash algorithm should be:
merchantDummyCallbackKeySandbox160351fc9-c5ce-42a8-9332-6e15ebf5bbe8SUCCESS7599********1920ca31e9418f907fcfbb50fc7733ed2d93b83b30a05e49e64c83058813827a8426
Applying the algorithm above will produce the following hash value:
095eb6428b6fd40543837ce009ede7c7f0a5b6006478e35825d8673fb3716b13
The generated hash must be compared with the hash parameter included in the callback request. The callback should only be considered valid if the two values match.
Request Parameters for Completing Meal Voucher Card Storage
To complete the meal voucher card storage process, the complete request should be sent with the following parameters using the sessionId returned as a result of the init request.
This request should only be sent for APM type METROPOL.
Validation code
Response Parameters
Unique value of the transaction
Masked card number
Card fingerprint
Balance
Regenerating Meal Voucher Card Storage Process
Whenever the meal voucher card storage process needs to be restarted for any reason, the process can be restarted using the sessionId value returned as a result of the init request.
After the restart request, only for METROPOL APM type, "Complete Meal Voucher Card Storage" request can be sent.
Meal voucher card storage information.
Card number (Must be sent for APM types METROPOL and EDENRED.)
User reference number
GSM number (Must be sent for APM types METROPOL and TOKENFLEX.)
The address to be used to convey the meal voucher card storage result and necessary information to the merchant. (Must be sent for APM types SETCARD, TOKENFLEX, MULTINET and SODEXO.)
Response Parameters
Unique value of the transaction
Guide values regarding the step to be taken in the next stage
The HTML code content of the form to be displayed to the user. This value is sent as Base64-encoded and must be Base64 decoded by the merchant before display. (Will be returned for APM types MULTINET and SETCARD.)
Information about the URL where the payment process will continue. (Will be returned for APM types SODEXO and TOKENFLEX.)
Sample Codes
You can review the sample codes in the open source Craftgate API clients.