Kart Elementleri

Kart Elementleri, kendi tasarladığınız ödeme formuna güvenli bir kart girişi alanı yerleştirmenizi sağlar. Hassas kart bilgileri Tahsilat’ın PCI-DSS uyumlu iframe’i içinde kalır, hiçbir zaman sizin sunucularınızdan geçmez.

Kart Elementleri ile ödeme formunun tamamını siz tasarlarsınız. Tahsilat.com sadece kart numarası, son kullanma tarihi ve CVV alanlarını güvenli bir iframe olarak sağlar. Taksit, bin sorgulama gibi işlemleri sizin yerinize otomatik yapar.

Kurulum ve Kart Elementini Oluşturma

<style>
    #card-element {
        width: 100%;
        height: 44px;
        border: 1px solid #d2d2d2;
        border-radius: 8px;
    }
</style>

<div id="card-element"></div>
<select id="installment-select" style="display: none;"></select>
<button id="pay-btn" disabled>Ödemeyi Tamamla</button>

<script src="https://js.tahsilat.com/v1/tahsilat.js"></script>

Kart Elementi Oluşturma

Kart elementi, güvenli kart bilgisi toplama alanını sayfanıza yerleştirir. Temel kullanımda sadece tutar ve para birimi yeterlidir. Taksit, stil, placeholder gibi ek özellikler için aşağıdaki bölümlere bakınız.

const tahsilat = new TahsilatSDK('pk_test_wsg...');
const elements = tahsilat.elements();

const cardElement = elements.create('card', {
    amount: 10000,
    currency: 'TRY'
}).on('ready', () => {
    console.log('Kart formu hazır');
}).on('change', (state) => {
    document.getElementById('pay-btn').disabled = !state.complete;
}).mount('#card-element');

const tahsilat = new TahsilatSDK('pk_test_wsg...', {
    debug: true
});

const elements = tahsilat.elements();

const cardElement = elements.create('card', {
    amount: 10000,
    currency: 'TRY'
}).on('ready', () => {
    console.log('Kart formu hazır');
}).on('change', (state) => {
    document.getElementById('pay-btn').disabled = !state.complete;
}).mount('#card-element');

amount kuruş cinsindendir. 100,00 TL için 10000 olarak girilmelidir. currency belirtilmezse varsayılan TRY kullanılır.

Ödeme Başlatma

Kart bilgileri girildikten sonra confirmPayment metodu ile ödeme başlatılır. Aşağıda farklı senaryolar için örnekler bulunmaktadır.

1. Müşteri Bilgileri ile Ödeme

Ödeme isteği oluşturulurken customer_id gönderilmemesi durumunda her ödeme için müşteri bilgileri tekrar alınır ve yeni bir müşteri oluşturulur. Bu durumda müşteri takibi ve raporlama süreci zorlaşabilir.Üye işyeri arayüzünden ya da Müşteriler sayfasından api aracılığı ile müşteri oluşturarak customer_id parametresini kullanabilirsiniz.

document.getElementById('pay-btn').addEventListener('click', async () => {
    const btn = document.getElementById('pay-btn');
    btn.disabled = true;

    try {
        const result = await cardElement.confirmPayment({
            cardholder_name: 'Ahmet Yılmaz',
            customer_email: '[email protected]',
            customer_phone: '5551234567',
            customer_phone_code: '+90',
            customer_country: 'TR' // ISO 3166-1 alpha-2 kabul edilir.
        });

        console.log('Ödeme işlemi başarılı sonucu kontrol ediniz:', result);
    } catch (err) {
        console.error('Hata:', err);
        btn.disabled = false;
    }
});

// SDK'yı debug modu ile başlatın
const tahsilat = new TahsilatSDK('pk_test_wsg...', {
    debug: true
});

const elements = tahsilat.elements();

const cardElement = elements.create('card', {
    amount: 10000,
    currency: 'TRY'
}).on('ready', () => {
    console.log('Kart formu hazır');
}).on('change', (state) => {
    console.log('Kart durumu:', state);
    document.getElementById('pay-btn').disabled = !state.complete;
}).on('installments', (data) => {
    console.log('Taksit seçenekleri:', data);
}).mount('#card-element');
    // Ödeme
    document.getElementById('pay-btn').addEventListener('click', async () => {
    const btn = document.getElementById('pay-btn');
    btn.disabled = true;

    try {
        const result = await cardElement.confirmPayment({
        cardholder_name: 'Ahmet Yılmaz',
        customer_email: '[email protected]',
        customer_phone: '5551234567',
        customer_phone_code: '+90',
        customer_country: 'TR'
    });

        console.log('Ödeme sonucu:', result);
    } catch (err) {
        console.error('Hata detayı:', err);
        console.error('Hata tipi:', err.type);
        console.error('Hata kodu:', err.code);
        btn.disabled = false;
    }
});

2. Müşteri ID ile Ödeme

Mevcut bir müşteriyi customer_id ile ilişkilendirdiğinizde müşteri bilgileri zorunlu değildir. Müşteri, public key ile oluşturulamaz; sadece secret key ile oluşturulabilir ve JS SDK bunu desteklemez. Bunun için Müşteriler sayfasını kontrol ediniz.

const result = await cardElement.confirmPayment({
    cardholder_name: 'Ahmet Yılmaz',
    customer_id: 123456789,
    metadata: [
        { key: "order_id", value: "123456" },
        { key: "customer_type", value: "premium" }
    ],
});

3. Ürün ID’leri ile Ödeme

Önceden oluşturulmuş ürün ID’lerini kullanarak ödeme başlatabilirsiniz. Ürün, public key ile oluşturulamaz; sadece secret key ile oluşturulabilir ve JS SDK bunu desteklemez. Bunun için Ürünler sayfasını kontrol ediniz.

const result = await cardElement.confirmPayment({
    cardholder_name: 'Ahmet Yılmaz',
    customer_id: 123456789,
    product_ids: ['11111111111111', '2222222222222'],
    metadata: [
        { key: "order_id", value: "123456" },
        { key: "customer_type", value: "premium" }
    ],
});

4. Ürün Bilgileri İle Ödeme

const result = await cardElement.confirmPayment({
    cardholder_name: 'Ahmet Yılmaz',
    customer_email: '[email protected]',
    customer_phone: '5551234567',
    customer_phone_code: '+90',
    customer_country: 'TR',
    products: [
        {
            product_name: 'Premium Üyelik',
            price: 10000,
            description: 'Aylık üyelik'
        }
    ],
    metadata: [
        { key: "order_id", value: "123456" },
        { key: "customer_type", value: "premium" }
    ],
});

5. Müşteri ile İlişkilendirilmiş Ödeme

Mevcut bir müşteriyi ödeme ile ilişkilendirmek için customer_id parametresini kullanabilirsiniz. Bu durumda ödeme esnasında müşteri bilgileri tekrardan alınmaz: Müşteri oluşturmak için Müşteriler sayfasını ziyaret edebilirsiniz.

const result = await cardElement.confirmPayment({
    cardholder_name: 'Ahmet Yılmaz',
    customer_id: 123456789,
    product_ids: ['11111111111111', '2222222222222'],
    metadata: [
        { key: "order_id", value: "123456" },
        { key: "customer_type", value: "premium" }
    ],
});

Ödeme Sonuçlarını Dinleme

Tahsilat.js SDK, ödeme işlemlerinin sonuçlarını event listener’lar aracılığıyla yakalamanızı sağlar. Bu sayede ödeme başarılı, başarısız veya iptal edildiğinde kullanıcıya bilgi verebilir ve gerekli aksiyonları alabilirsiniz.

Eğer ödemeyi pre_auth: true ile başlattıysanız, sonuç aldığınızda is_pre_auth değerini kontrol edin. true dönmesi durumunda ödeme başarılıdır ancak tutar karttan çekilmemiş, yalnızca bloke edilmiştir. Bloke edilen tutarı çekmek için ayrıca ön provizyonu kapatma işlemi yapmanız gerekmektedir.

const tahsilat = new TahsilatSDK('pk_test_wsg...');

// Başarılı ödeme
tahsilat.on('paymentSuccess', function(data) {
    console.log('Ödeme başarılı:', data);
    // Örnek: Teşekkür sayfasına yönlendir
});

// Başarısız ödeme
tahsilat.on('paymentError', function(data) {
    console.log('Ödeme hatası:', data);
    // Örnek: Kullanıcıya hata mesajı göster
});

// İptal edilen ödeme
tahsilat.on('paymentCancelled', function(data) {
    console.log('Ödeme iptal edildi:', data);
    // Örnek: Sepet sayfasına yönlendir
});

{
    "success": true,
    "transaction_id": "21325480405674",
    "payment_status": 1,
    "transaction_status": 2,
    "is_pre_auth": false,
    "amount": 50000,
    "currency": "TRY",
    "message": "İşleminiz başarılı bir şekilde tamamlanmıştır.",
    "error_code": "",
    "metadata": [
        { "key": "order_id", "value": "123456" },
        { "key": "customer_type", "value": "premium" }
    ]
}

{
    "success": false,
    "transaction_id": "20544083688242",
    "payment_status": 2,
    "transaction_status": 2,
    "is_pre_auth": false,
    "amount": 50000,
    "currency": "TRY",
    "message": "Hatalı test kart bilgisi.",
    "error_code": "invalid_test_card",
    "metadata": [
        { "key": "order_id", "value": "123456" },
        { "key": "customer_type", "value": "premium" }
    ]
}

Yanıt Alanları

Alan	Tip	Açıklama
`success`	boolean	İşlem başarılı mı
`transaction_id`	string	Tahsilat işlem numarası
`payment_status`	integer	`1`: Başarılı, `2`: Başarısız
`transaction_status`	integer	`2`: Tamamlandı, `3`: Ön provizyon
`is_pre_auth`	boolean	Ön provizyon işlemi mi
`amount`	integer	Tutar (kuruş)
`currency`	string	Para birimi
`message`	string	Durum mesajı
`error_code`	string	Hata kodu (başarısızsa)
`metadata`	array	Ödeme başlatılırken gönderilen ek veriler

Taksit

Kullanıcı kart numarasının ilk 6-8 hanesini girdiğinde SDK otomatik olarak BIN sorgulaması yapar ve taksit seçeneklerini döner. Bu seçenekleri kendi UI’ınızda göstermeniz gerekir.

Taksit seçeneklerindeki installment değeri şifrelenmiş bir değerdir. Bu değeri olduğu gibi installment_count parametresine geçmelisiniz. Düz sayı (1, 2, 3…) göndermeyiniz.

Taksit Akışı

Kullanıcı kart numarasını girer
SDK otomatik BIN lookup yapar
installments eventi tetiklenir
Siz taksit seçeneklerini gösterirsiniz
Seçilen taksitin şifreli installment değerini installment_count olarak göndermelisiniz.

Tam Örnek

Aşağıda taksit seçimi dahil uçtan uca bir ödeme akışı gösterilmektedir. Bu örneği kendi projenize uygun şekilde özelleştirebilirsiniz.

let selectedInstallment = null;

const cardElement = elements.create('card', {
    amount: 10000,
    currency: 'TRY'
}).on('installments', (data) => {
    const select = document.getElementById('installment-select');

    if (!data.installments) {
        selectedInstallment = null;
        select.style.display = 'none';

        return;
    }

    selectedInstallment = data.installments[0].installment;
    select.style.display = 'block';
    select.innerHTML = data.installments.map(item =>
    `<option value="${item.installment}">
            ${item.installment_text} - ₺${item.total_amount}
        </option>`
    ).join('');

    select.addEventListener('change', (e) => {
        selectedInstallment = e.target.value;
    });
}).on('change', (state) => {
    document.getElementById('pay-btn').disabled = !state.complete;
}).mount('#card-element');

// Ödeme
document.getElementById('pay-btn').addEventListener('click', async () => {
    try {
        const result = await cardElement.confirmPayment({
            cardholder_name: 'Ahmet Yılmaz',
            installment_count: selectedInstallment,
            customer_email: '[email protected]',
            customer_phone: '5551234567',
            customer_phone_code: '+90',
            customer_country: 'TR',
            products: [
                { product_name: 'Ürün', price: 10000 }
            ]
        });

        console.log('Ödeme işlemi başarılı sonucu kontrol ediniz:', result);
    } catch (err) {
        console.error('Hata:', err);
    }
});

Installments Event Verisi

{
    "installments": [
        {
            "installment": "eyJpdiI6Ij...",
            "installment_count": 1,
            "installment_text": "Tek çekim",
            "total_amount": "100.00",
            "installment_amount": "100.00",
            "commission_rate": "0.00",
            "commission_by": "1",
            "commission_by_text": "company",
        },
        {
            "installment": "eyJpdiI6Ik...",
            "installment_count": 3,
            "installment_text": "3 Taksit",
            "total_amount": "105.00",
            "installment_amount": "35.00",
            "commission_rate": "5.00",
            "commission_by": "2",
            "commission_by_text": "customer",
        }
    ],
    "binDetail": {
        "brand": "mastercard",
        "type": "credit",
        "bank_name": "Yapı Kredi"
    }
}

Alan	Tip	Açıklama
`installment`	string	Şifreli taksit değeri. `installment_count` parametresine bu değeri geçirin.
`installment_count`	integer	Taksit sayısı (görüntüleme amaçlı).
`installment_text`	string	Görüntüleme metni.
`total_amount`	string	Komisyon dahil toplam tutar.
`installment_amount`	string	Taksit başına tutar.
`commission_rate`	string	Komisyon oranı (%).

Özelleştirme

Ödeme parametrelerini önceden tanımlayarak confirmPayment() çağrısını basitleştirebilirsiniz:

const cardElement = elements.create('card', {
    amount: 10000,
    currency: 'TRY',
    style: {
        fontSize: '16px',
        fontFamily: 'Arial, sans-serif',
        color: '#333333',
        '::placeholder': {
            color: '#aaaaaa'
        }
    },
    placeholder: {
        cardNumber: '0000 0000 0000 0000',
        expiry: 'AA/YY',
        cvv: 'CVV'
    }
});

cardElement.mount('#card-element');

const cardElement = elements.create('card', {
    amount: 10000,
    currency: 'TRY'
}).on('ready', () => {
    console.log('Kart formu hazır');
})
.on('change', (state) => {
    // state.complete - tüm alanlar geçerli mi
    // state.brand   - kart markası (visa, mastercard, troy...)
    // state.error   - hata mesajı (varsa)
    // state.empty   - form boş mu
    document.getElementById('pay-btn').disabled = !state.complete;
})
.on('installments', (data) => {
    // data.installments - taksit listesi
    // data.binDetail    - kart BIN bilgisi
})
.on('focus', (data) => {
    // data.field - odaklanan alan
})
.on('blur', (data) => {
    // data.field - odaktan çıkan alan
});

Event’ler

Event	Açıklama
`ready`	Kart elementi yüklendi ve kullanıma hazır.
`change`	Kart bilgisi değişti. `state.complete`, `state.brand`, `state.error`, `state.empty` döner.
`installments`	BIN lookup sonucu taksit seçenekleri geldi.
`focus`	Bir alan odaklandı. `data.field` ile hangi alan olduğu döner.
`blur`	Bir alan odaktan çıktı.

confirmPayment() Parametreleri

Parametre	Tip	Zorunlu	Açıklama
`cardholder_name`	string	✓	Kart sahibinin adı ve soyadı.
`installment_count`	string		Şifreli taksit değeri. Gönderilmezse tek çekim uygulanır.
`customer_id`	integer		Mevcut müşteri ID. Gönderildiğinde müşteri bilgileri zorunlu değildir.
`customer_email`	string	*	Müşteri e-posta. `customer_id` yoksa zorunlu.
`customer_phone`	string	*	Müşteri telefon. `customer_id` yoksa zorunlu.
`customer_phone_code`	string	*	Telefon ülke kodu (örn. `+90`). `customer_id` yoksa zorunlu.
`customer_country`	string	*	Ülke kodu (örn. `TR`). `customer_id` yoksa zorunlu.
`products`	array		Ürün bilgileri. `product_ids` gönderilmiyorsa kullanılabilir.
`product_ids`	array		Önceden oluşturulmuş ürün ID’leri.
`metadata`	array		Ek veriler. `[{ key: "...", value: "..." }]` formatında.
`description`	string		Ödeme açıklaması.

elements.create() Parametreleri

Parametre	Tip	Zorunlu	Açıklama
`amount`	integer	✓	Ödeme tutarı, kuruş cinsinden.
`currency`	string		Para birimi. Varsayılan: `TRY`.
`locale`	string		Dil. Varsayılan: `tr`.
`style`	object		Kart elementinin stil ayarları.
`placeholder`	object		Placeholder metinleri: `{ cardNumber, expiry, cvv }`.
`hideErrors`	boolean		Hata mesajlarını gizle. Varsayılan: `false`.

Ödeme tutarı ile ürünlerin toplam tutarı eşleşmelidir. Aksi takdirde ödeme reddedilir.

Ödeme sonuçlarını almak için confirmPayment promise sonucunu dinleyebilir veya backend tarafında webhook entegrasyonu yapabilirsiniz. Webhook en güvenilir yöntemdir.

Giriş

Tahsilat JS (SDK)

Entegrasyon (SDK)

Müşteriler

Ürünler

Doğrudan API Entegrasyonu

Kurulum ve Kart Elementini Oluşturma

Kart Elementi Oluşturma

Ödeme Başlatma

1. Müşteri Bilgileri ile Ödeme

2. Müşteri ID ile Ödeme

3. Ürün ID’leri ile Ödeme

4. Ürün Bilgileri İle Ödeme

5. Müşteri ile İlişkilendirilmiş Ödeme

Ödeme Sonuçlarını Dinleme

Yanıt Alanları

Taksit

Taksit Akışı

Tam Örnek

Installments Event Verisi

Özelleştirme

Event’ler

confirmPayment() Parametreleri

elements.create() Parametreleri

​Kurulum ve Kart Elementini Oluşturma

​Kart Elementi Oluşturma

​Ödeme Başlatma

​1. Müşteri Bilgileri ile Ödeme

​2. Müşteri ID ile Ödeme

​3. Ürün ID’leri ile Ödeme

​4. Ürün Bilgileri İle Ödeme

​5. Müşteri ile İlişkilendirilmiş Ödeme

​Ödeme Sonuçlarını Dinleme

​Yanıt Alanları

​Taksit

​Taksit Akışı

​Tam Örnek

​Installments Event Verisi

​Özelleştirme

​Event’ler

​confirmPayment() Parametreleri

​elements.create() Parametreleri

Kurulum ve Kart Elementini Oluşturma

Kart Elementi Oluşturma

Ödeme Başlatma

1. Müşteri Bilgileri ile Ödeme

2. Müşteri ID ile Ödeme

3. Ürün ID’leri ile Ödeme

4. Ürün Bilgileri İle Ödeme

5. Müşteri ile İlişkilendirilmiş Ödeme

Ödeme Sonuçlarını Dinleme

Yanıt Alanları

Taksit

Taksit Akışı

Tam Örnek

Installments Event Verisi

Özelleştirme

Event’ler

confirmPayment() Parametreleri

elements.create() Parametreleri