Secure Ödeme (Pay Smart 3D)

3D güvenli ödeme almak için bu API kullanılır. Kullanıcı, banka doğrulama sayfasına yönlendirilir ve SMS koduyla ödeme doğrulanır. Ödeme başarılı ise return_url'e başarısız ise cancel_url'e gidilir. İlgili response mesajı query params içerisinde döner.

İstek Bilgileri

Metot: POST (HTML form gönderimi olmalıdır, AJAX kullanılmamalıdır)
URL: https://staging.halkode.com.tr/ccpayment/api/paySmart3D
CANLI URL: https://app.halkode.com.tr/ccpayment/api/paySmart3D
Yetkilendirme: Bearer {token} Token Alma servisinden alınan değer

İstek Parametreleri (Body)

Parametre	Tip	Koşul	Açıklama
`cc_holder_name`	`string`	Zorunlu	Kart sahibinin adı soyadı.
`cc_no`	`string`	Zorunlu	Maskelenmiş kart numarası (Örn: `123456******1234`).
`expiry_month`	`string`	Zorunlu	İki haneli ay (Örn: `08`).
`expiry_year`	`string`	Zorunlu	Dört haneli yıl (Örn: `2028`).
`cvv`	`string`	Zorunlu	Kartın arkasındaki güvenlik kodu.
`total`	`double`	Zorunlu	Toplam tutar (Nokta ile ayrılmalı).
`installments_number`	`integer`	Zorunlu	Taksit Tutarı
`currency_code`	`string`	Zorunlu	Para birimi kodu (Örn: `TRY`).
`merchant_key`	`string`	Zorunlu	Üye işyeri anahtarınız.
`invoice_id`	`string`	Zorunlu	Sizin tarafınızdaki tekil sipariş ID.
`invoice_description`	`string`	Boş Bırakılabilir	Sizin tarafınızdaki tekil sipariş ID.
`hash_key`	`string`	Zorunlu	Güvenlik imzası.
`name`	`string`	Zorunlu	İsim
`surname`	`string`	Zorunlu	Soyisim
`items`	`array`	Zorunlu	Ürün Sepeti
`return_url`	`string`	Zorunlu	Ödeme başarılı ise dönüş yapılacak URL (HTML formatında olmalıdır)
`cancel_url`	`string`	Zorunlu	Ödeme başarısız ise dönüş yapılacak URL (HTML formatında olmalıdır)
`transaction_type`	`string`	Opsiyonel	transaction_type == "Auth" ise işlem tutarı karttan anında düşülür. transaction_type == "PreAuth" ise işlem tutarı karttan daha sonra düşülecektir. Default değeri "Auth"
`payment_completed_by`	`string`	Opsiyonel	payment_completed_by == "app" ise işlem tutarı anında gerçekleşecektir. payment_completed_by == "Merchant" ise işlem tutarı üye iş yeri onayından sonra gerçekleşecektir. Default değeri app’dir.

Hash-Key Oluşturma

Hash Key, istek parametrelerinde yer alan invoice_id, merchant_key,currency_code,installments_number,total değerleri ve size ait benzersiz app_secret değerini kullanarak oluşturulması gereken benzersiz bir anahtardır. Aşağıda hash_key oluşturma yöntemi verilmiştir.

PHP Örnek Kodu

PHP

public static function hashGenerator($currency_code,$merchant_key,$invoice_id,$app_secret,$total,$installments_number)
{
       
  $data = $total . '|' . $installmentsNumber . '|' . $currency_code . '|' . $merchant_key . '|' . $invoice_id;
  $iv = substr(sha1(mt_rand()), 0, 16);
  $password = sha1($app_secret);
  $salt = substr(sha1(mt_rand()), 0, 4);
  $saltWithPassword = hash('sha256', $password . $salt);
  $encrypted = openssl_encrypt(
      $data, 'aes-256-cbc', $saltWithPassword, 0, $iv
  );
  $msg_encrypted_bundle = $iv . ':' . $salt . ':' . $encrypted;
  $msg_encrypted_bundle = str_replace('/', '__', $msg_encrypted_bundle);
  return response()->json(['Hash Key' =>$msg_encrypted_bundle ]);
}

Örnek İstek (Request)

json

{

    "cc_holder_name":"John Dao",
    "cc_no":"4155141122223339",
    "expiry_month":"12",
    "expiry_year":"2028",
    "cvv":"555",
    "currency_code":"TRY",
    "installments_number": 1,
    "invoice_id":"111112324115312",
    "invoice_description":" INVOICE TEST DESCRIPTION",
    "total":22.00,
    "items": [
        {
            "name": "Item3",
            "price": 22,
            "quantity": 1,
            "description": "item3 description"
        }
    ],
    "name" : "John",
    "surname" : "Dao",
    "merchant_key":"$2y$10$...",
    "hash_key" : "hesaplanan hash ",
    "return_url": "http://merchant-domain.com/success", // html sayfa olmalıdır
    "cancel_url": "http://merchant-domain.com/error", // html sayfa olmalıdır
    "payment_completed_by": "app", // Opsiyonel 
    "transaction_type": "Auth" // Opsiyonel 

}

Başarılı Yanıt

html

<form id="the-form" method="post" action="https://staging.halkode.com.tr/ccpayment/sr/redirect-to-bank">
  <input type="hidden" name="invoice_id" value="169262955487156" />
  <input type="hidden" name="amount" value="1.00" />
  <input type="hidden" name="client_id" value="31083" />
  <input type="hidden" name="return_url" value="https://staging.halkode.com.tr/ccpayment/payment/dummy_return_url?brand_order_id=169262955487156" />
</form>
<script type="text/javascript">
  window.onload = function() {
    document.getElementById("the-form").action = "";
    document.getElementById("the-form").submit();
  }
</script>

Başarılı yanıt aldığımız durumda ilgili banka sayfası HTML formatında döner.

Örnek Banka Sayfası

3D Ödeme Sonuç süreci

3D Secure ödeme akışında, kullanıcı banka doğrulama sayfasındaki (OTP) işlemini tamamladıktan sonra sistem otomatik olarak üye işyerinin belirttiği return_url adresine yönlendirme yapar.

1. Yönlendirme ve Veri Aktarımı

Önemli Not

3D Secure doğrulaması tamamlandığında, işlem sonucu ve detayları GET metodu kullanılarak Query String (URL Parametreleri) yapısında return_url adresinize iletilir.

Örnek Dönüş URL Yapısı: http://merchant-domain.com/success?order_no=1626...&invoice_id=deneme123&status_code=100&status_description=Payment+Successfully+Completed&payment_status=1&hash_key=...

2. Dönüş Parametreleri

return_url adresine gelen tüm parametreler ve açıklamaları aşağıdadır:

Parametre	Açıklama
`status_code`	İşlem sonuç kodu (Başarılı işlem için: 100).
`status_description`	İşlemin durumunu açıklayan metin.
`order_no`	HalkÖde sistemindeki tekil işlem numarası.
`invoice_id`	Sizin tarafınızdan gönderilen sipariş/fatura ID.
`payment_status`	Ödeme durumu (1: Başarılı, 0: Başarısız).
`transaction_type`	İşlem tipi (Örn: Auth veya PreAuth).
`payment_method`	Ödeme yöntemi (1: Kredi Kartı).
`credit_card_no`	Maskelenmiş kart numarası (Örn: 658761****9656).
`auth_code`	Bankadan dönen onay kodu.
`merchant_commission`	İşlemden kesilen üye işyeri komisyon tutarı.
`user_commission`	Son kullanıcıya yansıtılan komisyon tutarı.
`md_status`	3D Secure doğrulama durumu.
`hash_key`	Yanıtın güvenliğini doğrulamak için üretilen imza.

3. Ödeme Başarısız Senaryosu (OTP Doğrulanamadı)

Önemli Not

3D Secure doğrulaması tamamlanmadığında veya işlem sonucu hatalı olduğunda işlem sonucu ve detayları GET metodu kullanılarak Query String (URL Parametreleri) yapısında cancel_url adresinize iletilir.

Örnek Dönüş URL Yapısı: http://merchant-domain.com/error?order_no=VP17736419522411358&order_id=VP17736419522411358&invoice_id=tksprod202603061436deneo&status_code=41&status_description=transaction+failed

Başarısız Yanıt

json


{
    "status_code": 41,
    "status_description": "Gecersiz hesap numarasi.",
    "data": {
        "order_no": "VP17733132019692187",
        "order_id": "VP17733132019692187",
        "invoice_id": "Abcd1245671",
        "credit_card_no": "413226****0003",
        "transaction_type": "Auth",
        "payment_status": 0,
        "payment_method": 1,
        "error_code": "14",
        "error": "Gecersiz hesap numarasi.",
        "auth_code": null,
        "merchant_commission": 0.66,
        "user_commission": 0,
        "merchant_commission_percentage": 2.99,
        "merchant_commission_fixed": 0,
        "hash_key": "342fa9539f23ea16:5981:n8A4HxE2rGyk2RHp6J+L8M6PSOF1fnAzsGv4ybylad90oC6c5KjOxXKtI__RAjQmb",
        "original_bank_error_code": "14",
        "original_bank_error_description": "Gecersiz hesap numarasi."
    }
}

Kod Örnekleri

PHP Örnek Kodu

PHP


<?php

function sendRequest( $data, $token) {
    $baseUrl = "https://staging.halkode.com.tr/ccpayment/api/paySmart3D"
    $url = $baseUrl . $endpoint;
    
    $ch = curl_init($url);
    $payload = json_encode($data);
    
    $headers = [
        'Content-Type: application/json',
        'Accept: application/json',
        'Authorization: Bearer ' . $token
    ];
    
   
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_POST, true);
    curl_setopt($ch, CURLOPT_POSTFIELDS, $payload);
    curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
    
    $response = curl_exec($ch);
    $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    curl_close($ch);
    
    return json_decode($response, true);
}

//Token get token servisinden alınır. 

$authData = [
    "cc_holder_name":"John Dao",
    "cc_no":"4155141122223339",
    "expiry_month":"12",
    "expiry_year":"20",
    "cvv":"555",
    "currency_code":"TRY",
    "installments_number": 1,
    "invoice_id":"111112324115312",
    "invoice_description":" INVOICE TEST DESCRIPTION",
    "total":22.00,
    "items": [
        {
            "name": "Item3",
            "price": 22,
            "quantity": 1,
            "description": "item3 description"
        }
    ],
    "name" : "John",
    "surname" : "Dao",
    "merchant_key":"$2y$10$...",
    "hash_key" : "hesaplanan hash "
];

$authResult = sendRequest($authData,$token);
print_r($authResult);
?>

C# /.NET Örnek Kodu


using System.Text;
using System.Text.Json;
using System.Net.Http.Headers;

public class HalkodeClient
{
    private static readonly HttpClient client = new HttpClient();

    public async Task<string> PaySmart3D(object paymentData, string token)
    {
        var url = "https://staging.halkode.com.tr/ccpayment/api/paySmart3D";
        
        var json = JsonSerializer.Serialize(paymentData);
        var content = new StringContent(json, Encoding.UTF8, "application/json");

        client.DefaultRequestHeaders.Clear();
        client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", token);
        client.DefaultRequestHeaders.Accept.Add(new MediaTypeWithQualityHeaderValue("application/json"));

        var response = await client.PostAsync(url, content);
        return await response.Content.ReadAsStringAsync();
    }
}

// Örnek Kullanım
var paymentData = new {
    cc_holder_name = "Test kart",
    cc_no = "444444******4444",
    expiry_month = "12",
    expiry_year = "2024",
    cvv = "555",
    currency_code = "TRY",
    installments_number = 1,
    invoice_id = "Abcd1245671",
    invoice_description = "INVOICE TEST DESCRIPTION",
    total = 22.00,
    items = new[] {
        new { name = "Item3", price = 22, quantity = 1, description = "item3 description" }
    },
    name = "John",
    surname = "Dao",
    merchant_key = "$2y$10$WxwG144ioxqD77COQCNV0...",
    hash_key = "d02ee95a43f3a1a2:d52a:EwVzFl..."
};

var halkode = new HalkodeClient();
var result = await halkode.PaySmart3D(paymentData, "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzUxMiJ9...");

JavaScript / NodeJs Örnek Kodu

JavaScript


const axios = require('axios');

async function paySmart3D(paymentData, token) {
    try {
        const config = {
            method: 'post',
            url: 'https://staging.halkode.com.tr/ccpayment/api/paySmart3D',
            headers: { 
                'Content-Type': 'application/json', 
                'Accept': 'application/json',
                'Authorization': 'Bearer ' + token
            },
            data: paymentData
        };

        const response = await axios(config);
        return response.data;
    } catch (error) {
        console.error('Hata:', error.response ? error.response.data : error.message);
    }
}

const paymentData = {
    "cc_holder_name": "Test kart",
    "cc_no": "444444******4444",
    "expiry_month": "12",
    "expiry_year": "2024",
    "cvv": "555",
    "currency_code": "TRY",
    "installments_number": 1,
    "invoice_id": "Abcd1245671",
    "invoice_description": "INVOICE TEST DESCRIPTION",
    "total": 22.00,
    "items": [
        {
            "name": "Item3",
            "price": 22,
            "quantity": 1,
            "description": "item3 description"
        }
    ],
    "name": "John",
    "surname": "Dao",
    "merchant_key": "$2y$10$WxwG144ioxqD77COQCNV0...",
    "hash_key": "d02ee95a43f3a1a2:d52a:EwVzFl..."
};

paySmart3D(paymentData, "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzUxMiJ9...").then(console.log);

Secure Ödeme (Pay Smart 3D) ​

İstek Bilgileri ​

İstek Parametreleri (Body) ​

Hash-Key Oluşturma ​

Örnek İstek (Request) ​

Başarılı Yanıt ​

3D Ödeme Sonuç süreci ​

Başarısız Yanıt ​

Kod Örnekleri ​