> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.mangopay.com/api-reference/refunds/refund-object/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.mangopay.com/_mcp/server.
# The Refund object
### Description
Mangopay relies on the Refund object to manage the reimbursement of a past transaction. A Refund object has the value `REFUND` as its `Nature` and is linked to the transaction being reimbursed by its `InitialTransactionId` property.
Two types of refund are initiated by the platform (see the [Refunds](/guides/refunds) guide for details):
* **Pay-in refund** – Platform request to reimburse a pay-in.
* **Transfer refund** – Platform request to reimburse a transfer.
There are two other cases generated automatically by Mangopay:
* **Payout return** – Return of funds created when, for instance, the end user's bank account is closed or if the acquiring bank refuses the funds. This transaction re-credits the wallet from which the payout was sent. See the [Payouts](/guides/payouts/rejects-returns) guide for more details.
* **Repudiation return** – Return of funds created when a dispute is won in favor of the platform. This transaction re-credits the Repudiation Wallet, from which the repudiation was debited. See the [Disputes](/guides/disputes) guide for more details.
> **Note**
>
> **Note – Transaction data retained for 13 months**
>
> The API retains all transaction objects for 13 months from `CreationDate`. This applies to refunds and the initial transaction linked to a refund.
>
> A call to retrieve the initial transaction of a refund, based on the refund’s `InitialTransactionId`, may return a 404 Not Found if it occurred more than 13 months ago.
>
> For more information, see the [Data availability periods](/api-reference/overview/data-availability-periods) article.
### Attributes
The refund shape depends on the type of initial transaction. Select a tab to see the relevant schema.
#### Pay-in refund
#### Transfer refund
#### Payout return
### Schema (`PayoutRefundResponse`)
```yaml
components:
schemas:
Id:
type: string
description: >-
Max length: 128 characters (see [data
formats](/api-reference/overview/data-formats) for details)
The unique identifier of the object.
title: Id
Tag:
type: string
description: >-
Max. length: 255 characters
Custom data that you can add to this object, such as unique identifiers
in your system. To store multiple values, you can serialize them into a
single string, for example a JSON object:
`"{\"id_1\":AB123,\"id_2\":DE456}"`.
title: Tag
CreationDate:
type: integer
description: Unix timestamp (UTC) of the date and time the object was created.
title: CreationDate
CreditedUserId:
type: string
description: >-
**Default value:** The unique identifier of the owner of the credited
wallet.
The unique identifier of the user whose wallet is credited.
title: CreditedUserId
Currency:
type: string
description: >-
**Allowed values:** The three-letter ISO 4217
code (EUR, GBP, etc.) of a supported currency (depends on feature, contract,
and activation settings).
The currency of the amount.
title: Currency
Amount:
type: integer
description: >-
The amount of the currency in its minor unit. For example, EUR 12.60
would be represented as `1260` whereas JPY 12 would be represented as
just `12`.
title: Amount
PayoutRefundResponseDebitedFunds:
type: object
properties:
Currency:
$ref: '#/components/schemas/Currency'
Amount:
$ref: '#/components/schemas/Amount'
description: Information about the debited funds.
title: PayoutRefundResponseDebitedFunds
PayoutRefundResponseCreditedFunds:
type: object
properties:
Currency:
$ref: '#/components/schemas/Currency'
Amount:
$ref: '#/components/schemas/Amount'
description: >-
Information about the credited funds (`CreditedFunds` = `DebitedFunds` -
`Fees`).
title: PayoutRefundResponseCreditedFunds
PayoutRefundResponseFees:
type: object
properties:
Currency:
$ref: '#/components/schemas/Currency'
Amount:
$ref: '#/components/schemas/Amount'
description: Information about the fees.
title: PayoutRefundResponseFees
TransactionStatus:
type: string
description: |-
**Returned values:** `CREATED`, `SUCCEEDED`, `FAILED`
The status of the transaction.
title: TransactionStatus
ResultCode:
type: string
description: >-
The code indicating the result of the operation. This information is
mostly used to handle errors or for
filtering purposes.
title: ResultCode
ResultMessage:
type: string
description: The explanation of the result code.
title: ResultMessage
TransactionExecutionDate:
type: integer
description: >-
Unix timestamp (UTC) of the date and time the status changed to
`SUCCEEDED`, indicating that the transaction occurred. The statuses
`CREATED` and `FAILED` return an `ExecutionDate` of `null`.
title: TransactionExecutionDate
TransactionNature:
type: string
description: >-
**Returned values:** `REGULAR`, `REPUDIATION`, `REFUND`, `SETTLEMENT`
The nature of the transaction, providing more information about the
context in which the transaction occurred:
- `REGULAR` – Relative to most of the transactions (pay-ins, payouts,
and transfers) in a usual workflow.
- `REPUDIATION` – Automatic withdrawal of funds from the platform's
repudiation wallet as part of the dispute process (when the user has
requested a chargeback).
- `REFUND` – Reimbursement of a transaction to the user (pay-in refund),
to a wallet (transfer refund), or of a payout (payout refund, only
initiated by Mangopay).
- `SETTLEMENT` – Transfer made to the repudiation wallet by the platform
to settle a lost dispute.
title: TransactionNature
PayoutRefundResponseRefundReason:
type: object
properties:
RefundReasonMessage:
type: string
description: >-
Message explaining the reason for the refusal (for example, a bank
return code).
RefundReasonType:
type: string
description: >-
**Returned values:** `INITIALIZED_BY_CLIENT`,
`BANKACCOUNT_INCORRECT`, `OWNER_DO_NOT_MATCH_BANKACCOUNT`,
`BANKACCOUNT_HAS_BEEN_CLOSED`,
`WITHDRAWAL_IMPOSSIBLE_ON_SAVINGS_ACCOUNTS`, `OTHER`
The type of reason for the payout return.
description: Information about the reasons for the payout return.
title: PayoutRefundResponseRefundReason
PayoutRefundResponse:
type: object
properties:
Id:
$ref: '#/components/schemas/Id'
Tag:
$ref: '#/components/schemas/Tag'
CreationDate:
$ref: '#/components/schemas/CreationDate'
AuthorId:
type: string
description: >-
The unique identifier of the user at the source of the initial
transaction.
CreditedUserId:
$ref: '#/components/schemas/CreditedUserId'
DebitedFunds:
$ref: '#/components/schemas/PayoutRefundResponseDebitedFunds'
description: Information about the debited funds.
CreditedFunds:
$ref: '#/components/schemas/PayoutRefundResponseCreditedFunds'
description: >-
Information about the credited funds (`CreditedFunds` =
`DebitedFunds` - `Fees`).
Fees:
$ref: '#/components/schemas/PayoutRefundResponseFees'
description: Information about the fees.
Status:
$ref: '#/components/schemas/TransactionStatus'
ResultCode:
$ref: '#/components/schemas/ResultCode'
ResultMessage:
$ref: '#/components/schemas/ResultMessage'
ExecutionDate:
$ref: '#/components/schemas/TransactionExecutionDate'
Type:
type: string
description: >-
**Returned values:** `PAYIN`
The type of the transaction. Payout returns are recorded as pay-ins
crediting the wallet from which the payout was sent.
Nature:
$ref: '#/components/schemas/TransactionNature'
InitialTransactionId:
type: string
description: The unique identifier of the initial payout being refunded.
InitialTransactionType:
type: string
description: |-
**Returned values:** `PAYOUT`
The type of the initial transaction being refunded.
InitialTransactionNature:
type: string
description: |-
**Returned values:** `REGULAR`
The nature of the initial transaction being refunded.
DebitedWalletId:
type: string
description: >-
The unique identifier of the debited wallet. Not returned for payout
returns.
CreditedWalletId:
type: string
description: >-
The unique identifier of the wallet re-credited with the returned
funds.
RefundReason:
$ref: '#/components/schemas/PayoutRefundResponseRefundReason'
description: Information about the reasons for the payout return.
StatementDescriptor:
type: string
description: >-
Max. length: 10 characters; only alphanumeric and spaces
Custom description to appear on the user's bank statement along with
the platform name. Different banks may show more or less
information. See the Customizing bank
statement references article for details.
**Note:** On refunds, the `StatementDescriptor` is only available
for SEPA and BACS [direct debit
pay-ins](/api-reference/direct-debit-payins/create-direct-debit-payin)
(no other payment methods nor transfers).
title: PayoutRefundResponse
```
#### Repudiation return
### Schema (`RepudiationRefundResponse`)
```yaml
components:
schemas:
Id:
type: string
description: >-
Max length: 128 characters (see [data
formats](/api-reference/overview/data-formats) for details)
The unique identifier of the object.
title: Id
Tag:
type: string
description: >-
Max. length: 255 characters
Custom data that you can add to this object, such as unique identifiers
in your system. To store multiple values, you can serialize them into a
single string, for example a JSON object:
`"{\"id_1\":AB123,\"id_2\":DE456}"`.
title: Tag
CreationDate:
type: integer
description: Unix timestamp (UTC) of the date and time the object was created.
title: CreationDate
CreditedUserId:
type: string
description: >-
**Default value:** The unique identifier of the owner of the credited
wallet.
The unique identifier of the user whose wallet is credited.
title: CreditedUserId
Currency:
type: string
description: >-
**Allowed values:** The three-letter ISO 4217
code (EUR, GBP, etc.) of a supported currency (depends on feature, contract,
and activation settings).
The currency of the amount.
title: Currency
Amount:
type: integer
description: >-
The amount of the currency in its minor unit. For example, EUR 12.60
would be represented as `1260` whereas JPY 12 would be represented as
just `12`.
title: Amount
RepudiationRefundResponseDebitedFunds:
type: object
properties:
Currency:
$ref: '#/components/schemas/Currency'
Amount:
$ref: '#/components/schemas/Amount'
description: Information about the debited funds.
title: RepudiationRefundResponseDebitedFunds
RepudiationRefundResponseCreditedFunds:
type: object
properties:
Currency:
$ref: '#/components/schemas/Currency'
Amount:
$ref: '#/components/schemas/Amount'
description: >-
Information about the credited funds (`CreditedFunds` = `DebitedFunds` -
`Fees`).
title: RepudiationRefundResponseCreditedFunds
RepudiationRefundResponseFees:
type: object
properties:
Currency:
$ref: '#/components/schemas/Currency'
Amount:
$ref: '#/components/schemas/Amount'
description: Information about the fees.
title: RepudiationRefundResponseFees
TransactionStatus:
type: string
description: |-
**Returned values:** `CREATED`, `SUCCEEDED`, `FAILED`
The status of the transaction.
title: TransactionStatus
ResultCode:
type: string
description: >-
The code indicating the result of the operation. This information is
mostly used to handle errors or for
filtering purposes.
title: ResultCode
ResultMessage:
type: string
description: The explanation of the result code.
title: ResultMessage
TransactionExecutionDate:
type: integer
description: >-
Unix timestamp (UTC) of the date and time the status changed to
`SUCCEEDED`, indicating that the transaction occurred. The statuses
`CREATED` and `FAILED` return an `ExecutionDate` of `null`.
title: TransactionExecutionDate
TransactionNature:
type: string
description: >-
**Returned values:** `REGULAR`, `REPUDIATION`, `REFUND`, `SETTLEMENT`
The nature of the transaction, providing more information about the
context in which the transaction occurred:
- `REGULAR` – Relative to most of the transactions (pay-ins, payouts,
and transfers) in a usual workflow.
- `REPUDIATION` – Automatic withdrawal of funds from the platform's
repudiation wallet as part of the dispute process (when the user has
requested a chargeback).
- `REFUND` – Reimbursement of a transaction to the user (pay-in refund),
to a wallet (transfer refund), or of a payout (payout refund, only
initiated by Mangopay).
- `SETTLEMENT` – Transfer made to the repudiation wallet by the platform
to settle a lost dispute.
title: TransactionNature
RepudiationRefundResponseRefundReason:
type: object
properties:
RefundReasonMessage:
type: string
description: Message explaining the reason for the refund.
RefundReasonType:
type: string
description: >-
**Returned values:** `INITIALIZED_BY_CLIENT`,
`BANKACCOUNT_INCORRECT`, `OWNER_DO_NOT_MATCH_BANKACCOUNT`,
`BANKACCOUNT_HAS_BEEN_CLOSED`,
`WITHDRAWAL_IMPOSSIBLE_ON_SAVINGS_ACCOUNTS`, `OTHER`
The type of reason for the refund.
description: Information about the reasons for the repudiation return.
title: RepudiationRefundResponseRefundReason
RepudiationRefundResponse:
type: object
properties:
Id:
$ref: '#/components/schemas/Id'
Tag:
$ref: '#/components/schemas/Tag'
CreationDate:
$ref: '#/components/schemas/CreationDate'
AuthorId:
type: string
description: >-
The unique identifier of the user at the source of the initial
transaction.
CreditedUserId:
$ref: '#/components/schemas/CreditedUserId'
DebitedFunds:
$ref: '#/components/schemas/RepudiationRefundResponseDebitedFunds'
description: Information about the debited funds.
CreditedFunds:
$ref: '#/components/schemas/RepudiationRefundResponseCreditedFunds'
description: >-
Information about the credited funds (`CreditedFunds` =
`DebitedFunds` - `Fees`).
Fees:
$ref: '#/components/schemas/RepudiationRefundResponseFees'
description: Information about the fees.
Status:
$ref: '#/components/schemas/TransactionStatus'
ResultCode:
$ref: '#/components/schemas/ResultCode'
ResultMessage:
$ref: '#/components/schemas/ResultMessage'
ExecutionDate:
$ref: '#/components/schemas/TransactionExecutionDate'
Type:
type: string
description: >-
**Returned values:** `PAYIN`
The type of the transaction. Repudiation returns are recorded as
pay-ins crediting the Repudiation Wallet.
Nature:
$ref: '#/components/schemas/TransactionNature'
InitialTransactionId:
type: string
description: The unique identifier of the initial repudiation being refunded.
InitialTransactionType:
type: string
description: |-
**Returned values:** `PAYOUT`
The type of the initial transaction being refunded.
InitialTransactionNature:
type: string
description: |-
**Returned values:** `REPUDIATION`
The nature of the initial transaction being refunded.
DebitedWalletId:
type: string
description: >-
The unique identifier of the debited wallet. Not returned for
repudiation returns.
CreditedWalletId:
type: string
description: >-
The unique identifier of the Repudiation Wallet re-credited with the
returned funds (for example, `CREDIT_EUR`).
RefundReason:
$ref: '#/components/schemas/RepudiationRefundResponseRefundReason'
description: Information about the reasons for the repudiation return.
StatementDescriptor:
type: string
description: >-
Max. length: 10 characters; only alphanumeric and spaces
Custom description to appear on the user's bank statement along with
the platform name. Different banks may show more or less
information. See the Customizing bank
statement references article for details.
**Note:** On refunds, the `StatementDescriptor` is only available
for SEPA and BACS [direct debit
pay-ins](/api-reference/direct-debit-payins/create-direct-debit-payin)
(no other payment methods nor transfers).
title: RepudiationRefundResponse
```
### Related resources
#### [Refunds](/guides/refunds)
Learn more about pay-in and transfer refunds
#### [Payouts](/guides/payouts)
Learn more about payout returns
#### [Disputes](/guides/disputes)
Learn more about disputes and repudiations