Hata Yönetimi
PF Gateway API yanıtlarında hata kontrolü ve hata kodlarının yönetimi.
Tüm API yanıtları ortak bir hata yapısı kullanır. Bu sayede hata durumlarını tutarlı şekilde yönetebilirsiniz.
HTTP 200 dönen yanıtlar bile iş mantığı hatası içerebilir. Her zaman yanıt gövdesindeki isSucceed alanını kontrol edin.
Yanıt Yapısı
Her API yanıtında isSucceed alanı işlemin başarılı olup olmadığını belirtir.
{
"isSucceed": false,
"errorCode": "1001",
"errorMessage": "Kart numarası geçersiz",
"conversationId": "conv-123456"
}{
"isSucceed": true,
"orderId": "ORD-789",
"conversationId": "conv-123456"
}| Alan | Tip | Açıklama |
|---|---|---|
isSucceed | boolean | İşlemin başarılı olup olmadığı |
errorCode | string | Hata kodu (yalnızca hata durumunda) |
errorMessage | string | Hata açıklaması (yalnızca hata durumunda) |
conversationId | string | İstek takip kimliği |
Hata Kontrolü
Her API çağrısından sonra öncelikle isSucceed alanını kontrol edin.
const response = await fetch('/v1/Payments/provision', {
method: 'POST',
headers: { /* ... */ },
body: JSON.stringify(requestBody)
});
const data = await response.json();
if (!data.isSucceed) {
console.error(`Hata: [${data.errorCode}] ${data.errorMessage}`);
// Hatayı kullanıcıya gösterin veya loglayın
return;
}
// Başarılı işlem
console.log(`Sipariş oluşturuldu: ${data.orderId}`);var response = await httpClient.PostAsJsonAsync("/v1/Payments/provision", request);
var result = await response.Content.ReadFromJsonAsync<ProvisionResponse>();
if (!result.IsSucceed)
{
logger.LogError("Hata: [{Code}] {Message}", result.ErrorCode, result.ErrorMessage);
throw new PaymentException(result.ErrorCode, result.ErrorMessage);
}
// Başarılı işlem
logger.LogInformation("Sipariş oluşturuldu: {OrderId}", result.OrderId);import requests
response = requests.post(
f"{base_url}/v1/Payments/provision",
headers=headers,
json=request_body
)
data = response.json()
if not data["isSucceed"]:
print(f"Hata: [{data['errorCode']}] {data['errorMessage']}")
raise PaymentError(data["errorCode"], data["errorMessage"])
# Başarılı işlem
print(f"Sipariş oluşturuldu: {data['orderId']}")$response = $httpClient->post('/v1/Payments/provision', [
'headers' => $headers,
'json' => $requestBody,
]);
$data = json_decode($response->getBody()->getContents(), true);
if (!$data['isSucceed']) {
error_log(sprintf('Hata: [%s] %s', $data['errorCode'], $data['errorMessage']));
throw new PaymentException($data['errorCode'], $data['errorMessage']);
}
// Başarılı işlem
echo 'Sipariş oluşturuldu: ' . $data['orderId'];Banka Yanıt Bilgileri
Provision, Reverse ve Return işlemlerinde bankResponse objesi ek bilgiler içerir.
{
"isSucceed": true,
"bankResponse": {
"bankRrnNo": "012345678901",
"bankTansId": "TXN123",
"bankAuthCode": "AUTH01",
"bankReturnCode": "00"
}
}| Alan | Açıklama |
|---|---|
bankRrnNo | Banka referans numarası (RRN) |
bankTansId | Banka işlem ID'si |
bankAuthCode | Banka onay kodu |
bankReturnCode | Banka dönüş kodu (00 = başarılı) |
Destek talebi açarken conversationId ve bankRrnNo bilgilerini paylaşmanız sorun çözümünü hızlandırır.
Hata Kodları Referansı
Üye İş Yeri & Konfigürasyon (0001–0008)
| Kod | Açıklama | EN |
|---|---|---|
0001 | Geçersiz üye iş yeri bilgisi | Invalid merchant information |
0002 | Yurtdışı kartlarından taksit yapılamaz | Not allowed international card instalment |
0003 | Üye iş yeri durumu işlem almak için uygun değildir | Invalid merchant status |
0004 | Geçersiz işlem türü denenmektedir | Invalid transaction type |
0005 | Üye iş yerine ait POS bulunamadı | VPos not found |
0006 | POS bankası bulunamadı | Acquire bank not found |
0007 | Geçersiz tutar bilgisi mevcuttur | Invalid amount information |
0008 | Geçersiz ödeme tipi mevcuttur | Invalid payment type |
Oturum & Limit (0009–0016)
| Kod | Açıklama | EN |
|---|---|---|
0009 | Oturum bilgisi geçersizdir | Invalid session information |
0010 | Aylık tutar limitini aştınız | Monthly limit amount exceeded |
0011 | Aylık işlem limitini aştınız | Monthly limit count exceeded |
0012 | Günlük işlem limitini aştınız | Daily limit count exceeded |
0013 | Günlük tutar limitini aştınız | Daily limit amount exceeded |
0014 | Tam 3DS doğrulama yapılmadığı için işleme izin verilmemektedir | Half secure not allowed |
0015 | Oturum bilgisi bulunamadı | Session not found |
0016 | Yurtdışı kartlarında işlem yapılamaz | International card not allowed |
3D Secure Doğrulama (0017–0021, 0028–0029)
| Kod | Açıklama | EN |
|---|---|---|
0017 | 3DS işlemde tutar uyuşmazlığı mevcuttur | 3DS validation amount mismatch |
0018 | 3DS işlemde kart oturum uyuşmazlığı mevcuttur | 3DS validation card token mismatch |
0019 | 3DS işlem oturumu son bulmuştur | 3DS session expired |
0020 | 3DS işlemde para birimi uyuşmazlığı mevcuttur | 3DS validation currency mismatch |
0021 | 3DS işlemde işlem türü uyuşmazlığı mevcuttur | 3DS validation transaction type mismatch |
0028 | Başarılı 3DS doğrulama yapılamadı | 3DS verification failed |
0029 | Başarılı 3DS doğrulama bulunamadı | No successful 3DS verification found |
Token & İşlem Kısıtlamaları (0022–0027, 0030)
| Kod | Açıklama | EN |
|---|---|---|
0022 | Kart token zaman aşımına uğramıştır | Card token expired |
0023 | Taksitli işlem yapılamaz | Installment not allowed |
0024 | 3DS harici işlem yapılamaz | Non-secure not allowed |
0025 | Ön provizyon işlemi yapılamaz | Pre-authorization not allowed |
0026 | İşlem daha önceden iade edilmiştir | Transaction already refunded |
0027 | Geçersiz iade tutarı mevcuttur | Invalid return amount |
0030 | Token bilgisi bulunamadı | Token information could not be found |
| Kod | Açıklama | EN |
|---|---|---|
1001 | Geçersiz işlem bilgisi | Invalid transaction information |
1002 | Girilen kart bilgileri hatalıdır | The card information entered is incorrect |
1003 | Sistem hatası | System error |
1003 hatası alıyorsanız lütfen destek ekibiyle iletişime geçin. Bu hata genellikle geçici bir sistem sorununa işaret eder.
Başarılı
| Kod | Açıklama | EN |
|---|---|---|
5000 | İşlem başarılı gerçekleşti | The transaction was successful |
Onay & Yetkilendirme Hataları
| Kod | Açıklama | EN |
|---|---|---|
5001 | İşlem onaylanmadı | The transaction has not been approved |
5002 | İşlem onaylanmadı (banka ile iletişim) | Transaction not approved (contact bank) |
5003 | Karta el koyulmuştur | The card has been confiscated |
Kart Durum Hataları
| Kod | Açıklama | EN |
|---|---|---|
5004 | Kredi kartının geçerlilik süresi bitmiştir | Credit card validity period has expired |
5005 | Kredi kartı limiti yetersizdir | Credit card limit is not sufficient |
5006 | Kart e-ticaret işlemlerine kapalıdır | Card is closed to e-commerce transactions |
5007 | Sanal limit yetersizdir | Virtual limit is not sufficient |
5008 | Kart kapalıdır | Your card is closed |
5011 | Kredi kartı blokesi mevcuttur | Credit card blocking is available |
3D Secure & Güvenlik Hataları
| Kod | Açıklama | EN |
|---|---|---|
5009 | 3DS şifresi doğrulanamadı | Failed to verify 3DS secure password |
5010 | Kredi kartının 3DS tanımı bulunmamaktadır | Credit card does not have 3DS definition |
5012 | Güvenlik kodu hatalıdır | The security code entered is incorrect |
En İyi Uygulamalar
isSucceed Kontrolü
HTTP 200 dönen yanıtlar bile iş mantığı hatası içerebilir. Her yanıtta mutlaka isSucceed alanını kontrol edin.
conversationId Takibi
Her isteğe benzersiz bir conversationId atayarak hata durumlarında sorunları kolayca izleyin.
Hata Loglama
errorCode ve errorMessage değerlerini sisteminizde kayıt altına alın. Sorun giderme sürecini büyük ölçüde hızlandırır.
Retry Mekanizması
Ağ hatalarında belirli süre sonra tekrar deneyin, ancak her denemede yeni bir Nonce ve Signature oluşturun.
İdempotentlik
Aynı conversationId ile yapılan istekler aynı sonucu döner. Bu sayede mükerrer işlem riski ortadan kalkar.
Hata Kategorileri
0xxx iş mantığı, 1xxx sistem, 5xxx banka hatalarıdır. Hata kodunun prefix'ine göre farklı stratejiler uygulayın.