Genel Bilgiler

Bu rehber, Fincraft Payment API ile test ortamında ilk entegrasyonunuzu tamamlamanız için gereken adımları içerir. Kimlik doğrulama tamamlandıktan sonra ödeme, sorgulama ve iptal/iade endpoint’lerine geçebilirsiniz.


Test Base URL	`https://api-test.fincraft.com.tr`
API prefix	`/api/v1`
Kimlik doğrulama	Bearer Token
Content-Type	`application/json`
Encoding	`UTF-8`

Test ortamı gerçek para hareketi gerçekleştirmez. Canlı ortama geçmeden önce tüm akışları api-test.fincraft.com.tr üzerinden doğrulayın.

Kimlik doğrulama

API erişimi için önce POST /auth/login ile Bearer Token alınır. İstekte API Key ve API Secret kullanılır.

API Key ve Secret'ı birleştirin

Değerleri apiKey:apiSecret formatında birleştirin.

API_KEY:API_SECRET

Base64 encode edin

echo -n "apiKeyBilginiz:apiSecretBilginiz" | base64

curl -X POST https://api-test.fincraft.com.tr/auth/login \
  -H "Authorization: Basic BASE64_ENCODED_VALUE" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json"

accessToken ile istek atın

Authorization: Bearer ACCESS_TOKEN
Content-Type: application/json

{
  "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

Parametre	Tip	Açıklama
`accessToken`	String	Sonraki tüm API isteklerinde kullanılacak JWT token

Detaylı kimlik doğrulama adımları ve hata senaryoları için Kimlik Doğrulama sayfasına bakın.

İlk ödeme isteği

Token aldıktan sonra non-secure ödeme akışıyla test ödemesi oluşturabilirsiniz:

curl -X POST https://api-test.fincraft.com.tr/api/v1/payments/card \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "referenceId": "550e8400-e29b-41d4-a716-446655440000",
    "amount": 100,
    "finalAmount": 100,
    "walletAmount": 0,
    "installment": 1,
    "clientIpAddress": "192.168.1.1",
    "currency": "TRY",
    "transactionType": "AUTH",
    "card": {
      "cardHolderName": "Test Kullanıcı",
      "cardNumber": "5218487962459752",
      "expireMonth": "09",
      "expireYear": "28",
      "cvc": "000"
    },
    "products": [
      {
        "name": "Test Ürün",
        "externalId": "PROD-001",
        "price": 100
      }
    ]
  }'

Test kart numaraları ve senaryolar için Test Kartları sayfasını kullanın. Gerçek kart bilgisi test ortamında göndermeyin.

HTTP durum kodları

Kod	Açıklama
`200`	İstek başarılı
`400`	Geçersiz istek veya validasyon hatası
`401`	Kimlik doğrulama başarısız
`403`	Erişim reddedildi
`404`	Kayıt bulunamadı
`500`	Sunucu hatası

Kimlik doğrulama hataları

Durum	Olası neden
`401 Unauthorized`	API Key veya Secret hatalı
Geçersiz Authorization header	Basic encode formatı hatalı
Bearer token eksik	Ödeme isteğinde token gönderilmedi
Token süresi doldu	Yeniden `POST /auth/login` çağrısı gerekir

Güvenlik önerileri

API Secret değerini frontend kodunda veya public repolarda saklamayın
Kimlik bilgilerini ortam değişkeni veya secret manager üzerinden yönetin
accessToken değerini loglara yazmayın
Canlı ortamda yalnızca HTTPS kullanın

Sonraki adımlar

Non-Secure Ödeme

Kart ile doğrudan ödeme oluşturma endpoint’i.

3D Secure

3D Secure başlatma ve tamamlama akışı.

İşlem Sorgulama

Order ID veya Reference ID ile ödeme detayı.

Hata Kodları

Tüm sistem ve banka hata kodları.

Başlangıç

Genel

Non-Secure Ödeme

3D Secure Ödeme

Ortak Ödeme/Link/QR

Sorgulamalar

İptal/İade

Provizyon

Ürün İşlemleri

Bayi İşlemleri

APM (Alternative Payment Method) ile Ödeme

Kimlik doğrulama

İlk ödeme isteği

HTTP durum kodları

Kimlik doğrulama hataları

Güvenlik önerileri

Sonraki adımlar

Non-Secure Ödeme

3D Secure

İşlem Sorgulama

Hata Kodları

​Kimlik doğrulama

​Login yanıtı

​İlk ödeme isteği

​HTTP durum kodları

​Kimlik doğrulama hataları

​Güvenlik önerileri

​Sonraki adımlar

Non-Secure Ödeme

3D Secure

İşlem Sorgulama

Hata Kodları

Kimlik doğrulama

Login yanıtı

İlk ödeme isteği

HTTP durum kodları

Kimlik doğrulama hataları

Güvenlik önerileri

Sonraki adımlar