curl --request POST \
--url https://api.gigstack.io/v2/payments/{id}/refund \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"reason": "Customer requested cancellation",
"amount": 1160,
"external_processor_refund": true
}
'const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
reason: 'Customer requested cancellation',
amount: 1160,
external_processor_refund: true
})
};
fetch('https://api.gigstack.io/v2/payments/{id}/refund', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));import requests
url = "https://api.gigstack.io/v2/payments/{id}/refund"
payload = {
"reason": "Customer requested cancellation",
"amount": 1160,
"external_processor_refund": True
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text){
"success": true,
"data": {
"refund": {
"id": "re_example",
"reason": "Agreed partial refund",
"total": 116,
"status": "succeeded",
"timestamp": 1767225600000,
"from": "api",
"external_processor_refund": false
},
"payment": {
"id": "payment_example",
"amount": 116000,
"total_refunded": 11600,
"refund_status": "requires_action"
}
},
"message": "Refund processed successfully",
"timestamp": 1767225600000
}Refund payment
Integration note: Choose record-only versus an eligible Stripe refund before calling. amount is in currency units; response data.payment.amount and total_refunded are in minor units. Internal refund.status succeeded does not prove processor settlement. No idempotency key is documented for this endpoint.
Refund a payment with a specified reason and amount.
gigstack Connect: Refund other teams’ payments using the team parameter.
Key Features
- Partial or full refunds supported
- Optional external processor refund handling
- Automatic refund tracking and reporting
- Supports Stripe integration for automatic processor refunds
reason and amount are both required. amount must be at least 0.01 — the
validator rejects anything below it.
curl --request POST \
--url https://api.gigstack.io/v2/payments/{id}/refund \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"reason": "Customer requested cancellation",
"amount": 1160,
"external_processor_refund": true
}
'const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
reason: 'Customer requested cancellation',
amount: 1160,
external_processor_refund: true
})
};
fetch('https://api.gigstack.io/v2/payments/{id}/refund', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));import requests
url = "https://api.gigstack.io/v2/payments/{id}/refund"
payload = {
"reason": "Customer requested cancellation",
"amount": 1160,
"external_processor_refund": True
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text){
"success": true,
"data": {
"refund": {
"id": "re_example",
"reason": "Agreed partial refund",
"total": 116,
"status": "succeeded",
"timestamp": 1767225600000,
"from": "api",
"external_processor_refund": false
},
"payment": {
"id": "payment_example",
"amount": 116000,
"total_refunded": 11600,
"refund_status": "requires_action"
}
},
"message": "Refund processed successfully",
"timestamp": 1767225600000
}Authorizations
Authentication Method: HTTP Bearer token.
The runtime requires the literal Bearer prefix — a bare token in the
Authorization header is rejected with 401 unauthorized.
Header Format: Authorization: Bearer YOUR_API_KEY
Your API key is a JWT. Live keys operate on live data (livemode: true);
test keys operate on isolated test data (livemode: false).
Get your key at: app.gigstack.pro/settings?tab=api
Errors: credential failures are answered by the authentication layer with a raw
{ "message": … } body, not the standardized envelope — 401 for a missing, malformed or
expired token, 403 for a revoked key or a plan without API access. See the Unauthorized
and AuthForbidden responses.
Path Parameters
Payment id.
Query Parameters
gigstack Connect: Target team ID for multi-team access.
Requires gigstack Connect enabled on your team and shared billing account.
Also requires the multipleIssuerAccounts feature on your plan. Requests targeting a
team other than the one your API key belongs to return 403 without it.
Only API keys can use it: an OAuth access token sent with another team's id is rejected with
403 Team mismatch with OAuth token.
Optional — omit it entirely unless you are acting on another team. It deliberately
carries no example value so generated snippets do not emit ?team=undefined; when the
parameter is absent, the team is derived from your API key.
Example: ?team=team_xyz789
Body
Reason for the refund
"Customer requested cancellation"
Amount to refund, in the payment currency. Validation requires at least 0.01. The cumulative refunded total may not exceed the payment amount.
x >= 0.011160
Whether to process refund through external payment processor
false
Response
Payment refunded successfully
Standardized success envelope emitted by sendSuccessResponse.
true true
The operation payload.
Show child attributes
Show child attributes
Server time in epoch milliseconds (Luxon.now().toMillis()).
1767225600000
Human-readable summary. Present only when the handler supplies one.
"Operation completed successfully"