POST
/
v1
/
payments
/
:id
/
refund
curl --location --request POST 'https://api.stateset.com/v1/payments/pay_0901f083-aa1c-43c5-af5c-0a9d2fc64e30/refund' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_API_KEY' \
--data-raw '{
    "amount": 5000,
    "reason": "requested_by_customer",
    "notes": "Customer returned item"
}'

{
  "id": "ref_1234567890abcdef",
  "object": "refund",
  "amount": 5000,
  "currency": "USD",
  "payment_id": "pay_0901f083-aa1c-43c5-af5c-0a9d2fc64e30",
  "status": "succeeded",
  "reason": "requested_by_customer",
  "notes": "Customer returned item",
  "created_at": "2024-01-20T10:00:00Z",
  "processed_at": "2024-01-20T10:00:05Z",
  "payment": {
    "id": "pay_0901f083-aa1c-43c5-af5c-0a9d2fc64e30",
    "amount": 15000,
    "amount_refunded": 5000,
    "refunds_count": 1
  },
  "processor_refund_id": "re_1234567890",
  "receipt_url": "https://receipts.stateset.com/ref_1234567890abcdef",
  "metadata": {
    "return_id": "ret_abc123"
  }
}
This endpoint creates a refund for a captured payment. Refunds can be partial or full amount.

​
Authentication

This endpoint requires a valid API key with payments:write permissions. 
Authorization: Bearer YOUR_API_KEY

​
Path Parameters

​
id
string
required
The payment ID to refund

​
Request Body

​
amount
integer
Amount to refund in cents (defaults to full payment amount)
​
reason
string
required
Refund reason: “duplicate”, “fraudulent”, “requested_by_customer”, “defective”, “other”
​
notes
string
Internal notes about the refund
​
notify_customer
boolean
Whether to send refund notification email (default: true)
​
metadata
object
Additional metadata for the refund

​
Response

Returns the refund object. 
curl --location --request POST 'https://api.stateset.com/v1/payments/pay_0901f083-aa1c-43c5-af5c-0a9d2fc64e30/refund' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_API_KEY' \
--data-raw '{
    "amount": 5000,
    "reason": "requested_by_customer",
    "notes": "Customer returned item"
}'

{
  "id": "ref_1234567890abcdef",
  "object": "refund",
  "amount": 5000,
  "currency": "USD",
  "payment_id": "pay_0901f083-aa1c-43c5-af5c-0a9d2fc64e30",
  "status": "succeeded",
  "reason": "requested_by_customer",
  "notes": "Customer returned item",
  "created_at": "2024-01-20T10:00:00Z",
  "processed_at": "2024-01-20T10:00:05Z",
  "payment": {
    "id": "pay_0901f083-aa1c-43c5-af5c-0a9d2fc64e30",
    "amount": 15000,
    "amount_refunded": 5000,
    "refunds_count": 1
  },
  "processor_refund_id": "re_1234567890",
  "receipt_url": "https://receipts.stateset.com/ref_1234567890abcdef",
  "metadata": {
    "return_id": "ret_abc123"
  }
}