Refund payment

Returns money to the client for a captured payment: a one-step payment, or a two-step payment after the clearing. The result is returned in the same response.

Refunds can be partial and repeated: the total of refunds cannot exceed the captured amount.

A two-step payment that is not captured cannot be refunded: release it with cancel, or capture it with clearing first.

If fiscal receipts are connected for the merchant, pass pg_receipt_positions: a refund receipt is created from them.

Test cards: see Gateway API Overview.

Result

`pg_status`	Meaning	Next step
`ok`	The refund is accepted: see `pg_refund_status`.	`success`: nothing else is needed. `process`: request the status with `status_v2` until it is final.
`error`	The request is rejected or the payment system declined the refund.	See «Errors» below.

Refund flow

Each refund is a separate operation with its own ID: pg_payment_refund_id in the response.

Errors

The HTTP status is always 200; the error is returned in pg_error_code and pg_error_description.

`pg_error_code`	When	What to do
`9403`	A parameter is missing or has an invalid value, or a payment with this `pg_payment_id` does not exist.	Fix the request.
`1370`	`pg_amount` is missing, is not a number, or is less than 0.01.	Fix the amount.
`1100`	The signature is missing or invalid.	Check the signature: see Sync API Overview.
`1101`	`pg_merchant_id` is not found. The response is not signed.	Check the merchant ID.
`900811`	`pg_amount` is greater than the amount available for refund: the captured amount minus previous refunds. After a cancel nothing is available.	Check the amount; get the payment details with `status_v2`.
`9014`	The payment is not captured (a two-step payment without clearing) or has been cancelled.	Capture the payment with `clearing` or release it with `cancel`.
`110691`, `90131`	The payment is not successful.	There is nothing to refund.
`91021`	A refund request for this payment is already being processed.	Wait for the response to the first request or get the payment status with `status_v2`.
`10000`	The payment is not found for this merchant, or the refund could not be performed.	Check `pg_payment_id` and `pg_merchant_id`; repeat the request later.
`9994`	Refunds are disabled in the merchant settings.	Contact Freedom Pay.
`9110`	A dispute is open for the payment: refunds are unavailable until it is resolved.	Repeat after the dispute is resolved.
`9111`	The money has already been returned to the cardholder by a chargeback.	Do not refund the payment.
Other codes	The payment system declined the refund.	See Error codes.

Request example

Required fields only. pg_sig is calculated with the secret key test_secret_key.
Line breaks in the body are added for readability: send the body as one line.

Responses

🟢200Success

application/xml

Bodyapplication/xml

Examples

SuccessSuccess: partial refund

<?xml version="1.0" encoding="utf-8"?>
<response>
    <pg_payment_id>1015054203206</pg_payment_id>
    <pg_payment_refund_id>1015054203209</pg_payment_refund_id>
    <pg_status>ok</pg_status>
    <pg_refund_status>success</pg_refund_status>
    <pg_datetime>2026-10-15T10:45:36+00:00</pg_datetime>
    <pg_salt>dztVazCQUTbzGxxu</pg_salt>
    <pg_sig>7c655b98b997c49e0caaea363b6cb55c</pg_sig>
</response>

🟢200Error

Result#

Refund flow#

Errors#

Request example#

Request

Responses

Result

Refund flow

Errors

Request example