7

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.

Erunafailaro
  • 1,835
  • 16
  • 21
hakunin
  • 4,041
  • 6
  • 40
  • 57

2 Answers2

7

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.

    • Maybe even set the Retry-After header with the amount of seconds that the client is recommended to wait before trying again.

  • 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.

Erunafailaro
  • 1,835
  • 16
  • 21
  • 1
    Would you use 503, even if an external API is down? (such as Stripe, Paypal, etc..) – hakunin Feb 07 '20 at 12:09
  • If the unavailability of the external API prevents your API from serving requests as well, then yes. It that case, I would advice to use 503 – Erunafailaro Feb 07 '20 at 12:16
  • I think 400 is not appropriate when not enough funds because as Wikipedia says 400 is used when "The request cannot be fulfilled due to bad syntax". Hence, a different use case – Oleg Yablokov Oct 17 '22 at 12:12
4

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.

Jordan Gillard
  • 301
  • 1
  • 5
  • 14