Customizing Payment Gateway Reason Code Messages in Foxycart

bushybushy Member
in Bugs & Feature Requests edited March 2008
My reading of Cybersource doc is that if you want to customize the default error (or "reason code") message that a customer sees when a transaction fails (and the default messages always 100% suck) you need to do it on the web server that's serving the message. In the case of a Foxycart hosted cart, that'd be Foxycart's web server. What options does Foxycart provide for me to customize the message a customer sees if the transaction fails?

PS: <soapbox>I know you guys are growing this baby and feature requests are coming in cuz I read all the threads. But good error handling, unsexy as it may be, is IMHO bedrock to long term success. Small site owners (your initial adopters) tend to think first about features and last about what happens when a transaction goes wrong. They want to assume that every customer is legit, that every transaction succeeds. That kind of thinking doesn't scale, not if solid error handling isn't in place. It may be a bitter pill to swallow for the guy trying to sell some beautifully original t-shirts, but the reality is that the first time a customer get at an error message that comes straight from a payment gateway that customer is likely lost forever. You've blown your first and best shot at what could have been one of your best customers.</soapbox>
  • lukeluke FoxyCart Team
    Hey Bushy, thanks for the comments.

    We actually completely agree and opened a support ticket a while back with Cybersource because we were disappointed with the lack of meaningful error details they were returning. We ended up making a full array of all possible error codes that we could find and currently return those based on what Cybersource returns to us:
    $cybersourceResponse["100"] = "Successful transaction.";
    $cybersourceResponse["101"] = "The request is missing one or more required fields.";
    $cybersourceResponse["102"] = "One or more fields in the request contains invalid data";
    $cybersourceResponse["150"] = "Error: General system failure.";
    $cybersourceResponse["151"] = "Error: The request was received but there was a server timeout. This error does not include timeouts between the client and the server";
    $cybersourceResponse["152"] = "Error: The request was received, but a service did not finish running in time.";
    $cybersourceResponse["200"] = "The authorization request was approved by the issuing bank but declined by CyberSource because it did not pass the Address Verification Service (AVS) check";
    $cybersourceResponse["201"] = "The issuing bank has questions about the request. You do not receive an authorization code programmatically, but you might receive one verbally by calling the processor";
    $cybersourceResponse["202"] = "Expired card. You might also receive this if the expiration date you provided does not match the date the issuing bank has on file";
    $cybersourceResponse["203"] = "General decline of the card. No other information provided by the issuing bank.";
    $cybersourceResponse["204"] = "Insufficient funds in the account";
    $cybersourceResponse["205"] = "Stolen or lost card";
    $cybersourceResponse["207"] = "Issuing bank unavailable";
    $cybersourceResponse["208"] = "Inactive card or card not authorized for card-not-present transactions";
    $cybersourceResponse["209"] = "American Express Card Identification Digits (CID) did not match";
    $cybersourceResponse["210"] = "The card has reached the credit limit.";
    $cybersourceResponse["211"] = "Invalid card verification number.";
    $cybersourceResponse["221"] = "The customer matched an entry on the processor’s negative file.";
    $cybersourceResponse["230"] = "The authorization request was approved by the issuing bank but declined by CyberSource because it did not pass the card verification (CV) check";
    $cybersourceResponse["231"] = "Invalid account number";
    $cybersourceResponse["232"] = "The card type is not accepted by the payment processor";
    $cybersourceResponse["233"] = "General decline by the processor";
    $cybersourceResponse["234"] = "There is a problem with your CyberSource merchant configuration";
    $cybersourceResponse["235"] = "The requested amount exceeds the originally authorized amount. Occurs, for example, if you try to capture an amount larger than the original authorization amount";
    $cybersourceResponse["236"] = "Processor failure.";
    $cybersourceResponse["237"] = "The authorization has already been reversed";
    $cybersourceResponse["238"] = "The authorization has already been captured";
    $cybersourceResponse["239"] = "The requested transaction amount must match the previous transaction amount.";
    $cybersourceResponse["240"] = "The card type sent is invalid or does not correlate with the credit card number";
    $cybersourceResponse["241"] = "The request ID is invalid";
    $cybersourceResponse["242"] = "You requested a capture, but there is no corresponding, unused authorization record. Occurs if there was not a previously successful authorization request or if the previously successful authorization has already been used by another capture request";
    $cybersourceResponse["243"] = "The transaction has already been settled or reversed";
    $cybersourceResponse["246"] = "The capture or credit is not voidable because the capture or credit information has already been submitted to your processor. Or, you requested a void for a type of transaction that cannot be voided";
    $cybersourceResponse["247"] = "You requested a credit for a capture that was previously voided";
    $cybersourceResponse["250"] = "Error: The request was received, but there was a timeout at the payment processor";

    Not sure what more we can do than that... Do you have any suggestions?

    As for making your own custom message, that will be part of the language customization we build into future versions. You may want to change some wording, but someone else may need to use French or German. :)

    Thanks again for your comments.
  • bushybushy Member
    Hey Luke. So, LOL, would you believe that your array of Cybersource status codes includes everything EXCEPT the two most common errors I get in testing:

    1) Error: One or more of the services was declined: (Response Reason Code: 520) -- (me: What's happening is the issuing bank authorized the transaction but the order matched CyberSource SmartAuth criteria the merchant specied in their CyberSource SmartAuth settings.)

    2) Error: One or more of the services was declined: (Response Reason Code: 104) -- (me: customer is attempting to submit an order that has already been submitted and authorized by CyberSource--this happens when a customer tries to resubmit an order that originally returned a 520 error in FoxyCart. As far as CyberSource is concerned, since the issuing bank has already been authorized the transaction, so it's a duplicate.)

    (BTW, FoxyCart's handling of CyberSource 520 continues to be a potential deal-breaker for me if we can't find a better way to handle it. But it's tangential to the this thread's original issue of better error messages so I'll save that discussion for another thread.)

    The response strings you guys came up with (listed in your post) are a big improvement to what Cybersource returns, but in a lot of cases they still leave the customer hanging because the language is still kinda "machine-speak" and it doesn't suggest to the customer a clear course of action to resolve the error. Ideally I'd like it if FoxyCart gave me the option of specifying my own, more user-friendly error messages. It'd take some coding work but long-term it'd save you the headache of FoxyCart subscribers complaining about the text their customers get when an error occurs with an order. But if that's not feasible in the near term, I'd be happy to provide a suggested list of "friendlier" strings for the various CyberSource status codes (I'm a tech writer for a web analytics company so this is more or less what I do all day anyway :-) For example, in place of:

    "Expired card. You might also receive this if the expiration date you provided does not match the date the issuing bank has on file"

    I'd rather give the customer something like:

    "We're sorry. The card you're using appears to be expired. Or the expiration date you provided does not match the date your card's issuing bank has on file. Please verify that the expiration date you entered for your card is correct. If the card is expired, please use a different card to complete your order."
  • lukeluke FoxyCart Team
    Thanks Bushy!

    We would gladly implement a more user friendly list of messages, If you're willing to provide it. We'll also add 520 and 104 for you as well, just let us know exactly what you'd like to see.

    Sometimes there are messages that only show up with "live" gateways and since we don't have a live cybersource account, we rely on your feedback to improve our system.

  • bushybushy Member
    Thanks Luke. I'll knock out a list of strings in the next week or so (at least for those statuses I understand) --any recommendation on max character length (given the space you have to display it in?

    OT: Fun reading: bad error messages from the UI Hall of Shame
  • I was getting error 150 before I found out Cybersource hadn't switched 'Live' on our account.

    Cybersource 150 (live) - Merchant status is not set to live for production system or is not set to live, test, or eval for the test system. Contact CyberSource support
  • brettbrett FoxyCart Team
    So it's all cleared up now?
  • @brett, yes I had a feeling Cybersource was the one that wasn't playing. Espcially after I found this post and one about PayPal occassionaly not playing as well.

    I posted the 150 reference code description as it was a bit more descriptive from the Cybersource business center page.
  • @brett,

    Is there a way for us to write some jQuery or CSS to override error messages? Just checking.

    ie. I use Authorize.Net (that's Cybersource, right?) If the user enters the incorrect name, address or card exp date, Foxy returns this message from Authorize.
    Error: Your payment was declined for the following reason: This transaction has been declined. (Response Reason Code: 2)

    It's not that helpful. I was hoping to replace it with "Please verify your name, address and credit card information or try a different Visa or Mastercard credit card."

    I did a little searching in the forum and didn't find any answers. Feel free to point me to another thread if necessary.
  • lukeluke FoxyCart Team
    Cybersource is actually a different gateway than We use ourselves and agree those error messages are not very helpful at all. We'll add it to our list of "hopeful improvements" for next release, but no guarantees. You could try doing a jQuery check to search for that text and, if you find it, replace it with something else in the checkout template. That might work. Yeah, something like this:
    jQuery('#fc_error_container:contains("(Response Reason Code: 2)") ul li').html("<b>Error:</b> Please verify your name, address and credit card information or try a different Visa or Mastercard credit card.");
    Hope that helps.
  • Thanks. This helped a lot. Really appreciate it.
Sign In or Register to comment.