Refunds

Refunds are server-side operations. Use your secret API key for all refund endpoints.

Create a Refund

POST /refunds

GET //sandbox.perfectpay.ai/refunds

curl https://sandbox.perfectpay.ai/refunds \
  -X POST \
  -H "api-key: YOUR_SECRET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "payment_id": "pay_mbabizu24mvu3mela5njyhpit4",
    "amount": 1500,
    "reason": "Customer requested partial refund"
  }'

Response excerpt:

JSON

{
  "refund_id": "ref_abc123",
  "payment_id": "pay_mbabizu24mvu3mela5njyhpit4",
  "amount": 1500,
  "status": "pending",
  "created_at": "2026-03-22T15:08:12Z"
}

Omit amount to refund the full payment amount.

Refund Status Values

Status	Meaning
`pending`	Accepted and still processing
`review`	Held for manual or processor review
`succeeded`	Refund completed
`failed`	Refund could not be completed

Retrieve a Refund

GET /refunds/{refund_id}

GET //sandbox.perfectpay.ai/refunds/ref_abc123

curl https://sandbox.perfectpay.ai/refunds/ref_abc123 \
  -H "api-key: YOUR_SECRET_API_KEY"

List Refunds

POST /refunds/list

GET //sandbox.perfectpay.ai/refunds/list

curl https://sandbox.perfectpay.ai/refunds/list \
  -X POST \
  -H "api-key: YOUR_SECRET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Use this endpoint for reconciliation, customer support tooling, and admin dashboards. You can filter by payment_id, date range, and status.