{{ config('app.name') }}

API Dokümantasyonu

Versiyon 1.0.0

Payment Link API

Güvenli ve kolay entegre edilebilir ödeme bağlantısı çözümü.

Özellikler

Hızlı Entegrasyon

Kolay implementasyon ve hızlı entegrasyon imkanı

Güvenli İşlem

End-to-end şifrelenmiş güvenli ödeme altyapısı

Webhook Desteği

Gerçek zamanlı işlem bildirimleri

Base URL

https://panel.{{ config('app.lower_name') }}/api/

API Endpointleri

POST /api/get-token

API erişimi için token almak üzere kullanılır.

İstek Parametreleri:

  • app_key - Merchant panel üzerinden alınan app_key
  • app_secret - Merchant panel üzerinden alınan app_secret
POST /api/whitelabel-b2c-wallet-transfer

İşletme cüzdanından müşteri cüzdanına para transferi yapmak için kullanılır.

İstek Parametreleri:

  • customer_number - Müşteri numarası (customer_email veya customer_phone_number olmadığında zorunlu)
  • customer_name - Müşterinin tam adı (zorunlu)
  • lock_minute - İşlem kilidi süresi (zorunlu)
  • amount - Transfer tutarı (zorunlu)
  • currency - Para birimi kodu (örn: TRY) (zorunlu)
  • reference_id - Benzersiz referans numarası (zorunlu)
  • desc - İşlem açıklaması (opsiyonel)
POST /api/whitelabel-c2b-wallet-transfer-otp

Müşteriden işletmeye transfer işlemi için OTP kodu gönderimi yapar.

İstek Parametreleri:

  • customer_email - Müşteri e-posta adresi (zorunlu)
  • customer_name - Müşterinin tam adı (zorunlu)
  • amount - Transfer tutarı (zorunlu)
  • currency - Para birimi kodu (örn: TRY) (zorunlu)
  • reference_id - Benzersiz referans numarası (zorunlu)
  • desc - İşlem açıklaması (opsiyonel)
POST /api/whitelabel-c2b-wallet-transfer

OTP doğrulaması ile müşteriden işletmeye transfer işlemini tamamlar.

İstek Parametreleri:

  • reference_id - OTP gönderimi sırasında kullanılan referans numarası (zorunlu)
  • otp_code - SMS ile gönderilen doğrulama kodu (zorunlu)
POST /api/payment-link/create

Yeni bir ödeme bağlantısı oluşturmak için kullanılır.

İstek Parametreleri:

  • reference_id - Benzersiz referans numarası
  • amount - İşlem tutarı (opsiyonel)
  • success_callback_url - Başarılı işlem yönlendirme URL'i
  • fail_callback_url - Başarısız işlem yönlendirme URL'i
  • webhook_callback_url - Webhook bildirim URL'i
  • desc - İşlem açıklaması (opsiyonel)
GET /api/get-dekont

İşlem dekontunu PDF veya HTML formatında almak için kullanılır.

İstek Parametreleri:

  • tracking_id - İşlem takip numarası
  • type - İşlem tipi (c-to-b, b-to-c, c-to-b-link, c-to-c, deposit, withdraw)

Kabul Edilen Formatlar:

  • Accept: application/pdf - PDF formatında dekont
  • Accept: text/html - HTML formatında dekont

Kimlik Doğrulama

Token Alma

API'yi kullanmaya başlamadan önce merchant hesabınıza ait app_key ve app_secret bilgilerini kullanarak bir Bearer token almanız gerekmektedir.

Endpoint

POST /api/get-token

İstek Parametreleri

Parametre Tip Zorunlu Açıklama
app_key string Evet Merchant panel üzerinden alınan app_key
app_secret string Evet Merchant panel üzerinden alınan app_secret

Başarılı Yanıt

{
    "status": true,
    "message": "Token başarıyla oluşturuldu",
    "data": {
        "token": "1|abcdef123456...",
        "token_type": "Bearer"
    }
}

Hata Yanıtları

401 - Geçersiz Kimlik

{
    "status": false,
    "message": "Geçersiz kimlik bilgileri"
}

422 - Validasyon Hatası

{
    "status": false,
    "message": "Validasyon hatası",
    "errors": {
        "app_key": ["App key zorunludur"],
        "app_secret": ["App secret zorunludur"]
    }
}

Token Kullanımı

Authorization: Bearer 1|abcdef123456...

Aldığınız token'ı tüm API isteklerinizde Authorization header'ında yukarıdaki formatta göndermeniz gerekmektedir. Tokenlar süresiz geçerlidir ancak güvenlik nedeniyle düzenli olarak yenilemeniz önerilir.

Önemli Güvenlik Notları

  • Token'ınızı güvenli bir ortamda saklayın
  • Client tarafında veya açık kaynak kodlarda paylaşmayın
  • Şüpheli bir durum tespit ettiğinizde hemen token'ınızı yenileyin
  • Her uygulama için ayrı token kullanın

C2B Transfer

Bu API, müşteri cüzdanından işletme cüzdanına para transferi yapılmasını sağlar. İşlem iki adımda gerçekleşir: İlk olarak müşteri bilgileri doğrulanır ve OTP (SMS) kodu gönderilir, ardından OTP doğrulaması ile transfer tamamlanır. Her iki adım için ayrı endpoint kullanılır.

1. OTP İsteği Endpoint

POST /api/whitelabel-c2b-wallet-transfer-otp

Authorization: Bearer Token gerekli

Content-Type: application/json

İstek Parametreleri

Parametre Tip Zorunlu Açıklama
customer_email string Evet Müşteri e-posta adresi
customer_name string Evet Müşterinin tam adı (ad soyad)
amount numeric Evet Transfer tutarı
currency string Evet Para birimi kodu (örn: TRY)
reference_id string Evet Benzersiz referans numarası
desc string Hayır İşlem açıklaması

Örnek İstek

curl -X POST 'https://api.example.com/api/whitelabel-c2b-wallet-transfer-otp' \
-H 'Authorization: Bearer your-token-here' \
-H 'Content-Type: application/json' \
-d '{
    "customer_email": "[email protected]",
    "customer_name": "Ahmet Yılmaz",
    "amount": 100.00,
    "currency": "TRY",
    "reference_id": "TRX123456",
    "desc": "Market alışverişi ödemesi"
}'

Başarılı Yanıt

{
    "statusCode": 200,
    "message": "Doğrulama kodu gönderildi",
    "requires_otp": true,
    "data": {
        "tracking_id": "abc123def456"
    }
}

2. Transfer Onay Endpoint

POST /api/whitelabel-c2b-wallet-transfer

Authorization: Bearer Token gerekli

Content-Type: application/json

İstek Parametreleri

Parametre Tip Zorunlu Açıklama
reference_id string Evet İlk adımda kullanılan referans numarası
otp_code string Evet SMS ile gönderilen doğrulama kodu

Örnek İstek

curl -X POST 'https://api.example.com/api/whitelabel-c2b-wallet-transfer' \
-H 'Authorization: Bearer your-token-here' \
-H 'Content-Type: application/json' \
-d '{
    "reference_id": "TRX123456",
    "otp_code": "123456"
}'

Başarılı Yanıt

{
    "statusCode": 200,
    "message": "Transfer başarıyla tamamlandı",
    "data": {
        "tracking_id": "abc123def456",
        "amount": 100.00,
        "currency": "TRY"
    }
}

Hata Yanıtları

401 - Yetkilendirme Hatası

{
    "statusCode": 401,
    "message": "Geçersiz token"
}

404 - Müşteri Bulunamadı

{
    "statusCode": 404,
    "message": "Müşteri bulunamadı"
}

409 - İşlem Devam Ediyor

{
    "statusCode": 409,
    "message": "İşlem zaten devam ediyor"
}

400 - Yetersiz Bakiye

{
    "statusCode": 400,
    "message": "Bakiye yetersizdir."
}

400 - OTP Hatası

{
    "statusCode": 400,
    "message": "Geçersiz doğrulama kodu. Kalan deneme hakkı: 2"
}

400 - OTP Süresi Doldu

{
    "statusCode": 400,
    "message": "Doğrulama süresi dolmuş"
}

Önemli Notlar

• Transfer işlemi iki adımda tamamlanır: OTP gönderimi ve doğrulama.

• OTP kodunun geçerlilik süresi 5 dakikadır.

• Yanlış OTP kodu için maksimum 3 deneme hakkı vardır.

• Her işlem için benzersiz bir reference_id kullanılmalıdır.

• Transfer öncesi müşteri bakiyesi kontrol edilir.

• Müşteri adı-soyadı bilgileri sistemdeki kayıtlarla eşleşmelidir.

• İşlemler anlık gerçekleşir ve geri alınamaz.

• Doğrulama kodları SMS ile müşterinin kayıtlı telefon numarasına gönderilir.

• Aynı reference_id ile tekrar işlem yapılamaz.

İşletmeden Müşteriye Transfer (B2C)

Bu endpoint, işletmenizin cüzdanından müşteri cüzdanına para transferi yapmanızı sağlar. Transfer işlemi anlık olarak gerçekleşir ve müşteriye otomatik bildirim gönderilir. Müşteri numarası, e-posta adresi veya telefon numarası ile transfer yapabilirsiniz. İşlem sırasında müşteri bilgileri ve adı-soyadı doğrulaması yapılır.

Endpoint Detayları

POST /api/whitelabel-b2c-wallet-transfer

Authorization: Bearer Token gerekli

Content-Type: application/json

İstek Parametreleri

Parametre Tip Zorunlu Açıklama
customer_number string Evet Müşteri numarası
customer_name string Evet Müşterinin tam adı (ad soyad)
lock_minute numeric Evet Yeni transfer yapılabilmesi için kilit süresi (dakika)
amount numeric Evet Transfer tutarı
currency string Evet Para birimi kodu (örn: TRY)
reference_id string Evet Benzersiz referans numarası
desc string Hayır İşlem açıklaması

Örnek İstek

curl -X POST 'https://panel.{{ config('app.lower_name') }}/api/whitelabel-b2c-wallet-transfer' \
-H 'Authorization: Bearer your-token-here' \
-H 'Content-Type: application/json' \
-d '{
    "customer_number": "123456789",
    "customer_name": "Ahmet Yılmaz",
    "lock_minute": 5,
    "amount": 100.00,
    "currency": "TRY",
    "reference_id": "TRX123456",
    "desc": "Ödeme iadesi"
}'

Başarılı Yanıt

{
    "statusCode": 200,
    "message": "Transfer başarıyla tamamlandı",
    "data": {
        "tracking_id": "abcdef123456",
        "amount": 100.00,
        "currency": "TRY"
    }
}

Hata Yanıtları

401 - Yetkilendirme Hatası

{
    "statusCode": 401,
    "message": "Geçersiz token"
}

422 - Validasyon Hatası

{
    "statusCode": 422,
    "message": "Geçersiz form verileri",
    "errors": {
        "customer_name": ["The customer name field is required"]
    }
}

404 - Müşteri Bulunamadı

{
    "statusCode": 404,
    "message": "Müşteri bulunamadı"
}

404 - Müşteri Bilgi Uyuşmazlığı

{
    "statusCode": 404,
    "message": "Müşteri bilgileri uyuşmuyor"
}

409 - İşlem Kilidi

{
    "statusCode": 409,
    "message": "Müşteri işlem yapmaya kilitli"
}

400 - Yetersiz Bakiye

{
    "statusCode": 400,
    "message": "Bakiye yetersiz"
}

Önemli Notlar

• İşlem için yeterli bakiye kontrolü yapılır.

• Her işlem için benzersiz bir reference_id kullanılmalıdır.

• İşlemler anlık gerçekleşir ve geri alınamaz.

• Müşteri adı-soyadı tam ve doğru girilmelidir.

• İşlem kilidi süresi boyunca aynı müşteriye yeni transfer yapılamaz.

Dekont Görüntüleme

Bu endpoint ile gerçekleştirilen işlemlere ait dekont bilgilerini PDF veya HTML formatında alabilirsiniz. İşlem tipine ve takip numarasına göre dekont detaylarına erişim sağlanır.

Endpoint Detayları

GET /api/get-dekont

Content-Type: application/json

Accept: application/pdf veya text/html

İstek Parametreleri

Parametre Tip Zorunlu Açıklama
tracking_id string Evet İşlem takip numarası
type string Evet İşlem tipi (c-to-b, b-to-c, c-to-b-link)

İşlem Tipleri

c-to-b

Müşteriden İşletmeye Transfer

b-to-c

İşletmeden Müşteriye Transfer

c-to-b-link

Ödeme Bağlantısı ile Transfer

{{--
--}} {{--

c-to-c

--}} {{--

Müşteriden Müşteriye Transfer

--}} {{--
--}} {{--
--}} {{--

deposit

--}} {{--

Para Yatırma İşlemi

--}} {{--
--}} {{--
--}} {{--

withdraw

--}} {{--

Para Çekme İşlemi

--}} {{--
--}}

Örnek İstekler

PDF Formatında Dekont

curl -X GET 'https://panel.{{ config('app.lower_name') }}/api/get-dekont?tracking_id=123456&type=c-to-b' \
-H 'Authorization: Bearer your-token-here' \
-H 'Accept: application/pdf'

HTML Formatında Dekont

curl -X GET 'https://panel.{{ config('app.lower_name') }}/api/get-dekont?tracking_id=123456&type=c-to-b' \
-H 'Authorization: Bearer your-token-here' \
-H 'Accept: text/html'

Önemli Notlar

  • Sadece tamamlanmış işlemlerin dekontları görüntülenebilir
  • İşlem tipinin doğru seçilmesi önemlidir
  • Dekontlar merchant'a ait işlemler için görüntülenebilir

Webhook Bildirimleri

Kullanım Senaryoları

E-ticaret Entegrasyonu

Ödeme başarılı olduğunda otomatik olarak siparişi onaylayabilir, stok güncellemesi yapabilir ve müşteriye bilgilendirme e-postası gönderebilirsiniz.

Servis Aktivasyonu

Başarılı ödemeden sonra satın alınan dijital ürün veya hizmetleri otomatik olarak aktif hale getirebilirsiniz.

Webhook Entegrasyonu

Webhook entegrasyonu için izlemeniz gereken adımlar:

  1. Webhook URL'inizi HTTPS protokolü ile hazırlayın
  2. Ödeme bağlantısı oluştururken webhook_callback_url parametresinde bu URL'i belirtin
  3. Gelen bildirimlerin hash değerini doğrulayın
  4. İşlem durumuna göre gerekli aksiyonları alın

Webhook İstek Yapısı

Sistemimiz, aşağıdaki formatta bir JSON verisi gönderecektir. Bu veriyi işleyerek gerekli aksiyonları alabilirsiniz. 

{
   "hash": "sha256(tracking_id + reference_id + merchant_key)",
   "tracking_id": "benzersiz-takip-id",
   "reference_id": "siparis-referans-no",
   "amount": 100.00,
   "transaction_status": "COMPLETED",
   "transaction_status_message": "Tamamlandı",
   "operation_time": "2024-01-06T10:30:00Z",
   "from_user": {
       "name": "Ad Soyad",
       "customer_number": "musteri-no",
       "phone": "telefon-no"
   },
   "status_code": 200,
   "status_message": "İşlem başarılı"
}

Hash Doğrulama

Gelen webhook bildiriminin geçerliliğini doğrulamak için hash değerini kontrol etmelisiniz: hash = SHA256(tracking_id + reference_id + merchant_key)

Güvenlik Kontrolleri

Webhook bildirimlerinin güvenliğini sağlamak için aşağıdaki kontrolleri mutlaka yapmalısınız:

  1. HTTPS protokolü kullanın
  2. Hash doğrulaması yapın
  3. İşlem tekrarını önlemek için tracking_id kontrolü yapın
  4. Zaman aşımı kontrolü yapın

Webhook Yanıt Formatı

Webhook bildirimini aldığınızda aşağıdaki formatta bir yanıt döndürmelisiniz: 

{
   "status": true
}

Önemli Notlar

  • Webhook URL'iniz HTTPS protokolünü desteklemelidir
  • İsteklere 30 saniye içinde yanıt vermelisiniz
  • Başarılı işlemlerde {"status": true} yanıtı dönmelisiniz
  • from_user alanı, kullanıcı bilgisi olmadığında null olabilir
  • Hatalı yanıt durumunda webhook tekrar denenecektir

Transaction Status Değerleri

Durum Açıklama
PENDING İşlem beklemede
COMPLETED İşlem tamamlandı
REJECTED İşlem reddedildi

Hata Kodları

API'den dönen hata kodları ve çözüm önerileri aşağıda listelenmiştir. Her hata durumu için önerilen çözümleri uygulayarak işlemlerinizi başarıyla gerçekleştirebilirsiniz.

Kod Mesaj Açıklama Çözüm Önerisi
401 Token bulunamadı Authorization header'ında token bilgisi eksik Authorization header'ında Bearer token gönderin
401 Geçersiz token Gönderilen token geçersiz veya tanınmıyor get-token endpointi ile yeni bir token alın
401 Geçersiz kimlik bilgileri app_key veya app_secret hatalı Merchant panelinizden app_key ve app_secret bilgilerinizi kontrol edin
422 Validasyon hatası İstek parametreleri eksik veya hatalı format Tüm zorunlu alanları doğru formatta gönderdiğinizden emin olun
409 İşlem zaten devam ediyor Aynı referans ID için işlem devam ediyor İşlemin tamamlanmasını bekleyin veya farklı bir reference_id kullanın
400 Bu referans numarasını kullanamazsınız Referans ID daha önce kullanılmış ve işlem tamamlanmış Her işlem için benzersiz bir reference_id oluşturun
404 Ödeme bağlantısı bulunamadı Belirtilen hash değeri ile ödeme bağlantısı yok Hash değerini kontrol edin veya yeni bir ödeme bağlantısı oluşturun
400 Ödeme bağlantısı zaten kullanılmıştır Bu ödeme bağlantısı daha önce kullanılmış Yeni bir ödeme bağlantısı oluşturun
400 Ödeme bağlantısının süresi dolmuştur Bağlantı 25 dakikadan eski Yeni bir ödeme bağlantısı oluşturun
400 Ödeme bağlantısının deneme hakkı dolmuştur Maksimum deneme sayısına ulaşıldı Yeni bir ödeme bağlantısı oluşturun
500 İşlem sırasında bir hata oluştu Sunucu taraflı beklenmeyen bir hata Tekrar deneyin veya destek ekibiyle iletişime geçin

Önemli Not

500 hata kodunda işlemin durumunu /status endpointi üzerinden kontrol etmenizi öneririz. İşlem başarılı olmuş olabilir ancak yanıt alınamadan bağlantı kopmuş olabilir.