---
title: "Reserve credit against a payment for refund"
method: POST
path: "/v1/billing/funding/refunds"
---

# Reserve credit against a payment for refund

`POST /v1/billing/funding/refunds`

## Request

- Base URL: `https://docs.greatwait.dev` (the document declares no server; this is the origin it was published from)
- URL: `https://docs.greatwait.dev/v1/billing/funding/refunds`
- Auth: HTTP bearer

Reserves unused purchased execution credit against one original payment, with the billing owner's explicit confirmation. Purchased credit is not refundable except where a charge is refunded because the service did not work as described, so this records no promise of a refund: it never calls Stripe, cashes out credit or grants an MCP cash-out path. A Stripe refund of that payment settles the reservation when it carries the same credit and supersedes it otherwise; the Idempotency-Key preserves one reservation across retries. Trial credit has no cash value, and a refund does not restore automatic purchasing authority used in the month.

## Headers

- `Idempotency-Key` string, required

## Request body

- object
  - `amount` object, required
    - `currency` 'USD', required
    - `microdollars` string, required: A canonical nonnegative integer multiple of 10,000 microdollars, no greater than 9,223,372,036,854,770,000.
    - `scale` 6, required
  - `confirmed` true, required
  - `paymentOperation` string, required
  - `reason` string, required

## Response `201`

Reserve credit against a payment for refund

- object
  - `amount` object, required
    - `currency` 'USD', required
    - `microdollars` string, required: A canonical nonnegative integer multiple of 10,000 microdollars, no greater than 9,223,372,036,854,770,000.
    - `scale` 6, required
  - `id` string, required
  - `paymentOperation` string, required
  - `requestedAt` string, required
  - `state` 'operator-review-pending', required

## Other responses

- `400`: Problem document. Possible codes at this status: invalid_request.
- `401`: Problem document. Possible codes at this status: authentication_required, credential_expired, credential_revoked.
- `403`: Problem document. Possible codes at this status: scope_missing, test_to_live_escalation.
- `404`: Problem document. Possible codes at this status: not_found.
- `409`: Problem document. Possible codes at this status: idempotency_key_reused, project_archived, state_conflict.
- `429`: Problem document. Possible codes at this status: rate_limited.
- `503`: Problem document. Possible codes at this status: capability_not_configured, service_unavailable.

---

[API](https://skmtc.dev/greatwait/apis/greatwait-v1.md) · [All operations](https://skmtc.dev/greatwait/apis/greatwait-v1/llms.txt) · [OpenAPI document](https://skmtc.dev/greatwait/apis/greatwait-v1/revisions/6855bce23e72?raw)