What HTTP code response to use when payment fails?

Question

What HTTP code to use when processing payments / dealing with credit cards?

For instance:

• Not enough funds
• Unable to retrieve funds (when no reason is given)
• Credit card expired

I am sending a JSON response, so I don't mind too much but I am wondering what's the right code to use.

Answer 1

First, it is important to distinguish between failures that are

1. caused by the client side and
2. others that have been caused by problems on the server side

The latter ones normally describe errors that the client cannot solve on its own.

The first ones should have a status code in the 400 series. The others, caused by the server side should have a status code on the 500 series.

My suggestions

• Not enough funds

  • I would suggest 400 (Bad request) together with a meaningful error message.

• Unable to retrieve funds (when no reason is given)

  • 500 (internat server error), if the root cause is clearly the server side.
  • 503 (Service Unavailable), if it can be determined that some necessary web service is temporarily not available. The meaning behind 503 is that this error is of a temporary nature, encouraging the client to retry the same request later.
  • 400 (Bad request) if the root cause is a somehow invalid request by the client

• Credit card expired

  • Again, I would suggest 400 (Bad request) + error message

A full list of return codes can be found here.

Answer 2

What the previous answer said is valid. What is important is that your API sticks to its choice after deciding on a response code. Here's a relevant Uber Eats bug caused by a payment provider changing their API.

I want to add that 402 (Payment Required) might be what you're looking for. Note that 402 is declared "experimental" by MDN at the time of this comment. Check out the RFC introducing the 402 status code here.

The MDN docs state:

Sometimes, this status code indicates that the request cannot be processed until the client makes a payment. However, no standard use convention exists and different entities use it in different contexts.