Create 3D Secure Payment
Payments with 3D Secure take place in three steps: initiation, verification and completion. In the initiation request, a callback URL is given to the Craftgate API where the 3D Secure success status can be forwarded. Merchant business processes triggered by this URL send a request to complete the payment by specifying the payment ID and ensure that the process is completed end-to-end.
You can reach the security recommendations that will be useful for you when making the 3D Secure integration on our related page.
Secure Payment Initiation
URL
The endpoint and http method information to initiate 3D Secure payment are stated below.
Payment Initiation Request Parameters
For payments to be made with 3D Secure, the callbackUrl parameter must be sent, unlike other payments. In this
context, the parameters required to initiate a payment with 3D Secure are as follows.
All parameters in a regular payment request also apply to 3DSecure payment, See: Create Payment - Request Parameters. To initiate a 3DSecure payment, a request must be sent with the callbackUrl parameter.
"boomerang" value that can be sent with the request and received with the response. It can be used to associate different requests with each other. Usually, the order number is used that is stored in merchant own system.
Special characters that may cause security problems should not be used in the data. Data cannot start with the + or - character, but it can be used in it.
It is generally used as a payment order number or basket number on the merchant side. You can search with this value later by using reporting services.
Special characters that may cause security problems should not be used in the data. Data cannot start with the + or - character, but it can be used in it.
Total basket price. The sum of the item prices in the basket must be equal to total basket price.
The final amount to be paid from the card by calculating differences such as commissions and discounts. The amount to be collected from the wallet is also included in this amount. If there is an interest in the transaction, the amount with the interest added should be entered in this parameter.
The amount to be collected from the wallet of the buyer specified in the buyerMemberId parameter. It is required when wallet want to be used for the payment. (Default: 0)
Installment number. Should be 1 for cash price.
ID of the buyer that is returned from member creation.
It is generally used to keep information specific to the payment channel on the merchant side. You can search with this value later by using reporting services.
The URL to be used to send the result returned from the bank to the merchant
Order id parameter to be transmitted to the bank when receiving the payment. Since it is optional, it is recommended not to send it and the orderId value is generated by Craftgate.
IP of the buyer.
(See: Card Information) Should not be sent when payments that will be collected entirely from the wallet (ie. payments where paid price is equal to wallet Price)
Represents the POS that payment will be collected.
You can decide to try another virtual pos after a specific payment error(invalid transaction, do not honor) occurred.
Payment items related to payment. You must send at least one payment item and the sum of prices must be equal to the price field.
Additional parameters related to payment. See: Payment Additional Parameters
Response Parameters
Parameters returned as a result of initiate 3D Secure payment are also subject to the rules specified in
the Response Formats section of the API documentation home page. In the absence of a systematic
or fictional error, the sub-parameters of the object returned in the data parameter are as follows:
3D Secure HTML that will be shown to user. Return value must be base64-decoded.
ID of payment
3D Secure Verification V1
The 3D Secure payment process, which starts with a payment initiation request sent by the merchant, continues with user verification. For this, the HTML content in the response to the initiation request must be decoded and displayed to the user.
After the user enters the verification code sent to them, the verification result is sent to the Craftgate API by the
relevant bank. Craftgate API sends a request to the callbackUrl address sent by the merchant in the payment initiation
request, by collating the result it receives with some information about the payment.
Parameters Forwarded to Callback URL
The parameters are forwarded as form variables using the HTTP POST method. Since merchant callback url is called from customer's browser,
the address should be accessible from internet and content-type should be application/x-www-form-urlencoded.
The parameters included in the request to callbackUrl by Craftgate after validation are as follows:
Represents 3DSecure verification status. Returns SUCCESS or FAILURE.
Value of theconversationId parameter sent in the 3DSecure payment initiation
ID of the payment which is sent when the verification is successful.
According to the 3D Secure model of some banks and payment institutions, the verification and completion process can be done at the same time. If this value is WAITING you should call 3D Secure completion service, if COMPLETED payment is completed.
Sent as a parameter, n case the bank or end user triggers the 3DS verification step again and the payment has been verified before. Status parameter will be FAILURE and callbackStatus parameter will be ALREADY_RETURNED. In case this field comes with the value of ALREADY_RETURNED, the status of the payment should be checked in your system and no action should be taken if it is completed.
Returns this security parameter when response status success. Need to send this value in complete step.
Response parameters hash value with Sha-256 Hex algorithm. You can find details below on "Creating Hash Value".
For 3D Secure Verification V1: Validating The Hash Value
Malicious individuals can make queries to the merchant's Callback URL as if it's coming from Craftgate. Therefore, DO NOT TRUST ANY REQUEST COMING TO THE CALLBACK URL. VALIDATE THE HASH TO PROCEED.
Response's hash value is generated using the Sha-256 Hex method to ensure that the provided parameters are correct.
- You can create 32 characters key value from following: Merchant Panel -> Management -> Merchant Settings -> "Merchant 3DSecure Callback Key"
- You need to prepare input value as in order. Also you need to put "###" as delimiter between parameters.
- For null values please put empty string ("").
threedSecureCallbackKey###status###completeStatus###paymentId###conversationData###conversationId###callbackStatus
Example of hashing procedure for following response is below. Assume that Üye İşyeri Callback Key value as "merchantCallbackKeySandbox".
{
"status": "SUCCESS",
"conversationId": "456d1297-908e-4bd6-a13b-4be31a6e47d5",
"paymentId": 1,
"completeStatus": "COMPLETED",
"callbackStatus": null,
"conversationData": null
"hash": "fffe880629292588380ae03732e2e69d223f07a099c908ec8664e3b033c7523a"
}
Input value for hashing should be like:
merchantCallbackKeySandbox###SUCCESS###COMPLETED###1######456d1297-908e-4bd6-a13b-4be31a6e47d5###
You can hash this value via Sha-256 Hex algorithm with Üye İşyeri Callback Key value. Result must be equal with hash value which contains in response.
3D Secure Verification v2 (Recommended)
With the 3D Secure Verification v2, you can access the value of mdStatus in the callback request. Considering that additional fields can be added to the callback request in the future, the calculation of the hash should be done dynamically. The details of the hash calculation are provided below.
To be able to use the 3D Secure Verification v2, you need to set the value as 2 for the threeDSCallbackVersion parameter under the additionalParams parameter in the 3D Secure Payment Initiation request.
Parameters Forwarded to Callback URL
The parameters are forwarded as form variables using the HTTP POST method. Since merchant callback url is called from customer's browser,
the address should be accessible from internet and content-type should be application/x-www-form-urlencoded.
The parameters included in the request to callbackUrl by Craftgate after validation are as follows:
Represents 3DSecure verification status. Returns SUCCESS or FAILURE.
Value of theconversationId parameter sent in the 3DSecure payment initiation
ID of the payment which is sent when the verification is successful.
According to the 3D Secure model of some banks and payment institutions, the verification and completion process can be done at the same time. If this value is WAITING you should call 3D Secure completion service, if COMPLETED payment is completed.
Sent as a parameter, n case the bank or end user triggers the 3DS verification step again and the payment has been verified before. Status parameter will be FAILURE and callbackStatus parameter will be ALREADY_RETURNED. In case this field comes with the value of ALREADY_RETURNED, the status of the payment should be checked in your system and no action should be taken if it is completed.
Returns this security parameter when response status success. Need to send this value in complete step.
Represents 3DSecure verification status.
Hash parameters which are used to create hash value. The parameters should be parsed by the : character, and their respective parameter values should be added consecutively to be included in the hash calculation.
The hash value that is calculated by concatenating 3DSecure Callback Key and values as described in the hashParams field, and then encrypting it using the SHA-256 Hex algorithm.
Validating The Hash Value For 3D Secure Verification v2
Malicious individuals can make queries to the merchant's Callback URL as if it's coming from Craftgate. Therefore, DO NOT TRUST ANY REQUEST COMING TO THE CALLBACK URL. VALIDATE THE HASH TO PROCEED.
You can access 32 characters key value from following: Merchant Panel -> Management -> Merchant Settings -> "Merchant 3DSecure Callback Key"
- 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'];
}
Aassume that the following callback request is sent, and the Merchant's 3DSecure Callback Key value is merchantCallbackKeySandbox
status=SUCCESS
callbackStatus=
completeStatus=WAITING
paymentId=863
conversationData=
conversationId=d1811bb0-25a2-40c7-ba71-c8b605259611
mdStatus=1
hashParams=status:callbackStatus:completeStatus:paymentId:conversationData:conversationId:mdStatus
hash=07089c50db7babb19a7af7aba11d4acbe43f971355dbbde77de4fcc7d9cd56cc
You should eliminate null values from hashParams parameters and combine them as String. Unlike 3D Secure Verification v1, this step does not include the ##### character in the hashString.
In the example, the value to be inserted into the hashing algorithm should be formed as follows:
merchantCallbackKeySandboxSUCCESSWAITING863d1811bb0-25a2-40c7-ba71-c8b6052596111
Using the algorithm described above, the resulting hash value for the given example would be as follows:
07089c50db7babb19a7af7aba11d4acbe43f971355dbbde77de4fcc7d9cd56cc
To validate the generated hash value, you should compare it with the "hash" parameter present in the request.
3D Secure Payment Completion
For successfully verified payments, after Craftgate sends the result to the merchant with a request to callbackUrl,
the merchant must complete the process by sending a completion request to the Craftgate API. Unless this request is
made, the collection will not take place. Since the completion request is not made or the callbackUrl cannot be
accessed by Craftgate after verification, it will be pending and will be displayed in yellow on the merchant panel.
URL
The endpoint and http method information to complete 3D Secure payment are stated below.
Payment Completion Request Parameters
The parameters of the completion request to be made for the payments that pass the verification step are as follows:
ID of the payment that is sent to callbackUrl as a parameter
Payment Completion Response Parameters
The response to requests to complete payments made with 3D Secure is equivalent to a standard payment and includes details about the payment. For the format of this answer and the parameters it contains, see Create Payment - Response Parameters
Sample Codes
You can review the sample codes in the open source Craftgate API clients.