Refund: Overview

What is a Refund?

This section introduces core API methods and status flows for handling refunds, which are reimbursements linked to a specific payment. A refund can be created as full or partial and is always associated with the original payment intent.

Terminology

Entity	Description
Intent	A container that groups one or more transactions (Payment, Disbursement, or Refund) representing a single flow of funds
Partial Refund	A reimbursement for part of the original payment amount, always tied to the same payment intent
Multiple Partial Refunds	Several partial refunds against the same payment, together not exceeding the original amount
Full Refund	A reimbursement for the entire original payment amount

High-Level Refund Process

Endpoint	Short Name
`POST /processing/api/v1/refunds`	Refund request creation for partial or full refund, linked to an original payment
`GET /processing/api/v1/refunds/{id}`	Retrieve the refund details and its current status

Refund Structure

Attribute	Description
`Id`	Unique identifier of the refund generated by the platform.
`intentId`	An ID of the linked intent.
`paymentId`	An ID of the original payment, the refund was requested for.
`refundSubmittedAmount`	The amount and currency submitted in the original transaction request.
`refundAuthAmount`	The amount and currency successfully processed (can differ due to FX or fees).
`refundExchangeRate`	The FX rate used for currency conversion if applicable.
`reason`	The specified refund reason - free text
`status`	Current state of the payment (e.g. `ACCEPTED`, `REFUND_REQUESTED`, ...)
`createdAt`	Transaction creation date.
`updatedAt`	Transaction last update date.

Refund Status Model

The following table summarizes the statuses a refund may go through:

Status	Description
ACCEPTED	The refund request was received and passed the validations on our side and will be processed shortly
DECLINED	The refund request was rejected either during internal validation or by the Payment Method.
REFUND_REQUESTED	The refund has been submitted to the Payment Method Operator for processing.
REFUND_ISSUED	[Optional] The refund has been formally issued, but the final outcome of money delivery is not yet known and will later be confirmed as either REFUNDED or REFUND_FAILED
REFUNDED	The Payment Method confirmed that the refund was successfully processed. Money should be returned to the payer.
REFUND_FAILED	[Optional] The Payment Method confirmed that the refund could not be delivered to the payer.
ERROR	A technical issue occurred while processing the refund (system error, communication failure, etc.).