Request Refund
POST/api/v1/payments/{id}/refunds
- operationId
- payments.RequestRefund
- Permission
- refund.request
- Idempotency
- required
An Idempotency-Key header is required.
Parameters
| Field | in | Type | Required | Description |
|---|---|---|---|---|
| id | path | string | Yes | |
| Idempotency-Key | header | string | Yes | |
| PG-Version | header | string |
Request body
application/json
| Field | Type | Required | Description |
|---|---|---|---|
| amount | Money | ||
| payment_id | string | ||
| reason | string | ||
| reason_code | integer |
Example
A reviewed example request.
{
"amount": {
"minor": 125000,
"currency": "THB"
},
"reason": "Customer returned the order"
}Responses
200 OK
Response headers: `X-Request-Id`
| Field | Type | Required | Description |
|---|---|---|---|
| amount | Money | ||
| created_at | string (date-time) | (date-time) | |
| id | string | ||
| number | string | ||
| payment_id | string | ||
| reason | string | ||
| reason_code | integer | ||
| status | enum | Values: `requested`, `approved`, `rejected`, `canceled`, `processing`, `failed`, `succeeded` | |
| succeeded_at | string (date-time) | (date-time) |
{
"amount": {
"currency": "string",
"minor": 0
},
"created_at": "2026-10-01T09:00:00Z",
"id": "string",
"number": "string",
"payment_id": "string",
"reason": "string",
"reason_code": 0,
"status": "requested",
"succeeded_at": "2026-10-01T09:00:00Z"
}default Error
| Field | Type | Required | Description |
|---|---|---|---|
| code | string | Yes | |
| detail | string | ||
| details | object | ||
| errors | object[] | ||
| errors.code | string | ||
| errors.field | string | ||
| errors.message | string | ||
| instance | string | ||
| status | integer | Yes | |
| title | string | Yes | |
| type | string |
{
"code": "string",
"detail": "string",
"details": {},
"errors": [
{
"code": "string",
"field": "string",
"message": "string"
}
],
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
}Errors
Derived from the modules this operation touches, because the snapshot carries no x-errors list yet — it may list codes this operation cannot return.
Try it
POST/payments/%7Bid%7D/refundsMakes a real call in test mode with your own key. The key stays in this tab and is never sent anywhere but the API.
No API base URL is configured for this environment, so try-it is unavailable.
Starts with pg_test_. A live key is refused before any request is made.
curl -X POST '<API_BASE_URL>/api/v1/payments/%7Bid%7D/refunds' \
-H 'Authorization: Bearer pg_test_…' \
-H 'PG-Version: 2026-09-01' \
-H 'Content-Type: application/json' \
-H 'Idempotency-Key: <uuid v7>' \
-d '{
"amount": {
"minor": 125000,
"currency": "THB"
},
"reason": "Customer returned the order"
}'