Refund a payment

A refund returns money to the customer. Behind the scenes Paylera issues a credit note against the original invoice, reverses the ledger postings, and adjusts any active revenue-recognition schedule.

Full refund

POST /v1/payments/{id}/refunds
Idempotency-Key: <uuid>
{
  "reason": "service_outage"
}

Refunds the full payment amount to the original payment method. Allowed reason values: duplicate, fraudulent, customer_request, order_change, service_outage, product_unsatisfactory, other.

Partial refund

POST /v1/payments/{id}/refunds
Idempotency-Key: <uuid>
{
  "amount": "25.00",
  "reason": "order_change"
}

The sum of refunds against a single payment cannot exceed the payment amount. The API rejects the second refund attempt that would cross the line.

Refund to a wallet instead

POST /v1/payments/{id}/refunds
{
  "amount": "25.00",
  "reason": "customer_request",
  "destination": "wallet"
}

The amount lands in the customer’s wallet (in the payment currency) instead of returning to the card. Useful when the customer prefers credit, or when the card has been closed since the original charge.

A wallet-destined refund still issues a credit note — the ledger model sees it identically; the only difference is which liability account holds the money.

What happens automatically

1. A credit note is created against the original invoice (outcome: refund for card refunds, outcome: credit_balance for wallet refunds).
2. The ledger posts the reversing entries.
3. Any open revenue-recognition schedule for the originating line item is adjusted: future scheduled rows are deleted; already-recognised amounts post a reversal in the next period.
4. If the original payment came from an affiliate-attributed customer within the commission hold period, the affiliate commission is also reversed.
5. Webhook events fire (see below).

When refunds fail

Refunds can fail at the provider — the card is closed, the network is out, the issuer rejects. The credit note still issues; the outcome.refund_status is failed, and Paylera retries on a backoff schedule. After 5 failed attempts (over ~24h), the credit note moves to outcome.kind: pending_manual and emits credit_note.refund_failed. From there it’s an operator decision — typically: refund to wallet instead, or contact the customer for an alternative method.

Reversing a chargeback

Chargebacks ride a different path: the provider initiates them, and Paylera reflects them via webhook. You typically don’t issue a refund for a charged-back payment — the provider has already pulled the funds.

If you decide to refund a customer who later charges back the same payment, the refund still attempts (and likely fails because the provider sees the funds already returned). Inspect payment.charged_back events and let dispute resolution take its course.

Refund eligibility

A payment can be refunded when:

• It is succeeded.
• The provider’s refund window is still open (typically 180 days for cards; varies for ACH/SEPA).
• The sum of existing refunds is less than the payment amount.

A failed payment cannot be refunded — there’s no money to return. A requires_action payment cannot be refunded; cancel the payment instead with POST /v1/payments/{id}/cancel.

Idempotency on refunds

Use a fresh Idempotency-Key per refund attempt. Reusing the key from the original payment doesn’t help (different route).

Webhook events

Event	When
refund.created	Refund object created.
refund.succeeded	Provider returned the funds.
refund.failed	Provider rejected the refund.
credit_note.created	The accompanying credit note.
subscription.refund_processed	(For subscription invoices) the recognition schedule was adjusted.
commission.reversed	Affiliate commission was unwound.