Improvements to payment action response codes

We're updating the HTTP status codes returned when you perform payment actions, such as captures, refunds, and voids, to improve consistency and make responses easier to interpret.

What's changing

Invalid requests

For all invalid actions, such as refunding before capture or voiding a card verification, the API will now return 422 – Invalid data was sent with a JSON body that contains the type of error and a descriptive error code.

This will replace the current mix of 403 and 422 responses.

Duplicate requests

If you attempt a capture or refund for the full balance (without specifying the amount) on an action that’s already completed, or attempt a reversal for a payment that has already been reversed, the API will now return 200 – OK with the ID of the last completed action.

This replaces the current mix of 204 or 422 responses.

If you attempt a capture or refund for a partial amount on an action that’s already completed, the API will continue to return a 422 – Invalid data was sent with a JSON body that contains the type of error and a descriptive error code as it does now. We’ll also continue to return a 422 for any duplicate actions on an automatic capture or void.

Table of changes

Scenario	Previous response	New response
Invalid action (For example, refunding a card verification or voiding a card verification)	Mix of: `403 - Not allowed` `422 - Invalid data was sent`	`422 - Invalid data was sent` for all scenarios
Automatic capture, followed by any manual capture	`422 - Invalid data was sent`	`422 - Invalid data was sent`. No change for this scenario.
Automatic void, followed by any manual void	`422 - Invalid data was sent`	`422 - Invalid data was sent`. No change for this scenario.
Manual capture, followed by a repeat capture where you do not specify the amount	`422 - Invalid data was sent`	`200 - OK`
Manual partial captures for the full amount, followed by a repeat capture where you do not specify the amount	`422 - Invalid data was sent`	`200 - OK`
Manual refund, followed by a repeat capture where you do not specify the amount	`422 - Invalid data was sent`	`200 - OK`
Multiple partial refunds for a full amount, followed by a repeat capture where you do not specify the amount	`422 - Invalid data was sent`	`200 - OK`
Manual full refund or multiple partial refunds for the full transaction amount, followed by a reversal	`422 - Invalid data was sent`	`200 - OK`
Manual void, followed by a repeat void	`422 - Invalid data was sent`	`200 - OK`
Manual capture, followed by a repeat capture where you specify the amount	`422 - Invalid data was sent`	`422 - Invalid data was sent`. No change for this scenario.
Manual partial captures for the full amount, followed by a repeat capture where you specify the amount	`422 - Invalid data was sent`	`422 - Invalid data was sent`. No change for this scenario.
Manual refund, followed by a repeat refund where you specify the amount	`422 - Invalid data was sent`	`422 - Invalid data was sent`. No change for this scenario.
Manual partial refunds for the full amount, followed by a repeat refund where you specify the amount	`422 - Invalid data was sent`	`422 - Invalid data was sent`. No change for this scenario.
Reversal, followed by a reversal	`204 - Payment has already been reversed`	`200 - OK`

Sample response

200 – OK

{
"action_id": "act_isqdcbdhgafe3pvw4cprrpzxoq",
"_links": {
"payment": {
"href": "https://api.sandbox.checkout.com/payments/pay_xkggjm2ryufehchi25goowcetq"
}
}
}

What this means for you

These changes will be live from 22 July, 2025. If your integration handles payment action responses based on specific status codes, you will need to review your system logic to account for the updated responses.