Refunds

When a payout or a payin fails after funds have moved, Mural returns the funds automatically. You do not need to start, approve, or track the refund yourself. There is no refund endpoint. Follow the status of the payout or payin to see where a refund stands.

Payout refunds

When a fiat payout fails, Mural returns the funds to the Account that sent the payout.

Statuses

Each fiat payout reports its status in details.fiatPayoutStatus.type. A refunded payout moves through these statuses:

pending → refundInProgress → refunded

`fiatPayoutStatus.type`	Meaning	Fields
`refundInProgress`	The payout failed and the refund to your Account has started.	`failureReason`, `errorCode`, `initiatedAt`, `refundInitiatedAt`
`refunded`	The refund is complete and the funds are back in your Account. Terminal.	`failureReason`, `errorCode`, `initiatedAt`, `refundInitiatedAt`, `refundCompletedAt`, `refundTransactionId`

refundTransactionId identifies the incoming refund in the Transactions API. The refund appears as a deposit to the Account that sent the payout. Any developer fee you charged on the payout is reversed.

errorCode tells you why the payout failed. The get Payout Request endpoint reference lists every value. Correct the recipient details, then send a new Payout Request.

The Payout Request status does not change. A Payout Request's statusV2.type stays executed while one of its payouts is refunded. executed means the funds left your Account, not that each recipient received them. Check the status of each payout in payouts.

Payin refunds

Mural returns a payin to the payer when it cannot credit the funds to your Account. For example, the payer sends funds after a payin intent has expired. The refund goes back to the payer over the rail they paid with.

Statuses

A refunded payin moves through these statuses:

created → canceled → refunded

`payinStatus.type`	Meaning
`canceled`	The payin intent expired or was canceled. If funds arrive after this, the payin stays `canceled` while the refund is in progress.
`refunded`	The funds were returned to the payer.

A refunded payin carries refundedAt and a refundInfo object. refundInfo.type tells you why the funds were returned:

`refundInfo.type`	Meaning	Fields
`payinAfterExpiry`	The payer sent funds after the payin intent expired.	`expiredAt`, `receivedAt`
`providerInitiated`	The payment provider returned the funds to the payer.	none

A payin that the sending bank returns before it settles moves to failed, not refunded. No funds reach your Account.

Webhooks

Subscribe to webhook events to follow refunds as they happen. See Event Types.

payout_status_changed fires when a payout moves to refundInProgress and again when it moves to refunded. The payload carries only the status type. Fetch the Payout Request for errorCode, failureReason, and refundTransactionId.
payin_status_changed fires when a payin moves to refunded.

Sandbox: a simulated payout failure returns the funds to your Account and shows the payout as failed, not refundInProgress or refunded. To trigger a failure, see Simulated Payments.