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:
| Field | Description |
|---|---|
source.message | Human-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_code | Two-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). |
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.
| Message | Applies to | Description (English) | Description (Arabic) |
|---|---|---|---|
TIMED_OUT | All card sources | No 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 Error | All card sources | Moyasar could not connect to the acquirer. The customer can try again. | تعذر على ميسر الاتصال بالبنك المحصّل، يمكن للعميل المحاولة مرة أخرى |
DNS Error | All card sources | Moyasar could not reach the acquirer. The customer can try again. | تعذر على ميسر الوصول إلى البنك المحصّل، يمكن للعميل المحاولة مرة أخرى |
ACQUIRER PG SYSTEM ERROR | All card sources | The acquirer returned a system error. The customer can try again. | أعاد البنك المحصّل خطأ في النظام، يمكن للعميل المحاولة مرة أخرى |
BLOCKED: CARD COUNTRY NOT ALLOWED | All card sources | The card was issued in a country your account doesn't accept. | البطاقة صادرة من دولة غير مسموح بها في حسابك |
BLOCKED: Card in blocked list | All card sources | The card matches a block rule on your account. | البطاقة مدرجة في قائمة الحظر الخاصة بحسابك |
BLOCKED: Card is not in allowed list | All card sources | Your account only accepts listed cards, and this card isn't one of them. | حسابك يقبل بطاقات محددة فقط وهذه البطاقة ليست منها |
BLOCKED: Unauthenticated Transaction | Card | The payment was not authenticated with 3-D Secure and your account requires it. | لم تتم مصادقة العملية عبر 3D-Secure وحسابك يتطلب ذلك |
BLOCKED: High Risk Transaction | All card sources | The payment was declined by fraud risk checks. | تم رفض العملية من قبل فحوصات مخاطر الاحتيال |
BLOCKED: Authentication failed or not permitted (ECI xx) | Apple Pay, Google Pay, Samsung Pay | The wallet's authentication result (ECI value shown) is not accepted for your account. | نتيجة مصادقة المحفظة (قيمة ECI الظاهرة) غير مقبولة لحسابك |
MALFORMED TOKEN | Apple Pay, Google Pay, Samsung Pay | The wallet token sent in the request is not in a valid format. | رمز المحفظة المرسل في الطلب بصيغة غير صحيحة |
TOKEN CANNOT BE DECRYPTED | Apple Pay, Google Pay, Samsung Pay | The wallet token couldn't be decrypted, usually because the merchant certificate in the wallet portal doesn't match Moyasar's. | تعذر فك تشفير رمز المحفظة، غالباً بسبب عدم تطابق شهادة التاجر في بوابة المحفظة مع شهادة ميسر |
Messages starting with 3DS: | Card | 3-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 Message | Description (English) | Description (Arabic) |
|---|---|---|
| 1. INSUFFICIENT FUNDS | The card doesn't have sufficient funds to complete the transaction | لايوجد رصيد كافي في البطاقة |
| 2. DECLINED | Transaction declined by the customer’s bank. The customer should use an alternate credit card | عملية مرفوضة من بنك العميل، يجب استخدام بطاقة أخرى بديلة |
| 3. BLOCKED | The acquiring bank blocked the transaction without specifying the reason "could be suspected of fraud" | البنك المحصل للأموال قام بحجب العملية دون تحديد سبب لذلك ، قد يكون إشتباه لعملية إحتيال |
| 4. Allowed time frame for transaction has been expired | The 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 FAILURE | The customer’s bank has declined the transaction for an undefined cause in their system. The customer should use an alternate credit card | رفض بنك العميل العملية لسبب غير محدد في نظامهم ، يجب على العميل استخدام بطاقة أخرى بديلة |
| 6. EXPIRED CARD | The transaction failed as the card appears to have expired | فشلت العملية بسبب انتهاء البطاقة |
| 7. TIMED OUT | The 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 length | The security number (CVC/CVV) was entered incorrectly by the cardholder | تم إدخال رمز الأمان (CVC/CVV) بشكل خاطئ من قِبل حامل البطاقة |
| 9. REFERRED | The 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 | المبلغ تجاوز الحد الأقصى و المسموح لكل عملية |