HTTP Code for payment accepted/refused in a REST API

Question

In a REST API, in payment method (user gives his card infos), should I return 200 if the payment fails (for card expiration or balance too low problem) with an attached message + custom additional error code in JSON ? Or is there any other HTTP code for this ?

I did not found any information about this particular case, I just found 402 code for payment but it does not seem to be designed for this case. I'm not talking about a server (500) error or unreachable bank, just payment problem due to user card.

Answer 1

I think you should use 406 code.

Code - 406

Message - Not Acceptable

Description - Insufficient funds or other payment problem.

Answer 2

What does "the payment fails" mean exactly? I can think of a few different scenarios, many of which might require a different status code to reflect the actual status.

It all depends how the rest of your API works though. If you already use JSON objects in the response body, you may as well report 200 OK for any action:

HTTP/1.1 200 OK
...

{ 
    success: false,
    message: "Balance too low"
}

If you don't want that, any 4xx or 5xx error that applies will do. Try searching.

• REST HTTP status codes for failed validation or invalid duplicate
• What's an appropriate HTTP status code to return by a REST API service for a validation failure?
• REST response code for invalid data