Skip to main content

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

URL

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.

price
decimal
required

Amount to be top-up

buyerMemberId
number
required

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
required

See: Currencies The currency of the payment

Values:
TRY
USD
EUR
GBP
CNY
ARS
BRL
AED
IQD
AZN
KZT
KWD
SAR
BHD
RUB
JPY
EGP
conversationId
string

"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
required

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

The alias value of the POS that the payment pass over

card
Card
required

Card information to be collected

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:

htmlContent
string

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.

paymentId
number

ID of payment

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:

status
string

Status of 3D Secure verification. The value is SUCCESS if verification is successful, FAILURE if verification is failed

conversationId
string

Value of theconversationId parameter sent in the payment initiation request

paymentId
number

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.

URL

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:

paymentId
number

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

Loading..

3D Secure Payment Completion

Loading..