Skip to main content

Payment Errors

When a payment is declined or fails, the API still answers with HTTP 201 and returns the payment with status set to failed. Two fields on the payment source explain the failure:

FieldDescription
source.messageHuman-readable reason. When the issuer or acquirer declines, this is their own text and it can differ between banks and gateways for the same reason (for example DECLINED, DO NOT HONOUR, INSUFFICIENT FUNDS or INSUFFICIENT_FUNDS).
source.response_codeTwo-character code returned by the acquirer. See Response Codes. It is null when the payment failed before reaching the acquirer (3-D Secure failures, blocks, token errors, timeouts).
Mapping errors on your side

Use status to decide whether the payment succeeded, and map failures on source.response_code when it is present. Use source.message for display and logging only: issuer and acquirer messages are not a fixed list and can change without notice. When source.response_code is null, use the messages generated by Moyasar and the 3DS errors.

Requests that are rejected before a payment is created (invalid parameters, authentication, rate limits) return an HTTP error instead. Those are described in API errors.

Messages generated by Moyasar​

These are the most common messages set by Moyasar itself. Their text is stable and source.response_code is null for all of them. This list is not exhaustive: Moyasar can also set other messages, for example when it translates an acquirer result that comes with a source.response_code. In that case, map on the code.

MessageApplies toDescription (English)Description (Arabic)
TIMED_OUTAll card sourcesNo final answer was received from the acquirer in time. The customer can try again. If the payment later turns out to have gone through, Moyasar reverses it: its status becomes voided or refunded and the message becomes TIMED_OUT: reversed due to connection timeout.لم يصل رد نهائي من البنك المحصّل في الوقت المحدد، يمكن للعميل المحاولة مرة أخرى. إذا تبيّن لاحقاً أن العملية تمت، يلغيها ميسر وتصبح حالتها voided أو refunded والرسالة TIMED_OUT: reversed due to connection timeout
Acquirer Connection ErrorAll card sourcesMoyasar could not connect to the acquirer. The customer can try again.تعذر على ميسر الاتصال بالبنك المحصّل، يمكن للعميل المحاولة مرة أخرى
DNS ErrorAll card sourcesMoyasar could not reach the acquirer. The customer can try again.تعذر على ميسر الوصول إلى البنك المحصّل، يمكن للعميل المحاولة مرة أخرى
ACQUIRER PG SYSTEM ERRORAll card sourcesThe acquirer returned a system error. The customer can try again.أعاد البنك المحصّل خطأ في النظام، يمكن للعميل المحاولة مرة أخرى
BLOCKED: CARD COUNTRY NOT ALLOWEDAll card sourcesThe card was issued in a country your account doesn't accept.البطاقة صادرة من دولة غير مسموح بها في حسابك
BLOCKED: Card in blocked listAll card sourcesThe card matches a block rule on your account.البطاقة مدرجة في قائمة الحظر الخاصة بحسابك
BLOCKED: Card is not in allowed listAll card sourcesYour account only accepts listed cards, and this card isn't one of them.حسابك يقبل بطاقات محددة فقط وهذه البطاقة ليست منها
BLOCKED: Unauthenticated TransactionCardThe payment was not authenticated with 3-D Secure and your account requires it.لم تتم مصادقة العملية عبر 3D-Secure وحسابك يتطلب ذلك
BLOCKED: High Risk TransactionAll card sourcesThe payment was declined by fraud risk checks.تم رفض العملية من قبل فحوصات مخاطر الاحتيال
BLOCKED: Authentication failed or not permitted (ECI xx)Apple Pay, Google Pay, Samsung PayThe wallet's authentication result (ECI value shown) is not accepted for your account.نتيجة مصادقة المحفظة (قيمة ECI الظاهرة) غير مقبولة لحسابك
MALFORMED TOKENApple Pay, Google Pay, Samsung PayThe wallet token sent in the request is not in a valid format.رمز المحفظة المرسل في الطلب بصيغة غير صحيحة
TOKEN CANNOT BE DECRYPTEDApple Pay, Google Pay, Samsung PayThe wallet token couldn't be decrypted, usually because the merchant certificate in the wallet portal doesn't match Moyasar's.تعذر فك تشفير رمز المحفظة، غالباً بسبب عدم تطابق شهادة التاجر في بوابة المحفظة مع شهادة ميسر
Messages starting with 3DS:Card3-D Secure authentication failed. See 3DS errors for the full list.فشلت مصادقة 3D-Secure، راجع أخطاء 3DS

Common issuer and acquirer messages​

The following are messages commonly returned by banks, with a description of each. This list is not exhaustive.

Error MessageDescription (English)Description (Arabic)
1. INSUFFICIENT FUNDSThe card doesn't have sufficient funds to complete the transactionلايوجد رصيد كافي في البطاقة
2. DECLINEDTransaction declined by the customer’s bank. The customer should use an alternate credit cardعملية مرفوضة من بنك العميل، يجب استخدام بطاقة أخرى بديلة
3. BLOCKEDThe acquiring bank blocked the transaction without specifying the reason "could be suspected of fraud"البنك المحصل للأموال قام بحجب العملية دون تحديد سبب لذلك ، قد يكون إشتباه لعملية إحتيال
4. Allowed time frame for transaction has been expiredThe payment process took too long (more than 15 minutes) and then failed. Either because the bank message containing the PIN was delayed to the customer’s mobile phone or because the customer was late in completing itاستغرقت عملية الدفع وقت أطول (أكثر من المسموح 15 دقيقة) ثم فشلت ، إما بسبب تأخر رسالة البنك التي تحتوي على رمز التحقق إلى الهاتف المحمول الخاص بالعميل أو بسبب تأخر العميل في إكمالها
5. UNSPECIFIED FAILUREThe customer’s bank has declined the transaction for an undefined cause in their system. The customer should use an alternate credit cardرفض بنك العميل العملية لسبب غير محدد في نظامهم ، يجب على العميل استخدام بطاقة أخرى بديلة
6. EXPIRED CARDThe transaction failed as the card appears to have expiredفشلت العملية بسبب انتهاء البطاقة
7. TIMED OUTThe customer’s bank was unable to be connected. The customer should attempt to process this transaction againفشل الإتصال مع بنك العميل، يجب على العميل محاولة معالجة العملية مره أخرى
8. Value 'xxxx' is invalid. value: xxxx - reason: Invalid secure code lengthThe security number (CVC/CVV) was entered incorrectly by the cardholderتم إدخال رمز الأمان (CVC/CVV) بشكل خاطئ من قِبل حامل البطاقة
9. REFERREDThe customer’s bank has indicated there is a problem with the credit card numberأشار بنك العميل إلى وجود مشكلة في رقم بطاقة الإئتمان
10. 3-D Secure transaction attempt failed (AUTHENTICATION_FAILED)Authentication is unsuccessful or not attempted by the cardholderالمصادقة غير ناجحة أو قد تم إلغاؤها من قِبل حامل البطاقة
11. 3-D Secure transaction attempt failed (AUTHENTICATION_ATTEMPTED)Either the cardholder or card issuing bank is not 3D-Secure enrolled. 3D-Secure card authentication is unsuccessfulإما أن يكون حامل البطاقة أو البنك المصدّر للبطاقة غير مسجل في خدمة التحقق الأمني (3D-Secure)

مصادقة البطاقة (3D-Secure) غير ناجحة
12. 3-D Secure transaction attempt failed (AUTHENTICATION_NOT_AVAILABLE)Either the cardholder or card issuing bank is not 3D-Secure enrolled. 3D-Secure card authentication is unsuccessfulإما أن يكون حامل البطاقة أو البنك المصدّر للبطاقة غير مسجل في خدمة التحقق الأمني (3D-Secure)

مصادقة البطاقة (3D-Secure) غير ناجحة
13. 3-D Secure transaction attempt failed (Missing parameter)There was an authentication errorحدث خطأ في المصادقة
14. 3-D Secure transaction attempt failed (Relationship not found for merchantID XXX, card type VC)The merchant account is not configured to receive Visa transactionsلم يتاح لحساب التاجر من قِبل البنك بإستقبال عمليات فيزا
15. 3-D Secure transaction attempt failed (Relationship not found for merchantID XXX, card type MC)The merchant account is not configured to receive MasterCard transactionsلم يتاح لحساب التاجر من قِبل البنك بإستقبال عمليات ماستركارد
16. 3-D Secure transaction attempt failed (CARD_NOT_ENROLLED)The card was not listed 3D-Secure with the issuing bank. The cardholder needs to communicate with his bank to activate the card for online payment. Or the card number was entered incorrectly by the cardholderالبطاقة غير مدرجة في خدمة التحقق الأمني (3D-Secure)، يجب على حامل البطاقة التواصل مع البنك الذي يتعامل معه لتمكين البطاقة من الدفع عبر الإنترنت . أو قد تم إدخال رقم البطاقة بشكل غير صحيح من قِبل حامل البطاقة
17. 3-D Secure transaction attempt failed (Value 'xxx' is invalid. Cannot determine card brand.)The card number was entered incorrectly by the cardholderتم إدخال رقم البطاقة بشكل غير صحيح من قِبل حامل البطاقة
18. 3-D Secure transaction attempt failed (Value 'xxx' is invalid. Unable to determine card payment.)The card number was entered incorrectly by the cardholderتم إدخال رقم البطاقة بشكل غير صحيح من قِبل حامل البطاقة
19. 3-D Secure transaction attempt failed (Value 'xxx' is invalid. Amount exceeds maximum allowed limit)The amount exceeded the limit per transactionالمبلغ تجاوز الحد الأقصى و المسموح لكل عملية