Hatalar
HTTP durum kodları
| Kod | Anlamı | İmzalı |
|---|---|---|
200 | İstek işlendi. Sonuç result.successful alanındadır; sağlayıcının reddettiği bir ödeme, iade, iptal ya da kart saklama ve bankanın reddettiği banka hesabı kimlik bilgileri de 200 ile ve successful: false olarak döner. | evet |
401 | API anahtarı ya da imza geçersiz. İstek işlenmedi. | hayır |
403 | Çalışma alanı şu an işlem yapamıyor ya da ucun bağlı olduğu modül kapalı. İstek işlenmedi. | evet |
404 | Güncellenen, silinen, iade ya da iptal edilen kaydın token'ı yok ya da başka bir çalışma alanına ait. | evet |
422 | Gövde doğrulamadan ya da bir iş kuralından geçmedi. İstek işlenmedi; sağlayıcıya bir şey gönderilmedi. | evet |
429 | İstek sınırı aşıldı. İstek işlenmedi. | evet |
500 | Gateway'de beklenmeyen bir hata oluştu. | evet |
Yanıtı okurken önce durum koduna bakın. Hata yanıtlarının bir kısmı imzalıdır; imzalı olması onu bir işlem sonucuna çevirmez. Adresteki çalışma alanı kimliği bulunamazsa ya da uç adresi yanlışsa 404 imzasız döner.
Hata yanıtı
Bütün hata yanıtları aynı biçimdedir:
{
"result": {
"successful": false,
"message": "Çalışma alanınızda bu modül kapalı; açtırmak için bizimle iletişime geçin."
}
}
401
İmzasızdır.
result.message | Neden |
|---|---|
Geçersiz API anahtarı. | X-Api-Key eksik ya da adresteki çalışma alanına ait değil. |
İmzanın zaman damgası eksik ya da izin verilen aralığın dışında. | X-Timestamp eksik, yalnızca rakamdan oluşmuyor ya da sunucu saatinden 5 dakikadan fazla uzak. |
İmza doğrulanamadı. | X-Signature eksik ya da zaman damgası, metot, yol ve gövdeyle tutmuyor. |
403
result.message | Neden |
|---|---|
Çalışma alanınızın ödenmemiş bakiyesi bulunduğu için işlem yapılamıyor. | Çalışma alanının vadesi geçmiş bakiyesi var. |
Çalışma alanınızda bu modül kapalı; açtırmak için bizimle iletişime geçin. | Ucun bağlı olduğu modül çalışma alanınızda açık değil. |
Bakiye engeli bütün uçlar için geçerlidir. Modül engeli uca göre değişir: kartı doğrudan çeken iki uç Api modülünü, sipariş, ödeme linki, abonelik, kayıtlı kart ve banka hareketi uçları yalnızca kendi modülünü ister; iade, iptal ve ödeme sorgusu modül istemez.
| Uçlar | Gereken modül |
|---|---|
secure-payment, regular-payment | Api |
refund-payment, cancel-payment, retrieve-payments, retrieve-bin | Yok |
*-order* | Siparişler |
*-payment-link*, retrieve-link-payments | Link ile Ödeme |
*-subscription* | Abonelikler |
*-saved-card* | Kayıtlı Kartlar |
retrieve-banks, *-bank-account*, retrieve-bank-transactions | Banka Hareketleri |
Sipariş, ödeme linki ve abonelik ödemeleri ödemehub'ın ödeme sayfasında alındığı için Api modülü kapalıyken de iade ve iptal edilir, retrieve-payments ile sorulur.
Modülleri panelden siz açmazsınız. Canlı adreste (app.odemehub.com) yeni bir çalışma alanında modüllerin hepsi kapalıdır; anlaştığınız modülleri ödemehub ekibi açar. Sandbox'ta (sandbox.odemehub.com) bütün modüller baştan açıktır. Bkz. Modüller.
404
| Uç | result.message |
|---|---|
refund-payment, cancel-payment | Bu işlem bulunamadı. |
update-order/{token} | Bu sipariş bulunamadı. |
update-payment-link/{token} | Bu ödeme linki bulunamadı. |
update-subscription/{token} | Bu abonelik bulunamadı. |
update-saved-card/{token}, delete-saved-card/{token} | Bu kayıtlı kart bulunamadı. |
update-bank-account/{token}, delete-bank-account/{token} | Bu banka hesabı bulunamadı. |
Sorgu uçları (retrieve-payments, retrieve-orders, retrieve-payment-links, retrieve-link-payments, retrieve-subscriptions, retrieve-saved-cards, retrieve-bank-accounts, retrieve-bank-transactions) 404 dönmez: eşleşen kayıt yoksa liste boştur.
500
{
"result": {
"successful": false,
"message": "Beklenmeyen bir hata oluştu. Lütfen daha sonra yeniden deneyin."
}
}
Doğrulama hataları (422)
{
"result": {
"successful": false,
"message": "Tutar 100 veya 100.10 biçiminde olmalıdır; kuruş basamağı noktayla ayrılır.",
"errors": {
"transaction.amount": [
"Tutar 100 veya 100.10 biçiminde olmalıdır; kuruş basamağı noktayla ayrılır."
]
}
}
}
| Alan | Açıklama |
|---|---|
result.message | İlk hatanın mesajı. Birden fazla hata varsa sonuna (and N more errors) eklenir. |
result.errors | Alan yolu (ör. transaction.amount, order.items.0.name, customer.billing_address.email, token) → mesaj listesi. |
Doğrulama hatası alan istek işlenmez. Alanı düzeltip isteği yeniden gönderebilirsiniz.
Bazı iş kuralları da 422 olarak ilgili alanda döner; örneğin iade edilemeyen bir ödeme transaction.token, ödenmiş bir sipariş token, kart saklamayan bir ödeme hesabı payment_provider_token alanında reddedilir. Uca özel mesajlar her uç sayfasının Hatalar bölümündedir.
Ağ hataları
İstek gönderildikten sonra yanıt alınamadıysa (zaman aşımı, bağlantı kopması) işlemin gateway'de gerçekleşip gerçekleşmediği bilinmez.
- Ödeme (
secure-payment,regular-payment): Aynı ödeme isteğini tekrar göndermek yeni bir ödeme denemesidir. Önceretrieve-paymentsile o referanstaki son ödemeyi sorun. create-order,create-subscription,create-payment-link: Bu uçlar idempotent değildir; aynıreferenceile tekrar gönderilen istek ikinci bir kayıt ve yeni bir token açar. Önce ilgiliretrieve-*ucunureferenceile sorun; o referanstaki bütün kayıtlar döner. Bkz. Aynı referansla tekrarlanancreate-*istekleri.- İade ve iptal: Ödemenin güncel
payment_statusdeğeriniretrieve-paymentsile sorun.
SDK istisnaları
| PHP, Java | Node.js, Python | Durum |
|---|---|---|
AuthenticationException | AuthenticationError | 401. |
ForbiddenException | ForbiddenError | 403. |
NotFoundException | NotFoundError | 404. |
ValidationException | ValidationError | 422. errors alanı result.errors'tır. |
RateLimitException | RateLimitError | 429. retryAfter (Python'da retry_after) yanıttaki Retry-After başlığından okunur: beklenecek saniye. |
UnexpectedResponseException | UnexpectedResponseError | Diğer kodlar (500 dahil) ya da okunamayan yanıt. Durum kodu istisnadadır. |
SignatureException | SignatureError | Yanıtın imzası tutmadı; içeriğe güvenmeyin. |
TransportException | TransportError | Gateway'e ulaşılamadı; sonuç bilinmiyor. |
Hepsi OdemehubException (PHP, Java) ya da OdemehubError (Node.js, Python) sınıfından türer. 200 yanıtları istisna değildir; result.successful değerini kontrol edin.