1. 3D Secure Ödemesi
Sipay API Documentation
TR
  • EN
  • TR
  • Genel Bakış
    • Başlangıç
    • Test Kartları
  • Kimlik Doğrulama
    • Token Oluşturma
      POST
  • Non-Secure Ödeme
    • Non-Secure Ödeme Akışı
    • Non-Secure Kart Ödemesi
      POST
    • Non-Secure Tekrarlayan Ödeme
      POST
    • Non-Secure Sigorta Ödemesi
      POST
    • Non-Secure Ön Provizyon Ödemesi
      POST
    • Ödeme Onaylama
      POST
  • 3D Secure Ödemesi
    • 3D Secure Ödeme Akışı
    • 3D Secure Kredi Kart Ödemesi
      POST
    • 3D Secure Tekrarlayan Ödeme
      POST
    • 3D Secure Ön Provizyon Ödemesi
      POST
    • Ödeme Tamamlama
      POST
    • Ödeme Onaylama
      POST
    • 3D Secure Tarım Ödemesi
      POST
  • Sipay ile Non-Secure ve 3D Ödeme
    • Purchase Link Örneği
    • Sipay ile Non-Secure ve 3D Secure Ödeme
      POST
  • Ödeme Durumu Sorgulama
    • Durum Sorgulama
      POST
  • Taksitler & Komisyonlar
    • Taksit Bilgisi Sorgulama
      POST
    • Komisyon Bilgisi Sorgulama
      POST
    • Üye İşyeri Taksit Bilgisi Sorgulama
      POST
  • HASH
    • Hash Oluşturma
    • Hash Doğrulama
  • Kayıtlı Kart ile Ödeme
    • 3D Secure Kart Token ile Ödeme
    • Kart Kaydetme
    • Kayıtlı Kart Bilgilerini Sorgulama
    • Kayıtlı Kart Düzenleme
    • Kayıtlı Kart Silme
    • Non-Secure Kart Token ile Ödeme
  • Tekrarlayan Ödeme
    • Tekrarlayan Ödeme Sorgulama
    • Tekrarlayan Ödeme Plan Süreci
    • Tekrarlayan Ödeme Planı Güncelleme
  • İade
    • İade
  • Para Dağıtımı
    • Banka Hesabına Para Aktarımı
  • Webhook
    • Webhook
  • Hata Statü Kodları
    • Statü Kodları
  1. 3D Secure Ödemesi

3D Secure Ön Provizyon Ödemesi

Testing
POST
/ccpayment/api/paySmart3D
Ön Provizyon (Pre-Authorization), bir kartın kullanılabilir limitinin ödeme işlemi için geçici olarak rezerve edilmesi işlemidir. Tutar, karttan hemen tahsil edilmez; bunun yerine kart sahibinin kullanılabilir bakiyesinde bloke edilir. Bu işlemin amacı, ödemenin daha sonra tamamlanması (complete-confirm) için güvence altına alınmasıdır.

1. Ön Provizyon Başlatma#

Secure ödemelerde, gerekli tüm parametreler gönderilmelidir.
Ön provizyon işlemi başlatmak için transaction_type parametresi PreAuth olarak gönderilmelidir.
Müşteri, ödeme işlemi ile birlikte ön provizyon isteği gönderir:
Bloke edilecek tutar belirtilir.
Kart bilgileri gönderilir.

Opsiyonel Parametre:#

Ödemenin kim tarafından tamamlanacağını belirtmek için payment_completed_by isimli bir parametre kullanılabilir. Bu parametre aşağıdaki değerler ile gönderilebilir.
Bu değer app olarak gönderildiğinde, aşağıdaki işlemler sistem tarafından otomatik olarak gerçekleştirilir. Herhangi bir API endpoint çağrısı yapılmasına gerek yoktur.
Bu değer merchant olarak gönderildiğinde, aşağıdaki işlemlerin manuel olarak tamamlanması gerekir.
payment_completed_by parametresi gönderilmezse, sistem değeri otomatik olarak app olarak kabul eder ve işlemi buna göre devam ettirir.

payment_completed_by Değeri "Merchant" Olarak Gönderildiğinde#

Ödeme Tamamlama Endpoint'i#

PreAuth parametresi gönderildikten sonra ödeme durumu Pre-Authorization Pending olur. Ardından ön provizyon sürecini başlatmak için Ödeme Tamamlama endpoint'i çağrılmalıdır.
Ödeme Tamamlama endpoint'i 15 dakika içerisinde çağrılmalıdır.
Bu süre içerisinde çağrılmazsa ödeme işlemi otomatik olarak başarısız olur.
Kart sahibinin bankası aşağıdaki kontrolleri gerçekleştirir:
Kart limitinin yeterli olup olmadığı
Kartın aktif olup olmadığı
Dolandırıcılık / risk kontrolleri

Başarılı olması durumunda:#

Belirtilen tutar geçici olarak bloke edilir.
Yetkilendirme kodu döndürülür.
md_status = 1 olur.
Kontrollerden herhangi birinin başarısız olması durumunda işlem reddedilir.
ℹ️ Bu aşamada henüz herhangi bir tahsilat gerçekleştirilmez; tutar yalnızca kartın kullanılabilir bakiyesinde geçici olarak rezerve edilir.

Ön Provizyon Ödemesini Onaylama#

Ödeme Tamamlama endpoint'i başarıyla çağrıldıktan sonra ödeme durumu Pre-Authorization olarak güncellenir.
Ardından Ödeme Onaylama endpoint'i çağrılmalıdır.
Ödeme Onaylama işlemi yaklaşık 20 gün içerisinde tamamlanmalı veya iptal edilmelidir. Bu süre içerisinde tamamlanmaz veya iptal edilmezse ödeme işlemi otomatik olarak iptal edilir.
Ödeme Onaylama endpoint'i çağrıldığında ödeme durumu aşağıdaki değerlerden biri olarak güncellenir:
Pre-Auth Approved – Ödeme başarıyla onaylandığında.
Pre-Auth Declined – Ödeme onaylama işlemi başarısız olduğunda.


Hash key değeri istekte gönderilmelidir.
Örnek hash key değerleri, seçilen programlama diline göre sağ tarafta yer alan istek örnekleri panelinde bulunmaktadır.

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
Bodyapplication/json

⚪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,
	"authorization_expires_at": "2026-05-15T10:00:00Z",
	"authorization_duration_days": 30
}
Modified at 2026-07-10 12:26:56
Previous
3D Secure Tekrarlayan Ödeme
Next
Ödeme Tamamlama
Built with