Kimlik Doğrulama ve API Anahtarları

API, bearer kimlik doğrulaması kullanır. Anahtarı her isteğin Authorization başlığında gönderin:

curl https://pay.example.com/v1/payment_intents?limit=3 \
  -H "Authorization: Bearer sk_sandbox_YOUR_KEY"

Eksik, hatalı biçimli, iptal edilmiş veya uygun olmayan bir anahtar, error.type = authentication_error ile 401 döndürür. Canlı kurulumlarda her zaman HTTPS kullanın.

Anahtar türleri

Anahtarları üye işyeri panelinde Geliştiriciler → API anahtarları altında oluşturun, listeleyin ve iptal edin (ya da bir panel oturumundan /v1/api_keys ile). Gizli anahtar yalnızca oluşturulurken bir kez gösterilir. Bir anahtarı iptal etmek anında geçerli olur; anahtarı değiştirmek için yenisini oluşturun, devreye alın, ardından eskisini iptal edin.

Kısıtlı anahtarların kapsamları

Kısıtlı bir anahtar, <resource>:read veya <resource>:write biçiminde kapsamlar taşır; write, read yetkisini de içerir. Anahtarın kapsamları dışındaki bir çağrı, error.type = permission_error ile 403 döndürür.

Kaynaklar: payment_intents, installment_plans, refunds, disputes, balance, balance_transactions, topups, payouts, settlement_accounts, webhook_endpoints, events, customers, payment_methods, request_logs, reporting, products.

Örneğin bir iade servisi refunds:write ve payment_intents:read kapsamlarına, bir mutabakat işi balance_transactions:read ve payouts:read kapsamlarına ihtiyaç duyar.

API sürümü

Hesabınız belirli bir API sürümüne sabitlenmiştir. İstek başına PF-Version: YYYY-MM-DD başlığıyla bunu geçersiz kılabilirsiniz; kullanılan sürüm yanıttaki PF-Version başlığında geri döndürülür.

IP izin listesi

Gizli ve kısıtlı anahtarlar, kaydettiğiniz sunucu IP adresleriyle sınırlandırılabilir. Yayınlanabilir anahtarlar ve panel oturumları bu listeye tabi değildir.

1. Üye işyeri panelinde Ayarlar → İzinli IP adresleri bölümünü açın.
2. Tek bir IPv4 veya IPv6 adresi ya da bir CIDR bloğu ekleyin (IPv4 için en fazla /8, IPv6 için en fazla /16 genişliğinde). Bir kayıt tek bir API anahtarına bağlanabilir; kendi kayıtları olan bir anahtar yalnızca bu adreslerden kabul edilir, diğer tüm anahtarlar hesap genelindeki kayıtlardan kabul edilir.
3. Yeni kayıtlar, ödeme kuruluşu onaylayana kadar pending durumundadır. Bir kaydı silmek anında geçerli olur.

İzin verilmeyen bir adresten gelen istek 403 ip_not_allowed ile reddedilir. Sandbox kurulumlarında ihlal yalnızca Geliştiriciler → İstek kayıtları altında uyarı olarak kaydedilir; canlı kurulumlarda ise istek reddedilir. Hiç adres kaydedilmemişken liste uygulanıyorsa her sunucu isteği reddedilir; bu nedenle canlıya geçmeden önce adreslerinizi kaydedin.

Sunucularınız bir proxy veya NAT arkasındaysa iç adresi değil, genel çıkış adresini kaydedin.

Geri dönüş (callback) adresi ve web sitesi kaydı

Ödeme kuruluşlarının, ödemeyi nerede aldığınızı ve müşterilerin ve bildirimlerin nereye yönlendirildiğini bilmesi gerekir. Bunları Ayarlar → Web siteleri ve geri dönüş adresleri altında kaydedin:

• Ödeme aldığınız web siteleri (alan adları, canlıda https). Doğrulama DNS TXT kaydı veya manuel inceleme ile yapılır.
• 3-D Secure return_url değeri ve webhook uç nokta adresi olarak kullandığınız geri dönüş (callback) adresleri. Bir adres ya exact (şema, ana makine, port ve yol) ya da yol segmenti sınırında prefix ile eşleşir (/pay, /pay ve /pay/done ile eşleşir; /payment ile eşleşmez).

Onaylı bir web sitesinde bulunan veya kayıtlı bir geri dönüş adresiyle eşleşen bir return_url ya da webhook adresi kabul edilir; aksi halde çağrı 400 return_url_not_allowed (param: return_url) veya 400 webhook_url_not_allowed (param: url) ile başarısız olur ve kayıtsız bir web sitesinden yapılan ödeme 403 website_not_registered ile başarısız olur. IP adreslerinde olduğu gibi, eklemeler onay bekler, silmeler anında uygulanır ve canlı kurulumların reddettiği durumlarda sandbox kurulumları uyarı verir.

Onay süresini hesaba katın: üretim alan adınızı, return_url adresinizi ve sunucu IP adreslerinizi canlıya çıkıştan çok önce kaydedin.

Burada karşılaşabileceğiniz hatalar

Tam liste hatalar kılavuzundadır.