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.
The endpoint and http method information to initiate 3D Secure payment are stated below.
HTTP Method | URL |
---|---|
POST |
/payment/v1/card-payments/3ds-init |
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 |
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. |
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.
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". |
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.
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.
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.
The endpoint and http method information to complete 3D Secure payment are stated below.
HTTP Method | URL |
---|---|
POST |
/payment/v1/card-payments/3ds-complete |
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 |
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
You can review the sample codes in the open source Craftgate API clients.