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

# Cancel refund

> Cancel a refund that is still in `processing`. Completed, failed, or already canceled refunds cannot be canceled.



## OpenAPI

````yaml /en/api/refund-openapi.json post /api/v1/refunds/{refund_id}/cancel
openapi: 3.1.0
info:
  title: StablePay Refund API
  version: '2026-04-14'
  summary: 'StablePay refund endpoints: create, retrieve, and cancel refunds.'
  description: >-
    OpenAPI specification for the StablePay refund endpoints.


    ## Authentication


    Every endpoint requires both a **Bearer API Key** and signature headers:


    - `Authorization: Bearer {api_key}`

    - `X-StablePay-Timestamp`: Unix timestamp in seconds

    - `X-StablePay-Nonce`: Random string (UUID recommended) used for replay
    protection

    - `X-StablePay-Signature`: HMAC-SHA256 signature


    ## Signing rules


    The signing string is `{timestamp}.{nonce}.{requestBody}`:


    - `POST` requests: `requestBody` is the raw JSON payload string

    - `GET` requests: `requestBody` is the empty string


    Compute HMAC-SHA256 of the signing string using the merchant API Secret, and
    use the lowercase hex digest as `X-StablePay-Signature`.


    ## Amount precision


    All amount fields are expressed in the smallest unit of the currency. USDT
    and USDC both use 6 decimal places (i.e., 1 USDT = 1,000,000).
servers:
  - url: https://api.stablepay.co
    description: Production
security:
  - bearerAuth: []
    stablepayTimestamp: []
    stablepayNonce: []
    stablepaySignature: []
tags:
  - name: Refunds
    description: Create, retrieve, and cancel refunds.
paths:
  /api/v1/refunds/{refund_id}/cancel:
    post:
      tags:
        - Refunds
      summary: Cancel refund
      description: >-
        Cancel a refund that is still in `processing`. Completed, failed, or
        already canceled refunds cannot be canceled.
      operationId: cancelRefund
      parameters:
        - $ref: '#/components/parameters/RefundId'
        - $ref: '#/components/parameters/XStablePayTimestamp'
        - $ref: '#/components/parameters/XStablePayNonce'
        - $ref: '#/components/parameters/XStablePaySignature'
      responses:
        '200':
          description: Refund canceled.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RefundCancellation'
        '400':
          description: Invalid request or current status does not allow cancellation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Authentication failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Access denied
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Refund does not exist
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  parameters:
    RefundId:
      name: refund_id
      in: path
      required: true
      description: Unique refund ID supplied by the merchant when the refund was created.
      schema:
        type: string
      example: refund_20250101001
    XStablePayTimestamp:
      name: X-StablePay-Timestamp
      in: header
      required: true
      description: Unix timestamp in seconds. Must be within 5 minutes of server time.
      schema:
        type: string
      example: '1735689600'
    XStablePayNonce:
      name: X-StablePay-Nonce
      in: header
      required: true
      description: Replay-protection nonce, 16-64 characters. Use a fresh UUID per request.
      schema:
        type: string
        minLength: 16
        maxLength: 64
      example: 550e8400-e29b-41d4-a716-446655440000
    XStablePaySignature:
      name: X-StablePay-Signature
      in: header
      required: true
      description: >-
        Lowercase hex HMAC-SHA256 of `{timestamp}.{nonce}.{requestBody}` signed
        with the merchant API Secret. For GET requests, `requestBody` is an
        empty string.
      schema:
        type: string
      example: a1b2c3d4e5f6...
  schemas:
    RefundCancellation:
      type: object
      required:
        - refund_id
        - status
        - canceled_at
      properties:
        refund_id:
          type: string
          description: Merchant-supplied refund ID.
        status:
          type: string
          enum:
            - canceled
        canceled_at:
          type: integer
          format: int64
          description: Cancellation time, Unix seconds.
    ErrorResponse:
      type: object
      description: Error response.
      properties:
        error:
          type: object
          properties:
            type:
              type: string
              description: Error type.
            code:
              type: string
              description: Error code.
            message:
              type: string
              description: Error message.
            param:
              type: string
              description: Related parameter.
            doc_url:
              type: string
              description: Error documentation URL.
            decline_code:
              type: string
              description: Decline code.
            request_log_url:
              type: string
              description: Request log URL.
            charge:
              type: string
              description: Related payment ID.
        request_id:
          type: string
          description: Request ID.
        timestamp:
          type: integer
          format: int64
          description: Error timestamp in Unix seconds.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API Key
      description: Bearer API Key, for example `Bearer sk_live_xxx`.
    stablepayTimestamp:
      type: apiKey
      in: header
      name: X-StablePay-Timestamp
      description: Unix timestamp in seconds. Must be within 5 minutes of server time.
    stablepayNonce:
      type: apiKey
      in: header
      name: X-StablePay-Nonce
      description: Replay-protection nonce, 16-64 characters. Use a fresh UUID per request.
    stablepaySignature:
      type: apiKey
      in: header
      name: X-StablePay-Signature
      description: >-
        Lowercase hex HMAC-SHA256 of `{timestamp}.{nonce}.{requestBody}` signed
        with the merchant API Secret. For GET requests, `requestBody` is an
        empty string.

````