> This page is for Cash App Pay Partner API.

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://developers.cash.app/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://developers.cash.app/_mcp/server.

### Schema (`response.body`)

```yaml
openapi: 3.1.0
info:
  title: API
  version: 1.0.0
paths:
  /refunds:
    post:
      operationId: subpackageRefunds_create-refund
      summary: Create refund
      description: |-
        Creates a refund from a merchant to a customer.

        - To issue a refund, provide a `payment_id` in the request. 

        The grant must be associated with the `ON_FILE_PAYMENT` actions.

        To generate a grant to pass to this field, use the Customer Request API.

        **This endpoint is not rate limited.**

        Scopes: `REFUNDS_WRITE`
      tags:
        - subpackage_refunds
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/refunds_CreateRefundResponse'
        '400':
          description: >-
            Bad Request


            If a `REFUND_DECLINE_*` error is returned, the refund will still be
            created, but with a `DECLINED` status. This refund will then appear
            in the response payload.


            <Note> 

            **`REFUND_DECLINE_*` errors consume one-time use grants.**
             This means you must repeat the Customer Request flow to get a new grant if you want to try issuing
             the refund again. All other errors will not consume grants.
            </Note>
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateRefundRequestBadRequestErrorBody'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                idempotency_key:
                  $ref: '#/components/schemas/IdempotencyKey'
                refund:
                  $ref: '#/components/schemas/refunds_CreateRefundRequestRefund'
                  description: Details about the refund to create.
              required:
                - idempotency_key
                - refund
tags:
  - name: subpackage_refunds
servers:
  - url: https://api.cash.app/network/v1
    description: Production
  - url: https://sandbox.api.cash.app/network/v1
    description: Sandbox
components:
  schemas:
    IdempotencyKey:
      type: string
      minLength: 1
      maxLength: 64
      description: >-
        A unique identifier which can be used by Cash App to de-duplicate
        retries of this request, making it idempotent. For more information, see
        [Idempotency](/cash-app-pay-partner-api/guides/technical-guides/api-fundamentals/idempotency).
      title: IdempotencyKey
    Currency:
      type: string
      enum:
        - USD
      description: >-
        Indicates the country associated with an entity. Values are from the
        [ISO-4217 Alpha-3](https://www.iso.org/iso-4217-currency-codes.html)
        specification.


        Current values:


        - `USD`: United States Dollar
      title: Currency
    Metadata:
      type: object
      additionalProperties:
        type: string
      description: >-
        Freeform key-value pairs of arbitrary data associated with this
        resource.


        Keys and values must be passed as strings and not contain any personally
        identifiable information (PII).


        Min keys: `0`

        Max keys: `50`



        > Note: Nested keys are not supported.
      title: Metadata
    refunds_CreateRefundRequestRefund:
      type: object
      properties:
        amount:
          type: integer
          minimum: 1
          description: >-
            The amount of money to refund the customer, in the lowest
            denomination of currency for the refund.


            Min value: `1`
        currency:
          $ref: '#/components/schemas/Currency'
        merchant_id:
          type: string
          minLength: 1
          maxLength: 128
          description: |-
            ID of the merchant to make the refund from.

            Min length: `1`
            Max length: `128`
        payment_id:
          type: string
          minLength: 1
          maxLength: 128
          description: |-
            For refunds, this is the ID of the payment to refund.

            Min length: `1`
            Max length: `128`
        capture:
          type: boolean
          default: true
          description: >-
            Whether or not to automatically capture the refund once it's
            created.


            Default: `true`
        reference_id:
          type: string
          minLength: 1
          maxLength: 1024
          description: >-
            A user-defined identifier for this refund, typically used to
            associate the refund with a record in an external system.


            Min length: `1`

            Max length: `1024`
        metadata:
          $ref: '#/components/schemas/Metadata'
      required:
        - amount
        - currency
        - merchant_id
      description: Details about the refund to create.
      title: CreateRefundRequestRefund
    refunds_RefundStatus:
      type: string
      enum:
        - AUTHORIZED
        - CAPTURED
        - VOIDED
        - DECLINED
      description: >-
        The step of the refund processing lifecycle that this refund is
        currently at.


        - `AUTHORIZED`

        - `CAPTURED`

        - `VOIDED`

        - `DECLINED`
      title: RefundStatus
    ErrorCategory:
      type: string
      enum:
        - API_ERROR
        - AUTHENTICATION_ERROR
        - BRAND_ERROR
        - DISPUTE_ERROR
        - MERCHANT_ERROR
        - INVALID_REQUEST_ERROR
        - PAYMENT_PROCESSING_ERROR
        - RATE_LIMIT_ERROR
        - WEBHOOK_ERROR
        - API_KEY_ERROR
        - GRANT_ERROR
      description: The high-level reason the error occurred.
      title: ErrorCategory
    Error:
      type: object
      properties:
        category:
          $ref: '#/components/schemas/ErrorCategory'
          description: The high-level reason the error occurred.
        code:
          type: string
          description: >-
            A unique identifier for the specific type of error that occurred.
            For more information, see [Error Code
            Reference](/cash-app-pay-partner-api/guides/technical-guides/api-fundamentals/errors/error-code-reference).


            Min length: `1`
        detail:
          type: string
          description: >-
            Human-readable description of why the error occurred and how to
            resolve it.


            Min length: `1`
        field:
          type: string
          description: >-
            The field in the request that caused the error, using array and
            object dot notation.


            Min length: `1`
      required:
        - category
        - code
      description: Represents an error encountered during a request to the API.
      title: Error
    refunds_Refund:
      type: object
      properties:
        id:
          type: string
          minLength: 1
          maxLength: 128
          description: |-
            Unique identifier for this refund issued by Cash App.

            Min length: `1`
            Max length: `128`
        amount:
          type: integer
          description: >-
            Amount of money to refund, in the lowest denomination of currency on
            the refund.


            Min value: `1`
        currency:
          $ref: '#/components/schemas/Currency'
        customer_id:
          type: string
          minLength: 1
          maxLength: 128
          description: |-
            ID of the customer that received this refund.

            Min length: `1`
            Max length: `128`
        merchant_id:
          type: string
          minLength: 1
          maxLength: 128
          description: |-
            ID of the merchant that issued this refund.

            Min length: `1`
            Max length: `128`
        status:
          $ref: '#/components/schemas/refunds_RefundStatus'
          description: >-
            The step of the refund processing lifecycle that this refund is
            currently at.


            - `AUTHORIZED`

            - `CAPTURED`

            - `VOIDED`

            - `DECLINED`
        created_at:
          type: string
          format: date-time
          description: >-
            When this refund was created, in [RFC
            3339](https://datatracker.ietf.org/doc/html/rfc3339) format (UTC).
        updated_at:
          type: string
          format: date-time
          description: >-
            When this refund was last updated, in [RFC
            3339](https://datatracker.ietf.org/doc/html/rfc3339) format (UTC).
        grant_id:
          type: string
          minLength: 1
          maxLength: 256
          description: |-
            This is currently unused and empty.

            Min length: `1`
            Max length: `256`
        payment_id:
          type: string
          minLength: 1
          maxLength: 128
          description: |-
            This is currently unused and empty.

            Min length: `1`
            Max length: `128`
        reference_id:
          type: string
          minLength: 1
          maxLength: 1024
          description: >-
            A user-defined identifier for this refund, typically used to
            associate the refund with a record in an external system.


            Min length: `1`

            Max length: `1024`
        metadata:
          $ref: '#/components/schemas/Metadata'
        decline_errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: >-
            If the refund was declined, contains a list of the reasons why it
            was declined.


            Min number of items: `1`
      required:
        - id
        - amount
        - currency
        - customer_id
        - merchant_id
        - status
        - created_at
        - updated_at
      title: Refund
    refunds_CreateRefundResponse:
      type: object
      properties:
        refund:
          $ref: '#/components/schemas/refunds_Refund'
      required:
        - refund
      title: CreateRefundResponse
    CreateRefundRequestBadRequestErrorBody:
      type: object
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: A list of errors that occurred while processing the request.
        refund:
          $ref: '#/components/schemas/refunds_Refund'
      required:
        - errors
      title: CreateRefundRequestBadRequestErrorBody

```

**`Example`**

```json Example
{
  "id": "PWCR_da1v3j4p3z15y47adpzzq0whj",
  "amount": 2500,
  "currency": "USD",
  "customer_id": "CST_AQmxh4y_QGoNNIG5NUw0jttqyYedL1LklACQdyJ3H-Vs6WmLtP6A_C7XjQNohvY",
  "merchant_id": "MMI_4vxs5egfk7hmta3qx2h6rp91x",
  "status": "AUTHORIZED",
  "created_at": "2022-01-01T12:00:00Z",
  "updated_at": "2022-01-05T12:00:00Z",
  "grant_id": "GRG_221243dc6985a6819ff6950c1a21332f7bc4a46ebd49b5a7002908ab768e8e5ff7831e084d0d2c9d8d939793b55eff50",
  "payment_id": "PWC_4nn21zy6t0v2yhqg5bvhk7xkq",
  "reference_id": "external-id",
  "metadata": {},
  "decline_errors": [
    {
      "category": "INVALID_REQUEST_ERROR",
      "code": "MISSING_REQUIRED_FIELD",
      "detail": "Missing required parameter.",
      "field": "field_a[2].field_b"
    }
  ]
}
```