> ## Documentation Index
> Fetch the complete documentation index at: https://docs.anyway.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# Create a refund

> Refund a card order, in full or in part.

Authenticate with an API key that belongs to the target organization and has Full access or the `sales:refunds:execute` permission. Only the Owner, Admin and Finance roles can grant it.

* Refunds through the API work only after Anyway has enabled them for your organization; [contact Anyway support](mailto:support@anyway.sh) to turn it on. Until then a refund on one of your orders returns `403` `REFUND_API_NOT_ENABLED`, whatever the key. Order errors, such as `404` for an unknown order, come first.
* Takes the same inputs as the Refund button on an order in the dashboard. Omit `amountCents` to refund everything still refundable. `reason` is optional: `duplicate`, `fraudulent` or `requested_by_customer`. The currency is always the order's.
* Send a unique `Idempotency-Key` header (required; 1–200 ASCII characters from `0x21` to `0x7E`, no spaces). The same key with the same body returns the same refund and never refunds twice. The same key with a different order, amount or reason returns `409`.
* Card orders up to 90 days old only. Contact Anyway support for older orders.
* `200` with `status` `succeeded` means the refund is done. `202` with `status` `pending` means it waits for Anyway's review or for the card network. Review applies when the refund brings the order's total refunded to the approval threshold or above, or takes your organization past its daily refund limit (shared with dashboard refunds); only one refund per order can wait for review at a time. Retry with the same `Idempotency-Key` to get its current state, or wait for the `refund.succeeded` or `refund.failed` [Webhook](https://docs.anyway.sh/api-reference/endpoint/webhooks.md).
* The response is the same refund object as [Get a refund](https://docs.anyway.sh/api-reference/endpoint/get-refund.md). API refunds also show on the order in the dashboard.

| Status | Code | Meaning |
| - | - | - |
| `400` | `BAD_REQUEST` | A missing or invalid `Idempotency-Key`, an unknown field, an amount of 0 or less, or an invalid `reason`. |
| `400` | `REFUND_AMOUNT_TOO_LARGE` | `amountCents` is more than is left to refund on the order. |
| `400` | `REFUND_NOT_REFUNDABLE` | `amountCents` was omitted and nothing is left to refund on the order. |
| `400` | `REFUND_UNSUPPORTED_METHOD` | The order wasn't paid by card. |
| `400` | `REFUND_WINDOW_EXPIRED` | The order is older than 90 days. |
| `400` | `amount_too_large`, `charge_already_refunded` or `charge_disputed` | The card network refuses it: more than is left to refund, already fully refunded, or disputed. |
| `401` | | The API key is missing or invalid. |
| `403` | `INSUFFICIENT_SCOPE` | The key lacks `sales:refunds:execute`. |
| `403` | `REFUND_API_NOT_ENABLED` | Refunds through the API aren't enabled for your organization. Contact Anyway support. |
| `404` | | Unknown order ID, or it belongs to another organization. |
| `409` | `REFUND_PENDING_EXISTS` | Another refund on this order is waiting for review. |
| `409` | `REFUND_IDEMPOTENCY_MISMATCH` | The `Idempotency-Key` was already used with a different order, amount or reason. |
| `409` | `REFUND_FAILED` or `REFUND_REJECTED` | The refund for this `Idempotency-Key` already failed or was rejected. Send a new key to try again. |
| `503` | `REFUND_UNAVAILABLE` | The payment provider is busy or down, or this refund is still in progress. Retry with the same `Idempotency-Key`. |


## OpenAPI

````yaml api-reference/openapi.json POST /v1/refunds
openapi: 3.0.3
info:
  description: >-
    Organization-scoped commerce API for merchant backends: create and manage
    checkout sessions, and query commerce records.
  title: Anyway Merchant API
  contact: {}
  version: '1.0'
  x-source: anyway-backend-go
servers:
  - url: https://merchant-api-prod.anyway.sh
security: []
paths:
  /v1/refunds:
    post:
      tags:
        - refunds
      summary: Create a refund
      description: >-
        Refunds a card order, in full or in part, the same as the Refund button
        in the dashboard. Requires Full access or the `sales:refunds:execute`
        permission, and refunds through the API must be enabled for the
        organization by Anyway (otherwise 403 REFUND_API_NOT_ENABLED). Send a
        unique `Idempotency-Key` (required): the same key with the same body
        returns the same refund; the same key with a different order, amount or
        reason returns 409 REFUND_IDEMPOTENCY_MISMATCH. Card orders only, and
        orders older than 90 days can't be refunded. A refund that reaches the
        approval threshold, or takes the organization past its daily refund
        limit, returns 202 with status pending and waits for Anyway review. If
        the refund is still processing, retry with the same `Idempotency-Key`.
        Unknown request fields return 400. The result is sent as a
        refund.succeeded or refund.failed webhook.
      parameters:
        - description: >-
            Unique creation request key: 1-200 ASCII characters in the range
            0x21-0x7E (no spaces or control characters)
          name: Idempotency-Key
          in: header
          required: true
          schema:
            type: string
            minLength: 1
            maxLength: 200
      requestBody:
        required: true
        description: Order and amount
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/merchantapi.CreateRefundRequest'
      responses:
        '200':
          description: >-
            OK. The refund succeeded, or an earlier request with this
            Idempotency-Key is returned.
          content:
            application/json:
              schema:
                $ref: >-
                  #/components/schemas/response.ApiResponse-merchantapi_RefundResponse
        '202':
          description: >-
            Accepted. The refund is pending: waiting for Anyway review, or still
            processing.
          content:
            application/json:
              schema:
                $ref: >-
                  #/components/schemas/response.ApiResponse-merchantapi_RefundResponse
        '400':
          description: >-
            Bad Request. Missing or invalid Idempotency-Key, an unknown field,
            an amount of 0 or less, an invalid reason, REFUND_UNSUPPORTED_METHOD
            (not a card order), REFUND_WINDOW_EXPIRED (older than 90 days), or
            amount_too_large, charge_already_refunded, charge_disputed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/response.ApiResponse-any'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/response.ApiResponse-any'
        '403':
          description: >-
            Forbidden. The API key lacks the required permission
            (INSUFFICIENT_SCOPE), or refunds through the API are not enabled for
            the organization (REFUND_API_NOT_ENABLED).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/response.ApiResponse-any'
        '404':
          description: Not Found. Unknown order, or it belongs to another organization.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/response.ApiResponse-any'
        '409':
          description: >-
            Conflict. REFUND_PENDING_EXISTS, REFUND_IDEMPOTENCY_MISMATCH, or
            REFUND_FAILED / REFUND_REJECTED for a retried Idempotency-Key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/response.ApiResponse-any'
        '503':
          description: >-
            Service Unavailable. The payment provider is busy or down; retry
            with the same Idempotency-Key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/response.ApiResponse-any'
      security:
        - APIKeyAuth: []
components:
  schemas:
    merchantapi.CreateRefundRequest:
      type: object
      required:
        - orderId
      properties:
        orderId:
          type: string
          description: The order to refund (ORD...). Card orders only.
        amountCents:
          type: integer
          description: >-
            Amount to refund, in the order's currency. Omit to refund everything
            still refundable.
        reason:
          type: string
          enum:
            - duplicate
            - fraudulent
            - requested_by_customer
          description: Optional reason
    response.ApiResponse-merchantapi_RefundResponse:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/merchantapi.RefundResponse'
        error:
          $ref: '#/components/schemas/response.ErrorDetail'
        message:
          type: string
        success:
          type: boolean
    response.ApiResponse-any:
      type: object
      properties:
        data: {}
        error:
          $ref: '#/components/schemas/response.ErrorDetail'
        message:
          type: string
        success:
          type: boolean
    merchantapi.RefundResponse:
      type: object
      properties:
        amountCents:
          description: this refund, in the order's currency
          type: integer
        createdAt:
          description: when the refund was requested
          type: string
        currency:
          description: lowercase ISO 4217
          type: string
        failedAt:
          description: 'failed: when it was rejected or declined'
          type: string
        failureReason:
          description: >-
            FailureReason (failed only) is "rejected" (declined during Anyway's
            review)

            or "declined" (declined when processed).
          type: string
        fullyRefunded:
          type: boolean
        orderId:
          type: string
        orgId:
          type: string
        reason:
          type: string
          nullable: true
        refundId:
          description: Anyway RFN_ id
          type: string
        refundedAt:
          description: 'succeeded: when the payment partner confirmed it'
          type: string
        status:
          description: '"succeeded" | "failed"; Merchant API reads also "pending"'
          type: string
        totalRefundedCents:
          description: >-
            TotalRefundedCents sums every succeeded refund on the order (this
            one

            included when it succeeded); FullyRefunded is true once it reaches
            the

            order's total paid. A webhook carries both as of its event; a
            Merchant API

            read, as of the request. They differ once a later refund on the
            order succeeds.
          type: integer
    response.ErrorDetail:
      type: object
      properties:
        code:
          type: string
        message:
          type: string
  securitySchemes:
    APIKeyAuth:
      description: 'Merchant API key (format: ak_BASE64)'
      type: apiKey
      name: X-API-Key
      in: header

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.