Charge API: failure_code vs failure_message

[Martin Lademann]

Hi again,

I want understand the charge properties failure_code and failure_message a bit better. I'd expect that the latter would be always (the user-friendly version of) the string corresponding to the failure_code written down in the reference document for the error object (https://stripe.com/docs/api#errors) but the reference says "further" which confuses me a little since this formulation suggests failure_message might actually contain more information than failure_code (especially since something like card_declined is very vague). I suppose that's not the case since it would make translating error messages virtually impossible, but some more clarity at this point would be very much appreciated.

Martin

[Matthew Arkin]

Just to piggy back off of this, when should we see a charge created with a failure code?

Its my understanding that a charge won’t be created if a charge attempt fails. Stripe instead returns an 4XX error and the body of the response is an error.

--

Matt Arkin

Kollective Solutions

http://kollective.it

http://mattarkin.com

--
You received this message because you are subscribed to the Google Groups "Stripe API Discussion" group.
To post to this group, send email to api-d...@lists.stripe.com.
Visit this group at http://groups.google.com/a/lists.stripe.com/group/api-discuss/.

To unsubscribe from this group and stop receiving emails from it, send an email to api-discuss...@lists.stripe.com.

[Vladimir Andrijevik]

When charging a subscription fails (for any invoice after the initial one), a failed charge is recorded as a Charge object, and a `charge.failed` event which describes it is emitted via webhooks, as documented at https://stripe.com/docs/api#event_types

In this case, there will be multiple Charges with the same invoice property, and at most one of them (the last one) will have a true value for the `paid` property.

Cheers,

Vlad

[Jim Danz]

Hi Martin,

failure_code and failure_message on the charge object mirror the
values that we returned in our original response to you when you
created the charge.

So, if when creating a charge you received a 402 response with contents:
{
'type': 'card_error',
'code': 'card_declined'
'message': 'Your card was declined.'
'charge': 'ch_foo'
}

Then, when fetching 'ch_foo' from the API, you would see
failure_code='card_decline' and failure_message='Your card was
declined.'.
Unfortunately, in the majority of cases we do not have more
interesting information to offer than simply "Your card was declined."
When a card is declined, in the majority of cases the card networks /
the customer's bank simply say "decline" without providing any further
color around what happened.

In general, code/failure_code will adhere to the published list of
codes at https://stripe.com/docs/api#errors, and
message/failure_message will be a human-readable string suitable for
display to the end user.

"Further" is probably the wrong word to use there to describe what
we're getting at, because there isn't really a case where the
failure_message will provide strictly more information than the
failure_code, just a longer and more human-readable way of saying it.
For instance, when code is invalid_expiry_year, message will be "Your
card's expiration year is invalid.". No new information, just the
human-readable explanation of the code.

Hope this helps! Sorry for the confusing diction in the docs.

Cheers,
Jim

[Martin Lademan]

Thanks for the detailed reply Jim! If you get the chance to remove the
"further" from the docs no one will ever ask again... ;)

Martin

[Martin Lademan]

Hi Jim,

sorry, but this topic still bothers me. I just remembered examples where
I had actually seen more information in failure_message than in
failure_code.

Looking at the docs the failure_code 'card_declined' should translate
into the general failure_message 'Your/the card was declined.' And you
pointed out, that Stripe doesn't know more about the reason of the
decline. But I've seen examples where failure_message has had different
and more detailed values for the same failure_code 'card_declined', namely:

* 'Your card has insufficient funds.'
* 'Your card is not supported for this currency. Please use a Visa or
MasterCard card.'

Since you don't support translations of failure_message yourself I'm
really wondering how you want developers to translate them for the end
users if no complete list is published? I'm not satisfied just having
the "majority" of cases covered.

Martin



On 09/12/14 20:00, Jim Danz wrote:

[Scott Fotheringham]

Hi Martin,

Isn't what Jim is saying though that the banks and card handlers are not consistent with their reply when Stripe attempts to charge the card? So, where Stripe is given a message of more detail, they will provide it - otherwise, a generic message is given.

I find this perfectly adequate and actually exceptionally helpful. I'm sure they'll update if the banks/cards start providing more standardized messages.

[Martin Lademan]

Hi Scott,

thanks for your input, but I don't believe it's a problem with the
banks/card providers. If they only answer "decline" where does Stripe
acquire the more detailed information like the previously mentioned
"insufficient funds" or "currency not supported" that get delivered
through the API in failure_message?

My understanding of failure_code is that it should be providing an
identifying key for failure_message that could be used e.g. for
translating failure_message into other languages than English. At the
moment it provides a key for a category of failure_messages. So to
achieve translations of all available details I'd need a list of all
possible failure_messages which is unavailable atm and even if existing
it would be not a desired way to do translations since they are usually
done on keys and not values.

Martin

[Scott Fotheringham]

Hi Martin,

Sorry, maybe I wasn't clear. Stripe does provide these messages when that particular card/bank provide such details to Stripe about why the transaction failed. But, for example, I have seen customers of my sites (using AMEX I believe) attempt to pay their bill and be given a generic failure message by Stripe. I believe some do this for security purposes. The failure frustrated both the customer and myself until her bank called her and told her payments over n amount had to be pre-approved. This tells me that either Stripe didn't understand the response (unlikely) or the bank gave Stripe a generic failure message (more likely). Possibly for security reasons to prevent fraud.

What I'm getting at is that some banks send Stripe back (I have no idea of the protocols) something like FAIL and a code which Stripe uses to determine the cause of the failure and provide a detailed message through the API. On the other hand, other banks may be providing only FAIL for certain cases, in which case Stripe has no choice but to provide a generic failure message.

[Martin Lademan]

> Sorry, maybe I wasn't clear. Stripe does provide these messages when that particular card/bank provide such details to Stripe about why the transaction failed.

Of course they do – but not in way I can translate them to other
languages! Sorry if my posts have been confusing: I'm not questioning
the failure details themselves, just the (in my eyes improvable)
structure they are provided through the API.