Refunds

A refund returns money to a customer against a payment they made. It is the money-out counterpart to a payment. A refund does not un-pay the original invoice, because invoices do not change once issued. Instead it is handled on the customer's account balance.

Two ways to give money back

• Online. Send the refund back through the gateway to the card or bank the customer paid with. The money returns to their original payment method.
• Offline. Record that you returned the money some other way, outside yRecurring, so your records match.

Reverse or goodwill

When you refund, you choose what it does to the customer's balance. The cash you return is the same either way; the difference is whether they still owe it.

Mode	What it does	Use it when
Reverse (default)	Returns the money and re-opens the balance, so the customer owes it again.	The payment was a duplicate, a mistake, or something you will collect again.
Goodwill	Returns the money and forgives the debt, so the customer's balance does not change.	A service credit, an apology, or a partial cancellation your business is absorbing.

Reverse says "here is your money back, but this is still owed." Goodwill says "here is your money back, and we are letting it go."

Reasons

A refund records why it happened: requested by the customer, a duplicate, fraudulent, a chargeback, or other. The reason is kept with the refund for your records, and it is what reports use to tell money you chose to return from money that was taken from you.

Chargebacks

A chargeback is the customer's bank taking a payment back after a dispute. yRecurring records it as a refund with the reason Chargeback, so the money leaving shows on the customer's account, on the invoice, and in your reports.

• It happens by itself. When your gateway reports that a dispute closed against you (or you accepted it), the chargeback is recorded automatically for the amount that was disputed, never more than the payment was worth. Nothing is recorded while a dispute is still open, because until it closes the money may still come back.
• It is written off. A lost dispute is the bank ruling that the customer does not owe that charge, so the chargeback uses goodwill mode: the customer's balance does not change, and their statement shows the chargeback and the write-off as two lines. The invoice stays paid. If you decide to pursue the money anyway, record it in reverse mode instead, or send an invoice; yRecurring will never charge the card again on its own.
• If the bank changes its mind. Occasionally a lost dispute is reversed later and the money comes back. The chargeback refund is then marked reversed: it stays in the list, struck through, and the statement shows the money returning on the day it did. The payment can be refunded again for its full value.
• Gateways that do not report disputes. Authorize.Net sends no dispute events. Record those chargebacks yourself: refund the payment offline with the reason Chargeback, and it is treated exactly the same way. Chargeback is not offered for online refunds, because nothing is sent to the gateway for a chargeback.
• No email to the customer. A chargeback never triggers the "you have been refunded" notification; their bank returned the money, not you.

Anything the ledger cannot represent is called out on the activity feed rather than rounded away: a dispute claiming more than the payment was worth, or a dispute in a different currency from the payment.

How much you can refund

You can refund up to the original payment amount, minus anything already refunded against it. That means partial refunds and several refunds against one payment are both fine, as long as the total does not go past what was paid.

In the API

Refund a payment with the POST /v1/payments/{id}/refund endpoint, giving the amount, the mode (reverse or goodwill), and a reason. A refund's status can be pending, processing, succeeded, failed, or reversed. See the API reference.

What you cannot refund online

An online refund only works when the original payment was settled online through the gateway, because that is the only way the money can travel back to the card or bank. A payment you recorded offline has no gateway transaction to reverse, so you give that money back your own way and record it as an offline refund.

A payment made from prepaid credits cannot be refunded yet. That case is not supported today.

The refund velocity limit

Online refunds are capped by how much your whole organization refunds within a period. Once your online refunds for the current window reach the limit, further online refunds are held until the window rolls. This is a safety brake: if a key ever leaked, it stops an attacker from draining your gateway through refunds. It applies to the organization total, on top of the per-payment cap that stops any single refund going past what was paid.

Edge cases

• The invoice stays paid. A refund never reopens the invoice itself. Whether the customer owes money again is decided by the mode, on their account balance.
• Online refunds go back to the original method. The gateway returns the money the way it came in.
• A payment not settled online can only be refunded offline. There is no gateway transaction to reverse.
• Prepaid-credits payments cannot be refunded yet.
• The velocity limit is an organization total for the period, not a per-customer or per-payment one.