API Reference · Payments

Refund a payment

Refunds all or part of a payment back to the customer.

POST/v1/payments/:id/refund

Omit `amount` for a full refund. Partial refunds are allowed as long as the total refunded never exceeds the original amount. LuniPay also reverses the platform fee proportionally and emits `payment.refunded`.

Path parameters

idstringRequired

Payment id (`pay_…`).

Body parameters

amountinteger

Amount to refund, in the smallest currency unit. Defaults to the full remaining amount.

reasonstring

Refund reason shown on the dashboard.

Allowed values: duplicate fraudulent requested_by_customer

metadataobject

Up to 20 key/value pairs attached to the refund.

Errors

404

resource_missing

No payment exists with that id.

409

refund_exceeds_remaining

Requested amount is greater than the remaining refundable balance.

409

payment_not_refundable

Payment is not in a state that can be refunded (e.g., FAILED or already REFUNDED).

Request

curl -X POST https://lunipay.io/api/v1/payments/pay_01JRZK9XA0PMK4JHGF7Z3V8TRC/refund \
  -H "Authorization: Bearer sk_test_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "amount": 5000, "reason": "requested_by_customer" }'

Response

{
  "id": "re_01JRZKABXWK5TFH9C8MVN3QESJ",
  "object": "refund",
  "payment_id": "pay_01JRZK9XA0PMK4JHGF7Z3V8TRC",
  "amount_cents": 5000,
  "currency": "usd",
  "status": "SUCCEEDED",
  "reason": "requested_by_customer",
  "created": 1713101000
}