> For the complete documentation index, see [llms.txt](https://docs.loomgate.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.loomgate.io/en/api-reference/refunds.md).

# Refunds

Refund payments, retrieve and list refunds.

The refund rules (fees are not refunded, `amount_refundable`, refund fees, idempotency) are described in [Refunds](/en/concepts/refunds.md).

## Refund a succeeded payment

> Fees are never refunded: at most the payment's \`amount\_refundable\` (amount\_total less the processing and bank fees, less what was refunded). Omit \`amount\` to refund all of it. Partial refunds may be repeated. With an \`Idempotency-Key\`, the same key and body return the refund made by the first request (same id, current status) and never refund twice; the same key with a different body, or a key already used to create a payment intent, is a 409.

```json
{"openapi":"3.0.0","info":{"title":"Loomgate API","version":"v1"},"tags":[{"name":"Refunds","description":"Give money back to the buyer of a succeeded payment. Fees are never refunded."}],"servers":[{"url":"https://api.loomgate.io"}],"security":[{"secret_key":[]}],"components":{"securitySchemes":{"secret_key":{"scheme":"bearer","type":"http","description":"Secret key `sk_live_…` (server-side only)."}},"schemas":{"CreateRefundRequest":{"type":"object","properties":{"payment_intent":{"type":"string","description":"A succeeded payment intent."},"amount":{"type":"integer","minimum":1,"nullable":true,"description":"Minor units, at most the payment's `amount_refundable` (fees are never refunded). Omit to refund all of it."},"reason":{"type":"string","nullable":true,"maxLength":500}},"required":["payment_intent"]},"Refund":{"type":"object","properties":{"id":{"type":"string"},"object":{"type":"string","enum":["refund"]},"payment_intent":{"type":"string"},"amount":{"type":"integer","description":"Returned to the buyer, at most amount_refundable of the payment: fees are never refunded."},"refund_fee":{"type":"integer","description":"Refund fee charged to the merchant."},"status":{"type":"string","enum":["pending","processing","succeeded","failed"]},"reason":{"type":"string","nullable":true},"created":{"type":"integer","description":"Unix seconds."}},"required":["id","object","payment_intent","amount","refund_fee","status","reason","created"]},"ErrorResponse":{"type":"object","properties":{"error":{"$ref":"#/components/schemas/Error"}},"required":["error"]},"Error":{"type":"object","properties":{"type":{"type":"string","enum":["invalid_request_error","authentication_error","card_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string","description":"The request field at fault."},"decline_code":{"type":"string","description":"Card declines only, when the reason is known."}},"required":["type","code","message"]}}},"paths":{"/partner/v1/refunds":{"post":{"description":"Fees are never refunded: at most the payment's `amount_refundable` (amount_total less the processing and bank fees, less what was refunded). Omit `amount` to refund all of it. Partial refunds may be repeated. With an `Idempotency-Key`, the same key and body return the refund made by the first request (same id, current status) and never refund twice; the same key with a different body, or a key already used to create a payment intent, is a 409.","operationId":"createRefund","parameters":[{"name":"Idempotency-Key","required":false,"in":"header","description":"1 to 255 characters.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateRefundRequest"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Refund"}}}},"400":{"description":"invalid_request_error: `validation_error` or a more specific code; `param` names the field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"authentication_error: missing, invalid or revoked key / client secret.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"invalid_request_error: no such object.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"invalid_request_error: `idempotency_key_reused`, or `payment_intent_updated` on confirm (the amount changed since the card form was loaded: load the form again, then confirm).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"rate_limit_error: `rate_limited`, too many requests; retry after the `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"api_error: `internal_error`, or `fee_plan_not_configured` when no fee schedule applies.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"502":{"description":"api_error: `provider_error`, the payment could not be processed; retry later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"summary":"Refund a succeeded payment","tags":["Refunds"]}}}}
```

## GET /partner/v1/refunds/{id}

> Retrieve a refund

```json
{"openapi":"3.0.0","info":{"title":"Loomgate API","version":"v1"},"tags":[{"name":"Refunds","description":"Give money back to the buyer of a succeeded payment. Fees are never refunded."}],"servers":[{"url":"https://api.loomgate.io"}],"security":[{"secret_key":[]}],"components":{"securitySchemes":{"secret_key":{"scheme":"bearer","type":"http","description":"Secret key `sk_live_…` (server-side only)."}},"schemas":{"Refund":{"type":"object","properties":{"id":{"type":"string"},"object":{"type":"string","enum":["refund"]},"payment_intent":{"type":"string"},"amount":{"type":"integer","description":"Returned to the buyer, at most amount_refundable of the payment: fees are never refunded."},"refund_fee":{"type":"integer","description":"Refund fee charged to the merchant."},"status":{"type":"string","enum":["pending","processing","succeeded","failed"]},"reason":{"type":"string","nullable":true},"created":{"type":"integer","description":"Unix seconds."}},"required":["id","object","payment_intent","amount","refund_fee","status","reason","created"]},"ErrorResponse":{"type":"object","properties":{"error":{"$ref":"#/components/schemas/Error"}},"required":["error"]},"Error":{"type":"object","properties":{"type":{"type":"string","enum":["invalid_request_error","authentication_error","card_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string","description":"The request field at fault."},"decline_code":{"type":"string","description":"Card declines only, when the reason is known."}},"required":["type","code","message"]}}},"paths":{"/partner/v1/refunds/{id}":{"get":{"operationId":"retrieveRefund","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Refund"}}}},"400":{"description":"invalid_request_error: `validation_error` or a more specific code; `param` names the field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"authentication_error: missing, invalid or revoked key / client secret.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"invalid_request_error: no such object.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"rate_limit_error: `rate_limited`, too many requests; retry after the `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"summary":"Retrieve a refund","tags":["Refunds"]}}}}
```

## List refunds

> Newest first, optionally for one payment intent.

```json
{"openapi":"3.0.0","info":{"title":"Loomgate API","version":"v1"},"tags":[{"name":"Refunds","description":"Give money back to the buyer of a succeeded payment. Fees are never refunded."}],"servers":[{"url":"https://api.loomgate.io"}],"security":[{"secret_key":[]}],"components":{"securitySchemes":{"secret_key":{"scheme":"bearer","type":"http","description":"Secret key `sk_live_…` (server-side only)."}},"schemas":{"RefundList":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"$ref":"#/components/schemas/Refund"}},"has_more":{"type":"boolean"}},"required":["object","data","has_more"]},"Refund":{"type":"object","properties":{"id":{"type":"string"},"object":{"type":"string","enum":["refund"]},"payment_intent":{"type":"string"},"amount":{"type":"integer","description":"Returned to the buyer, at most amount_refundable of the payment: fees are never refunded."},"refund_fee":{"type":"integer","description":"Refund fee charged to the merchant."},"status":{"type":"string","enum":["pending","processing","succeeded","failed"]},"reason":{"type":"string","nullable":true},"created":{"type":"integer","description":"Unix seconds."}},"required":["id","object","payment_intent","amount","refund_fee","status","reason","created"]},"ErrorResponse":{"type":"object","properties":{"error":{"$ref":"#/components/schemas/Error"}},"required":["error"]},"Error":{"type":"object","properties":{"type":{"type":"string","enum":["invalid_request_error","authentication_error","card_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string","description":"The request field at fault."},"decline_code":{"type":"string","description":"Card declines only, when the reason is known."}},"required":["type","code","message"]}}},"paths":{"/partner/v1/refunds":{"get":{"description":"Newest first, optionally for one payment intent.","operationId":"listRefunds","parameters":[{"name":"limit","required":false,"in":"query","description":"Page size.","schema":{"minimum":1,"maximum":100,"default":20,"type":"integer"}},{"name":"starting_after","required":false,"in":"query","description":"Id of the last object of the previous page.","schema":{"type":"string"}},{"name":"payment_intent","required":false,"in":"query","description":"Only refunds of this payment intent.","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RefundList"}}}},"400":{"description":"invalid_request_error: `validation_error` or a more specific code; `param` names the field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"authentication_error: missing, invalid or revoked key / client secret.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"invalid_request_error: no such object.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"rate_limit_error: `rate_limited`, too many requests; retry after the `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"summary":"List refunds","tags":["Refunds"]}}}}
```

## The refund object

## The Refund object

```json
{"openapi":"3.0.0","info":{"title":"Loomgate API","version":"v1"},"components":{"schemas":{"Refund":{"type":"object","properties":{"id":{"type":"string"},"object":{"type":"string","enum":["refund"]},"payment_intent":{"type":"string"},"amount":{"type":"integer","description":"Returned to the buyer, at most amount_refundable of the payment: fees are never refunded."},"refund_fee":{"type":"integer","description":"Refund fee charged to the merchant."},"status":{"type":"string","enum":["pending","processing","succeeded","failed"]},"reason":{"type":"string","nullable":true},"created":{"type":"integer","description":"Unix seconds."}},"required":["id","object","payment_intent","amount","refund_fee","status","reason","created"]}}}}
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.loomgate.io/en/api-reference/refunds.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.