1. 3D Secure Payment
SA
  • Overview
    • Getting Started
  • Authentication
    • Token Generation
      POST
  • Commission
    • Commission
      POST
  • HASH
    • Hash Creation
    • Hash Validation
  • Non-Secure Payment
    • Non-Secure Payment Flow
    • Non-Secure Card Payment
      POST
    • Non-Secure Pre-Authorization Payment
      POST
    • Confirm Payment
      POST
  • 3D Secure Payment
    • 3D Secure Payment Flow
    • 3D Secure Card Payment
      POST
    • 3D Secure Pre-Authorization Payment
      POST
    • Complete Payment
      POST
    • Confirm Payment
      POST
  • Non-Secure and 3D Payment with Sipay
    • Non-Secure and 3D Secure Payment with Sipay
      POST
  • Check Status
    • Check Status
      POST
  • Refund
    • Refund
      POST
  • Webhook
    • Webhook
  • Status Codes
    • Status Codes
  1. 3D Secure Payment

3D Secure Pre-Authorization Payment

Testing
POST
/ccpayment/api/paySmart3D
Pre-authorization is a process in which a card's available limit is temporarily reserved for a payment transaction. The amount is not immediately captured from the card, but it is blocked from the cardholder’s available balance. The purpose is to secure the payment for a later finalization (complete-confirm).

1. Initiating Pre-Authorization#

For Secure Payments, all required parameters must be provided.
To initiate a pre-authorization transaction, the transaction_type parameter must be set to PreAuth.
The customer submits a pre-authorization request along with the payment:
The amount to be blocked is specified
Card details are included

Optional Parameter :#

A parameter named payment_completed_by is available to specify who is expected to complete the payment. This parameter can be sent with the following values.
When this value is sent by the app, the following actions are executed automatically. There is no need send any API Endpoints.
When the value is sent by the merchant, the following actions must be completed manually.
If payment_completed_byparameter is not provided, the system automatically treats the value as app and proceeds accordingly.

If payment_completed_by sending "Merchant"#

Complete Payment Endpoint#

After sending the pre-auth parameter, payment status will be Pre-Authorization Pending and then the Complete Payment endpoint must be called to initiate the pre-authorization process.
The Complete Payment endpoint must be called within 15 minutes.
If not called within this timeframe, the payment will automatically failed.
The cardholder’s bank performs the following checks:
Is the card limit sufficient?
Is the card active?
Fraud / risk controls

If successful:#

The specified amount is temporarily blocked.
An authorization code is returned.
md_status = 1.
If any check fails, the transaction is declined.
ℹ️ At this stage, no funds are withdrawn yet; the amount is only temporarily reserved from the card’s available balance.

Confirm Pre-Authorization Payment#

Once the Complete Payment endpoint is successfully called, the payment status is updated to Pre-Authorization.
After that, the Confirm Payment endpoint must be called.
The Confirm Payment process should be completed or canceled within approximately 20 days. If not completed or canceled within this period, the payment will be automatically canceled.
If the Confirm Payment endpoint is called, the payment status will be updated to either:
Pre-Auth Approved – if the payment is successfully confirmed.
Pre-Auth Declined – if the payment confirmation fails.


The hash key must be sent in the request.
Sample hash keys can be found in the request form panel on the side, corresponding to the selected programming language.

Request

Authorization
Provide your bearer token in the
Authorization
header when making requests to protected resources.
Example:
Authorization: Bearer ********************
Body Params application/jsonRequired

Examples

Responses

🟢200Success
application/json
Body

⚪1Failed
🟠404Failed
Request Request Example
Shell
JavaScript
Java
Swift
HASH
generate_hash_key() {
  local total="$1"
  local installment="$2"
  local currency_code="$3"
  local merchant_key="$4"
  local invoice_id="$5"
  local app_secret="$6"

  local data="${total}|${installment}|${currency_code}|${merchant_key}|${invoice_id}"

  local rand1
  rand1=$(openssl rand -hex 16)
  local iv
  iv=$(printf "%s" "$rand1" | openssl sha1 | awk '{print $2}' | cut -c1-16)

  local password
  password=$(printf "%s" "$app_secret" | openssl sha1 | awk '{print $2}')

  local rand2
  rand2=$(openssl rand -hex 16)
  local salt
  salt=$(printf "%s" "$rand2" | openssl sha1 | awk '{print $2}' | cut -c1-4)

  local salt_with_password
  salt_with_password=$(printf "%s" "${password}${salt}" | openssl sha256 | awk '{print $2}' | cut -c1-32)

  local key_hex
  key_hex=$(printf "%s" "$salt_with_password" | xxd -p -c 256)

  local iv_hex
  iv_hex=$(printf "%s" "$iv" | xxd -p -c 256)

  local encrypted_base64
  encrypted_base64=$(printf "%s" "$data" | openssl enc -aes-256-cbc -K "$key_hex" -iv "$iv_hex" -base64)

  local msg_encrypted_bundle="${iv}:${salt}:${encrypted_base64}"
  msg_encrypted_bundle="${msg_encrypted_bundle//\//__}"

  echo "$msg_encrypted_bundle"
}

total="100"
installment="1"
currency_code="TRY"
merchant_key="merchant_key"
invoice_id="invoice_id"
app_secret="app_secret"

result=$(generate_hash_key "$total" "$installment" "$currency_code" "$merchant_key" "$invoice_id" "$app_secret")
echo "$result"
Response Response Example
200 - Success
{
	"sipay_status": "1",
	"order_no": "VP1776849645922312",
	"order_id": "VP1776849645922312",
	"invoice_id": "XV7YO2ADFXZANAF-1776849645",
	"status_code": "100",
	"status_description": "Payment Successfully Completed",
	"sipay_payment_method": "1",
	"credit_card_no": "554960****6017",
	"transaction_type": "Pre-Authorization",
	"payment_status": "1",
	"payment_method": "1",
	"error_code": "100",
	"error": "Payment Successfully Completed",
	"auth_code": "1234456",
	"merchant_commission": "0.02",
	"user_commission": "0",
	"merchant_commission_percentage": "1",
	"merchant_commission_fixed": "0",
	"installment": "1",
	"amount": "2",
	"payment_reason_code": null,
	"payment_reason_code_detail": null,
	"hash_key": "a1111f9ee22ee8db:b8eb:BoR1Nc3eYPpi9oa7r2KkUxOKeBdq3QA4pLiwAMQphd__W5t+PaLSKn1FJ+hAgakz4v5koPQkSDKFKFJFJD3404857fnGWG9WV3L3sOIw==",
	"md_status": "1",
	"original_bank_error_code": null,
	"original_bank_error_description": null,
	"host_reference_id": null
}
Modified at 2026-04-29 07:20:15
Previous
3D Secure Card Payment
Next
Complete Payment
Built with