# أكواد أخطاء الدفع (/ar/integrate/errors/payment-error-codes)

كل قيمة لـ `lastPaymentError.code`، متجمّعة حسب المجال. الـ URL بتاع كل إدخال هو قيمة `lastPaymentError.docUrl`.

الصفحة دي هي وجهة كل `lastPaymentError.docUrl` اللي كوده جه من `PaymentErrorCode`. الإرساء (anchors) هنا بيطابق قيمة `code`، فـ `https://docs.xpay.app/integrate/errors/payment-error-codes#card_declined` بيوصلك مباشرةً للصف اللي تحت.

لسبب الرفض المحدّد للبنك المُصدِر على دفع بالبطاقة (`lastPaymentError.declineCode`)، شوف [أكواد الرفض](/integrate/errors/decline-codes). للنموذج ونمط المعالِج، شوف [أخطاء الدفع](/integrate/errors/payment-errors).

## التحقّق من البطاقة [#التحقّق-من-البطاقة]

العميل دخّل بيانات بطاقة ما بتعدّيش التحقّق الأساسي. `paymentMethodType: "card"`. الإرشاد: `confirm_card_data` (خلّي العميل يدخّل بياناته تاني).

### `invalid_number` [#invalid_number]

رقم البطاقة مش بصيغة صالحة (طول غلط، أو فشل في فحص Luhn، إلخ).

### `invalid_expiry_month` [#invalid_expiry_month]

شهر انتهاء الصلاحية مش قيمة صالحة.

### `invalid_expiry_year` [#invalid_expiry_year]

سنة انتهاء الصلاحية مش قيمة صالحة.

### `invalid_cvc` [#invalid_cvc]

الـ CVC/CVV مش بصيغة صالحة (طول غلط).

### `incorrect_number` [#incorrect_number]

رقم البطاقة عدّى التحقّق من الصيغة لكن البنك المُصدِر بيقول إنه غلط.

### `incorrect_cvc` [#incorrect_cvc]

الـ CVC/CVV ما بيطابقش اللي عند البنك المُصدِر.

### `incorrect_zip` [#incorrect_zip]

الرمز البريدي ما بيطابقش عنوان الفوترة المسجَّل عند البنك المُصدِر.

### `expired_card` [#expired_card]

البطاقة منتهية. العميل محتاج بطاقة تانية.

## المعالجة [#المعالجة]

أخطاء رجعت أثناء محاولة الـ charge الفعلية. خليط من أخطاء البطاقة ونتائج المعالج.

### `card_declined` [#card_declined]

البنك المُصدِر رفض العملية من غير سبب أكثر تحديدًا. اقرنه بـ `lastPaymentError.declineCode` لسبب مستوى البنك المُصدِر لما يكون موجود.

### `processing_error` [#processing_error]

حصل خطأ أثناء المعالجة، لكن البنك المُصدِر ما رفضش العملية تمامًا. عادةً مؤقت. الإرشاد: `try_again_later`.

### `authentication_required` [#authentication_required]

البنك المُصدِر بيتطلّب مصادقة إضافية (3D Secure) لإتمام الدفع. العميل محتاج يحاول تاني ويكمّل التحدّي.

## الحساب والرصيد [#الحساب-والرصيد]

### `insufficient_funds` [#insufficient_funds]

بطاقة العميل ما عندهاش رصيد متاح كفاية للعملية.

### `card_velocity_exceeded` [#card_velocity_exceeded]

البطاقة اتستخدمت مرات كتير في فترة قصيرة. الإرشاد: `try_again_later`.

## الاحتيال والمخاطر [#الاحتيال-والمخاطر]

البنك المُصدِر رفض العملية لأسباب مخاطر. الإرشاد: `do_not_try_again` للتلاتة.

### `fraudulent` [#fraudulent]

البنك المُصدِر (أو مؤشرات مخاطر XPay نفسها) علّم الدفع كاحتيالي. ما تعيدش المحاولة؛ المحاولة دي مسجّلة عند البنك المُصدِر.

### `stolen_card` [#stolen_card]

البطاقة اتبلّغ عنها مسروقة. ما تعيدش المحاولة. بلّغ فريق الدعم بتاعك لو المعدّل غير عادي.

### `lost_card` [#lost_card]

البطاقة اتبلّغ عنها ضايعة.

## المعالج [#المعالج]

### `issuer_not_available` [#issuer_not_available]

XPay ما قدرش يوصل للبنك المُصدِر للبطاقة. الإرشاد: `try_again_later`.

### `processor_timeout` [#processor_timeout]

معالج الدفع ما ردّش في الوقت المناسب. الطلب ممكن يكون نجح على ناحيتهم؛ راجع لوحة التحكم قبل إعادة المحاولة. الإرشاد: `try_again_later`.

### `processor_declined` [#processor_declined]

المعالج رفض العملية لسبب ما اتترجمش لكود أكثر تحديدًا.

## الطلب [#الطلب]

### `amount_too_large` [#amount_too_large]

مبلغ العملية بيتعدّى الحد الأقصى المسموح لطريقة الدفع دي.

### `amount_too_small` [#amount_too_small]

مبلغ العملية تحت الحد الأدنى المطلوب لطريقة الدفع دي.

### `currency_not_supported` [#currency_not_supported]

العملة مش مدعومة من طريقة الدفع دي.

### `duplicate_transaction` [#duplicate_transaction]

المعالج اكتشف معاملة مشابهة مؤخرًا. استنى، بعدين أعِد المحاولة.

## الاسترداد [#الاسترداد]

### `charge_already_refunded` [#charge_already_refunded]

حاولت تسترد عملية دفع اتردّت بالكامل بالفعل.

### `charge_disputed` [#charge_disputed]

حاولت تسترد عملية دفع تحت نزاع حاليًا. عمليات الدفع المتنازَع عليها خارج تحكّمك لحد ما النزاع يتحل.

### `refund_disputed_payment` [#refund_disputed_payment]

حاولت تسترد عملية دفع اتنازِع عليها. نفس القاعدة.

## طرق الدفع غير البطاقية [#طرق-الدفع-غير-البطاقية]

### `payment_declined` [#payment_declined]

طريقة دفع غير بطاقية (BNPL، أو كشك، أو محفظة، أو تحويل بنكي) رفضت الدفع. التفاصيل بتعتمد على المزوّد؛ راجع لوحة التحكم للتفاصيل.

## العام [#العام]

لما المعالج أو البنك المُصدِر ما يرجّعش سبب محدّد، XPay بيرجع لواحد من دول.

### `generic_decline` [#generic_decline]

الدفع اترفض من غير سبب محدّد.

### `do_not_honor` [#do_not_honor]

البنك المُصدِر رجّع "do not honor"، اللي عادةً معناه إن العميل المفروض يتواصل مع بنكه. الإرشاد: `try_again_later`.

### `call_issuer` [#call_issuer]

البنك المُصدِر قال للعميل يكلّمه. اعرض للعميل رسالة واضحة "اتواصل مع بنكك وحاول تاني".

## رايح فين بعد كده [#رايح-فين-بعد-كده]

<Cards>
  <Card icon="<Ban />" title="أكواد الرفض" href="/integrate/errors/decline-codes">
    سبب الرفض للبنك المُصدِر في `lastPaymentError.declineCode`. أكثر تفصيلًا من الأكواد اللي في الصفحة
    دي.
  </Card>

  <Card icon="<CreditCard />" title="أخطاء الدفع" href="/integrate/errors/payment-errors">
    النموذج: إزاي `lastPaymentError` متشكّل وإزاي تتعامل معاه.
  </Card>

  <Card icon="<Hash />" title="أكواد أخطاء API" href="/integrate/errors/api-error-codes">
    المرجع التاني: الأكواد اللي بترجع في `error.code` على استدعاء API فاشل.
  </Card>

  <Card icon="<TriangleAlert />" title="أخطاء API" href="/integrate/errors/api-errors">
    مغلّف خطأ الـ API المتزامن.
  </Card>

  <Card icon="<Layers />" title="مقدمة الأخطاء" href="/integrate/errors/introduction">
    رجوع للأول. خريطة المكانين.
  </Card>
</Cards>