Cancel payment (reverse)

Cancels the hold of a two-step payment (auto_clearing = false) and releases the funds.

The X-Action header must be gateway.payment.reverse.

Sign the request with X-JWS-Signature: see Async API Overview.

Reversal is possible only for a payment in status approved that is not cleared: for a cleared payment use gateway.payment.refund.

Reverse flow

The full two-step flow (create, clearing or reverse, refund) is shown in Capture payment (clearing).

Result

Response	Meaning	Next step
`reverse_payment.status = process`	The reversal is accepted: a child reversal payment is created.	Get the final status with `gateway.payment.status`: the payment gets status `reversed`. If the response is lost, use `gateway.request.status`.
`status = error`	The reversal is rejected: a failed reversal payment is returned.	See «Errors» below. The failed attempt is also listed in `reverse_payments` of the original payment.
`{}`, `X-Request-Status: process`	The result is not ready yet.	Repeat the request in a few seconds with the same `X-Request-Id`.

Errors

A rejected reversal is returned with HTTP 200 as a failed reversal payment: status error and the error object.
The error is returned in error.code and error.description.

HTTP	`error.code`	When	What to do
`200`	`110691`	Invalid payment status: reversal is possible only for a two-step payment in status `approved` that is not cleared and not reversed yet.	Get the payment status with `gateway.payment.status`. For a cleared payment use `gateway.payment.refund`.
`200`	`9994`	Reversal is disabled in the merchant settings.	Contact Freedom Pay.
`400`	`9400`	The body is not valid JSON.	Fix the request.
`401`	`9998`	The signature is invalid.	Check the signature: see Async API Overview.
`422`	`9403`	`id` is missing or is not a UUID, or a required header is missing. The reason is in `error.description`.	Fix the request.
`500`	`9999`	Internal error at the gateway entry point.	Repeat the request later with the same `X-Request-Id`.
`500`	`10000`	Internal error in payment processing.	Repeat the request later with the same `X-Request-Id`.

Responses

🟢200OK

application/json

Headers

Bodyapplication/json

Example

{
    "id": "01a133ca-fa79-7f0c-82d7-7c04ba783963",
    "amount": 100,
    "reverse_payment": {
        "id": "01a133cb-07bc-7115-8c30-afe77ae49495",
        "status": "process"
    },
    "status": "error",
    "created_at": "2026-10-13T05:45:12.452783942Z",
    "error": {
        "code": "110691",
        "description": "Invalid payment status."
    }
}

🟠400Bad Request

🟠422Unprocessable Entity

🟠401Unauthorized

🔴500Internal Server Error

Cancel payment (reverse)

Reverse flow#

Result#

Errors#

Request

Responses

Reverse flow

Result

Errors