Rubikpara

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
{
  "isSucceed": false,
  "errorCode": "1001",
  "errorMessage": "Kart numarası geçersiz",
  "conversationId": "conv-123456"
}
isSucceed: true
{
  "isSucceed": true,
  "orderId": "ORD-789",
  "conversationId": "conv-123456"
}
AlanTipAçıklama
isSucceedbooleanİşlemin başarılı olup olmadığı
errorCodestringHata kodu (yalnızca hata durumunda)
errorMessagestringHata açıklaması (yalnızca hata durumunda)
conversationIdstringİ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.

Banka yanıtlı başarılı cevap
{
  "isSucceed": true,
  "bankResponse": {
    "bankRrnNo": "012345678901",
    "bankTansId": "TXN123",
    "bankAuthCode": "AUTH01",
    "bankReturnCode": "00"
  }
}
AlanAçıklama
bankRrnNoBanka referans numarası (RRN)
bankTansIdBanka işlem ID'si
bankAuthCodeBanka onay kodu
bankReturnCodeBanka 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)

KodAçıklamaEN
0001Geçersiz üye iş yeri bilgisiInvalid merchant information
0002Yurtdışı kartlarından taksit yapılamazNot allowed international card instalment
0003Üye iş yeri durumu işlem almak için uygun değildirInvalid merchant status
0004Geçersiz işlem türü denenmektedirInvalid transaction type
0005Üye iş yerine ait POS bulunamadıVPos not found
0006POS bankası bulunamadıAcquire bank not found
0007Geçersiz tutar bilgisi mevcutturInvalid amount information
0008Geçersiz ödeme tipi mevcutturInvalid payment type

Oturum & Limit (0009–0016)

KodAçıklamaEN
0009Oturum bilgisi geçersizdirInvalid session information
0010Aylık tutar limitini aştınızMonthly limit amount exceeded
0011Aylık işlem limitini aştınızMonthly limit count exceeded
0012Günlük işlem limitini aştınızDaily limit count exceeded
0013Günlük tutar limitini aştınızDaily limit amount exceeded
0014Tam 3DS doğrulama yapılmadığı için işleme izin verilmemektedirHalf secure not allowed
0015Oturum bilgisi bulunamadıSession not found
0016Yurtdışı kartlarında işlem yapılamazInternational card not allowed

3D Secure Doğrulama (0017–0021, 0028–0029)

KodAçıklamaEN
00173DS işlemde tutar uyuşmazlığı mevcuttur3DS validation amount mismatch
00183DS işlemde kart oturum uyuşmazlığı mevcuttur3DS validation card token mismatch
00193DS işlem oturumu son bulmuştur3DS session expired
00203DS işlemde para birimi uyuşmazlığı mevcuttur3DS validation currency mismatch
00213DS işlemde işlem türü uyuşmazlığı mevcuttur3DS validation transaction type mismatch
0028Başarılı 3DS doğrulama yapılamadı3DS verification failed
0029Başarılı 3DS doğrulama bulunamadıNo successful 3DS verification found

Token & İşlem Kısıtlamaları (0022–0027, 0030)

KodAçıklamaEN
0022Kart token zaman aşımına uğramıştırCard token expired
0023Taksitli işlem yapılamazInstallment not allowed
00243DS harici işlem yapılamazNon-secure not allowed
0025Ön provizyon işlemi yapılamazPre-authorization not allowed
0026İşlem daha önceden iade edilmiştirTransaction already refunded
0027Geçersiz iade tutarı mevcutturInvalid return amount
0030Token bilgisi bulunamadıToken information could not be found
KodAçıklamaEN
1001Geçersiz işlem bilgisiInvalid transaction information
1002Girilen kart bilgileri hatalıdırThe card information entered is incorrect
1003Sistem 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ı

KodAçıklamaEN
5000İşlem başarılı gerçekleştiThe transaction was successful

Onay & Yetkilendirme Hataları

KodAçıklamaEN
5001İşlem onaylanmadıThe transaction has not been approved
5002İşlem onaylanmadı (banka ile iletişim)Transaction not approved (contact bank)
5003Karta el koyulmuşturThe card has been confiscated

Kart Durum Hataları

KodAçıklamaEN
5004Kredi kartının geçerlilik süresi bitmiştirCredit card validity period has expired
5005Kredi kartı limiti yetersizdirCredit card limit is not sufficient
5006Kart e-ticaret işlemlerine kapalıdırCard is closed to e-commerce transactions
5007Sanal limit yetersizdirVirtual limit is not sufficient
5008Kart kapalıdırYour card is closed
5011Kredi kartı blokesi mevcutturCredit card blocking is available

3D Secure & Güvenlik Hataları

KodAçıklamaEN
50093DS şifresi doğrulanamadıFailed to verify 3DS secure password
5010Kredi kartının 3DS tanımı bulunmamaktadırCredit card does not have 3DS definition
5012Güvenlik kodu hatalıdırThe 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.

On this page