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

# Create a refund

> Gives money back on one of your payments, in full or in part, through the same path the dashboard uses, so the refund shows in RevOS like any other. Requires an `Idempotency-Key`: the same key with the same body returns the same refund. One refund at a time per payment: while one is `pending`, another is refused with 409.



## OpenAPI

````yaml /api-reference/openapi-v1.json post /refunds
openapi: 3.1.0
info:
  title: Payra API
  version: v1
  description: >-
    The Payra API. Authenticate with a secret key: `Authorization: Bearer
    sk_test_...`. The two payment method session endpoints Payra Elements calls
    also take a publishable key with the session's `client_secret`.
servers:
  - url: https://api-dashboard.payra.com/v1
    description: 'Sandbox and live: the key decides which'
security: []
paths:
  /refunds:
    post:
      tags:
        - Refunds
      summary: Create a refund
      description: >-
        Gives money back on one of your payments, in full or in part, through
        the same path the dashboard uses, so the refund shows in RevOS like any
        other. Requires an `Idempotency-Key`: the same key with the same body
        returns the same refund. One refund at a time per payment: while one is
        `pending`, another is refused with 409.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                payment:
                  type: string
                  minLength: 1
                  maxLength: 64
                  example: pay_test_7Hs2kQ9mL1pXv4cR8tWzAbCdEf
                  description: A payment of yours that `succeeded`.
                amount:
                  type: integer
                  exclusiveMinimum: 0
                  example: 2500
                  description: >-
                    In the smallest unit of the currency. Omit it to refund
                    everything that has not been refunded yet; above that
                    remaining balance the request is refused.
                reason:
                  type: string
                  minLength: 1
                  maxLength: 200
                  example: Customer returned the item
                  description: Shown on the refund in RevOS and on the receipt.
              required:
                - payment
      responses:
        '201':
          description: The refund
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Refund'
        '400':
          description: >-
            Invalid parameters, a missing or reused Idempotency-Key, a payment
            that cannot be refunded, or an amount above what is left
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Missing, invalid or revoked API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '402':
          description: The processor refused the refund; `refund` names the failed refund
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: The API is not enabled for the workspace, or the key lacks the scope
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: A refund of this payment is still pending
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Rate limit exceeded; see Retry-After
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
        - bearerAuth: []
components:
  schemas:
    Refund:
      type: object
      properties:
        object:
          type: string
          enum:
            - refund
        id:
          type: string
          example: re_test_3kQ2mL7Hs1pXv4cR8tWzAbCdEf
        payment:
          type: string
          example: pay_test_7Hs2kQ9mL1pXv4cR8tWzAbCdEf
          description: The payment the money goes back on.
        status:
          type: string
          enum:
            - pending
            - succeeded
            - failed
          example: succeeded
          description: >-
            `pending` while the processor has the refund but has not confirmed
            it (a later webhook says how it ended); `succeeded` once the money
            is on its way back; `failed` when the processor refused (the create
            then answers 402 and this object stays readable).
        amount:
          type: integer
          example: 2500
          description: In the smallest unit of the currency (cents).
        currency:
          type: string
          enum:
            - USD
            - CAD
          example: USD
        reason:
          type:
            - string
            - 'null'
          example: Customer returned the item
        failure:
          type:
            - object
            - 'null'
          properties:
            code:
              type: string
              enum:
                - card_declined
                - insufficient_funds
                - authentication_failed
                - invalid_payment_method
                - duplicate_transaction
                - ach_returned
                - chargeback
                - processing_error
              example: processing_error
            message:
              type: string
              example: The payment could not be processed. Retry later.
          required:
            - code
            - message
          description: >-
            Set when `status` is `failed`: why, in the same fixed vocabulary as
            a payment failure. `processing_error` is a fault on the way to the
            processor, safe to retry with a new Idempotency-Key.
        livemode:
          type: boolean
          example: false
        created_at:
          type: string
          format: date-time
          example: '2026-09-22T20:00:00.000Z'
        succeeded_at:
          type:
            - string
            - 'null'
          format: date-time
          example: '2026-09-22T20:00:01.312Z'
      required:
        - object
        - id
        - payment
        - status
        - amount
        - currency
        - reason
        - failure
        - livemode
        - created_at
        - succeeded_at
    Error:
      type: object
      properties:
        error:
          type: object
          properties:
            type:
              type: string
              enum:
                - invalid_request_error
                - authentication_error
                - permission_error
                - rate_limit_error
                - idempotency_error
                - card_error
                - api_error
            code:
              type: string
            message:
              type: string
            param:
              type: string
            request_id:
              type: string
          required:
            - type
            - code
            - message
            - request_id
          additionalProperties:
            type: string
      required:
        - error
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >-
        A secret key, `sk_test_...` or `sk_live_...`; a publishable key
        (`pk_...`) on the browser routes only

````