Refund payment

Refunds a debited payment fully or partially.

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

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

Refund is possible only for a payment in status success: to cancel a hold that is not cleared use gateway.payment.reverse.

Several partial refunds are allowed while their total with reversals does not exceed the payment amount.

The status of the payment stays success: count only refund_payments items with status success.

Refund flow

Result

Response	Meaning	Next step
`refund_payment.status = process`	The refund is accepted: a child refund payment is created.	Get the final status with `gateway.payment.status`: the refund is listed in `refund_payments`. If the response is lost, use `gateway.request.status`.
`status = error`	The refund is rejected: a failed refund payment is returned.	See «Errors» below. The failed attempt is also listed in `refund_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 refund is returned with HTTP 200 as a failed refund 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: refund is possible only for a payment in status `success` (not approved, not reversed, not failed).	Get the payment status with `gateway.payment.status`. To cancel a hold that is not cleared use `gateway.payment.reverse`.
`200`	`900811`	The refund amount exceeds the amount available for refund.	Pass a smaller `amount`: the total of refunds and reversals cannot exceed the payment amount.
`200`	`9994`	Refund 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, `amount` is less than 0.01, 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

Examples

Partial refund acceptedFull refund acceptedRepeated request (same X-Request-Id)Rejected: amount exceeds the available amountRejected: invalid payment statusRejected: refund disabled for the merchantResult not ready (X-Request-Status: process)

{
  "id": "01a133d6-91e2-7993-8302-61572319a64a",
  "amount": 100,
  "refund_payment": {
    "id": "01a133d6-9e79-7b54-969c-4b269bd9b2e3",
    "status": "process",
    "amount": -30
  }
}

🟠400Bad Request

🟠422Unprocessable Entity

🟠401Unauthorized

🔴500Internal Server Error

Refund flow#

Result#

Errors#

Request

Responses

Refund flow

Result

Errors