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
Request Body
Amount to refund in cents (defaults to full payment amount)
Refund reason: “duplicate”, “fraudulent”, “requested_by_customer”, “defective”, “other”
Internal notes about the refund
Whether to send refund notification email (default: true)
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"
}
}
