Refunds

Refund all or part of a succeeded payment. Full refunds move the payment to status: refunded; partial refunds leave the payment as succeeded with a smaller remaining balance.

Full refund

curl -X POST https://magiapay.innoserver.cloud/v1/refunds \
  -H "Authorization: Bearer sk_live_..." \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{ "payment": "pay_0e1f...", "reason": "requested_by_customer" }'

Partial refund

Include amount to refund less than the full payment:

Partial refund

curl -X POST https://magiapay.innoserver.cloud/v1/refunds \
  -H "Authorization: Bearer sk_live_..." \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{ "payment": "pay_0e1f...", "amount": 100.00, "reason": "other" }'

List refunds for a payment

bash

curl "https://magiapay.innoserver.cloud/v1/refunds?payment=pay_0e1f...&limit=50" \
  -H "Authorization: Bearer sk_live_..."

Reason codes

Code	When to use
`duplicate`	Same payment charged twice.
`fraudulent`	Payment was unauthorised / chargeback.
`requested_by_customer`	Customer asked for a refund.
`other`	Anything else — include details in your own records.

Constraints

You can only refund a payment with status: succeeded.
Total refunded amount across all refunds cannot exceed the original payment amount.
Refund processing is synchronous for most methods in v1 — the response is the final state.
The ledger is debited at refund creation time (not later). Partial refunds leave the payment's net_amount untouched; your balance reflects the cumulative impact.

Errors

HTTP	code	Cause
400	`invalid_state`	Payment is not in `succeeded` status.
400	`invalid_request`	Refund amount exceeds remaining balance.
404	`not_found`	Payment id not found for this merchant / environment.