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.

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 Verification

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:

Critical Security Check: 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 3DSecure Callback Key value as "merchantThreeDsCallbackKeySndbox".

{
    "status": "SUCCESS",
    "conversationId": "456d1297-908e-4bd6-a13b-4be31a6e47d5",
    "paymentId": 1,
    "completeStatus": "COMPLETED",
    "callbackStatus": null,
    "conversationData": null
    "hash": "8e042e470e283c3658786577ad0c52e28f8eee7094a1860957877258a963a061"
}

Input value for hashing should be like:

merchantThreeDsCallbackKeySndbox###SUCCESS###COMPLETED###1######456d1297-908e-4bd6-a13b-4be31a6e47d5###

You can hash this value via Sha-256 Hex algorithm with Üye İşyeri 3DSecure Callback Key value. Result must be equal with hash value which contains in response.

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:

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.

3D Secure Payment Initiation

• Java
• .NET
• PHP
• Node.js

3D Secure Payment Completion

• Java
• .NET
• PHP
• Node.js