Create Top-up with 3D Secure

Payments done with 3D Secure is realized in three steps: initiation, verification and completion. In the initiation request, Craftgate API is given a callback URL which can receive the success status of 3d Secure. The merchant triggered by this URL states the payment ID and sends payment completion request thus enabling end to end completion of the process.

3D Secure Payment Initiation


The endpoint and http method information used to initiate 3D Secure payment are stated below.

POST /payment/v1/deposits/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.

Parameter Name Type Mandatory Description
price decimal Yes Amount to be top-up
buyerMemberId number Yes The ID value of the buyer member who is related to payment. This ID value is not the id value that is stored in merchant own system. It is the value stored in Craftgate.
currency Currency Yes See: Currencies The currency of the payment
conversationId string No "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.
callbackUrl string Yes The address to be used to send back the result returned from the bank to the merchant system for the 3D Secure payments (see. Create 3D Secure Payment)
posAlias string No The alias value of the POS that the payment pass over
card Card No Card information to be collected (See. Card Information)

Card Information

If the cardUserKey field is set in card information in the request, the fields in the Stored Card Information section are valid. For other cases, see: Credit Card, Debit Card or Prepaid Card Information.

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 HTML content of the 3D Secure form to be displayed to the user. This value is sent as Base64-encoded and must be Base64 decoded by the merchant before display.

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 information about the payment.

Parameters Forwarded to Callback URL

The following parameters are forwarded as form variables using the HTTP POST method. The parameters included in the request to callbackUrl to be done by Craftgate after validation are as follows:

Parameter Name Type Always Exist Description
status string Yes Status of 3D Secure verification. The value is SUCCESS if verification is successful, FAILURE if verification is failed
conversationId string No Value of theconversationId parameter sent in the payment initiation request
paymentId number No This value returns when validation is successful. The ID value for the payment generated by the Craftgate API

3D Secure Payment Completion

For successfully verified payments, after the result is forwarded to the merchant with a request to callbackUrl by Craftgate, 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 callbackUrl cannot be accessed by Craftgate after verification or when the completion request is not made, it will be pending and will be displayed in yellow on the merchant panel.


The endpoint and http method information used to complete 3D Secure payment are stated below.

POST /payment/v1/deposits/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 The ID of the payment that is generated by Craftgate API and passed to callbackUrl

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: Payment - Response Parameters

Withdraw Money from Wallet

To refund the money that is deposit to wallet, to the card, visit the Refund Wallet Transaction page.

Sample Codes

You can review the sample codes in the open source Craftgate API clients.

3D Secure Payment Initiation

3D Secure Payment Completion