Refunds
API ReferenceRefundsCreate
Create Refund
Create a new refund for a completed payment.
POST /refunds
Body Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
payment_id | string | Yes | The ID of the payment to refund. |
refund_id | string | No | Your own unique identifier for this refund (max 30 chars). Pass it to make the request idempotent across retries — useful when running multiple partial refunds against the same payment. If omitted, the platform generates one. UUID v4 is recommended. |
amount | integer | No | Amount to refund in the smallest currency denomination. Defaults to the full payment amount when omitted. Minimum 100. |
reason | string | No | Reason for the refund (max 255 chars). For Stripe-routed payments, use one of duplicate, fraudulent, or requested_by_customer. |
refund_type | string | No | One of Instant (default) or Scheduled. Scheduled queues the refund for the next batch settlement window the connector supports. |
metadata | object | No | Up to 50 key-value pairs (key max 40 chars, value max 500 chars) for your own bookkeeping. |
Request Example
curl -X POST 'https://api.v2.paychtec.com/refunds' \ -H "Content-Type: application/json" \ -H "api-key: snd_YOUR_API_KEY" \ -d '{ "payment_id": "pay_mbabizu24mvu3mela5njyhpit4", "amount": 500, "reason": "Customer requested refund"}'Response
{
"refund_id": "ref_1234567890abcdef",
"payment_id": "pay_mbabizu24mvu3mela5njyhpit4",
"amount": 500,
"currency": "USD",
"status": "succeeded",
"reason": "Customer requested refund",
"created": "2024-01-22T14:00:00Z"
}