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.

HTTP Method URL
POST /payment/v1/card-payments/3ds-init

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.

Parameter Name Type Required Description
callbackUrl string Yes The URL to be used to send the result returned from the bank to the merchant

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:

Parameter Name Type Always Exist Description
htmlContent string Yes 3D Secure HTML that will be shown to user. Return value must be base64-decoded.

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:

Parameter Name Type Always Exist Description
status string Yes Represents 3DSecure verification status. Returns SUCCESS or FAILURE.
conversationId string No Value of theconversationId parameter sent in the 3DSecure payment initiation
paymentId number No ID of the payment which is sent when the verification is successful.
completeStatus string Yes 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.
callbackStatus string No 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.
conversationData string No Returns this security parameter when response status success. Need to send this value in complete step.
hash string Yes Response parameters hash value with Sha-256 Hex algorithm. You can find details below on "Creating Hash Value".

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.

HTTP Method URL
POST /payment/v1/card-payments/3ds-complete

Payment Completion Request Parameters

The parameters of the completion request to be made for the payments that pass the verification step are as follows:

Parameter Name Type Always Exist Description
paymentId number Yes 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.

3D Secure Payment Initiation

3D Secure Payment Completion