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

# Create a refund

> Gives money back from a payment taken through Vori. A refund of the whole payment cancels it when the processor still allows that, and otherwise sends the money back to the card. A refund of part of a payment always sends the money back to the card. Refunds are capped at what remains of the payment, and retrying with the same `idempotency_key` returns the refund already made instead of refunding again. If the processor does not answer, the refund is held back from reads and this call returns a gateway timeout. The money may still have moved, so the refund goes on holding that part of the payment until its outcome is known. Retrying with the same `idempotency_key` reports it as still in progress while the processor may be working on it, and after that answers with its outcome once the processor can say what happened to it.

> [!WARNING]
>
> Payments and refunds are in beta. Contact Vori Support to enable them for your account. Until they are enabled, these endpoints answer `403 Forbidden`.


## OpenAPI

````yaml api/openapi.json POST /v1/refunds
openapi: 3.0.0
info:
  title: Vori API
  description: ''
  version: 1.0.0
  contact: {}
servers:
  - url: https://api.vori.com
    description: production
security: []
tags: []
paths:
  /v1/refunds:
    post:
      tags:
        - Refunds
      summary: Create a refund
      description: >-
        Gives money back from a payment taken through Vori. A refund of the
        whole payment cancels it when the processor still allows that, and
        otherwise sends the money back to the card. A refund of part of a
        payment always sends the money back to the card. Refunds are capped at
        what remains of the payment, and retrying with the same
        `idempotency_key` returns the refund already made instead of refunding
        again. If the processor does not answer, the refund is held back from
        reads and this call returns a gateway timeout. The money may still have
        moved, so the refund goes on holding that part of the payment until its
        outcome is known. Retrying with the same `idempotency_key` reports it as
        still in progress while the processor may be working on it, and after
        that answers with its outcome once the processor can say what happened
        to it.
      operationId: createRefund
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreatePaymentRefundRequest'
      responses:
        '201':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentRefund'
        '400':
          description: ''
          content:
            application/json:
              schema:
                anyOf:
                  - $ref: '#/components/schemas/DuplicateIdempotencyKeyError'
                  - $ref: '#/components/schemas/PaymentMerchantAccountChangedError'
                  - $ref: '#/components/schemas/PaymentMissingProcessorTokenError'
                  - $ref: '#/components/schemas/PaymentNotRefundableError'
                  - $ref: '#/components/schemas/PaymentProcessorNotConfiguredError'
                  - $ref: '#/components/schemas/RefundAmountExceedsPaymentError'
        '402':
          description: ''
          content:
            application/json:
              schema:
                anyOf:
                  - $ref: '#/components/schemas/RefundDeclinedError'
        '403':
          description: ''
          content:
            application/json:
              schema:
                anyOf:
                  - $ref: '#/components/schemas/InsufficientPermissionsError'
                  - $ref: '#/components/schemas/NoBannerAssociationError'
        '409':
          description: ''
          content:
            application/json:
              schema:
                anyOf:
                  - $ref: '#/components/schemas/RefundInProgressError'
        '504':
          description: ''
          content:
            application/json:
              schema:
                anyOf:
                  - $ref: '#/components/schemas/PaymentProcessorTimeoutError'
      security:
        - bearer: []
components:
  schemas:
    CreatePaymentRefundRequest:
      type: object
      properties:
        amount:
          type: string
          description: >-
            Amount to return to the card, in dollars. Refund the full `amount`
            of the payment or any part of it.
          format: positive-monetary
          pattern: ^[0-9]+(\.[0-9]+)?$
          example: '199.99'
        idempotency_key:
          type: string
          maxLength: 255
          description: >-
            Your own key for the refund, unique within the banner and mode.
            Sending the same key again returns the refund already made rather
            than refunding twice. Up to 255 characters.
        metadata:
          type: object
          maxProperties: 50
          additionalProperties:
            type: string
            maxLength: 500
          example:
            order_source: shopify
            fulfillment_id: '88213'
          nullable: true
          description: >-
            Your own key/value pairs, stored as sent and returned unchanged.
            Vori never interprets them. Up to 50 keys; key names up to 40
            characters of letters, numbers, underscores, and hyphens; values up
            to 500 characters. Keys beginning with "vori" are reserved. Do not
            put personal or sensitive information here — these values flow into
            reporting and data exports.
        payment_id:
          type: string
          description: >-
            ID of the payment to refund. The payment has to be `captured`, and
            what is refunded across all of its refunds can never exceed what was
            charged.
        store_id:
          type: string
          description: >-
            ID of the store the payment was taken for. It has to be the same
            store that was charged.
          pattern: ^[0-9]+$
      description: >-
        Gives money back from a payment taken through the Vori API, using the
        payment processor that took it.
      required:
        - amount
        - idempotency_key
        - payment_id
        - store_id
    PaymentRefund:
      type: object
      properties:
        id:
          type: string
          description: Unique identifier for the record.
        amount:
          type: string
          description: Amount returned to the card, in dollars.
          format: positive-monetary
          pattern: ^[0-9]+(\.[0-9]+)?$
          example: '199.99'
        created_at:
          type: string
          description: When the record was created.
          format: date-time
        idempotency_key:
          type: string
          description: >-
            Your own key for the refund, unique within the banner and mode.
            Sending the same key again returns the refund already made rather
            than refunding twice. Up to 255 characters.
        metadata:
          type: object
          maxProperties: 50
          additionalProperties:
            type: string
            maxLength: 500
          example:
            order_source: shopify
            fulfillment_id: '88213'
          nullable: true
          description: >-
            Your own key/value pairs, exactly as supplied when the refund was
            made.
        mode:
          description: >-
            Whether money moves for real or not: `test` refunds in the payment
            processor's test environment and never moves money, and `live` makes
            an actual refund. It is always the `mode` of the payment being
            refunded.
          allOf:
            - $ref: '#/components/schemas/PaymentMode'
        payment_id:
          type: string
          description: ID of the payment being refunded.
        processor:
          description: >-
            The payment processor that handled the refund, which is the one that
            took the payment.
          allOf:
            - $ref: '#/components/schemas/PaymentProcessor'
        status:
          description: >-
            Where the refund stands: `captured` once the money was given back,
            and `failed` when the processor refused it. A refund is never
            `authorized`. A refund the processor has not answered for yet is not
            served at all, and goes on holding that part of the payment until
            its outcome is known.
          allOf:
            - $ref: '#/components/schemas/PaymentStatus'
        store_id:
          type: string
          description: ID of the store the refund was made for.
          pattern: ^[0-9]+$
        type:
          description: >-
            How the money was given back: `void` cancels the charge before it
            settles, and `return` sends money back to the card. Vori picks
            whichever the payment still allows.
          allOf:
            - $ref: '#/components/schemas/PaymentRefundType'
        updated_at:
          type: string
          description: When the record was last changed.
          format: date-time
      description: >-
        A refund of a card payment taken through the Vori API. One refund is one
        attempt to give money back, and a refund is never edited once the
        processor has answered.
      required:
        - id
        - amount
        - created_at
        - idempotency_key
        - metadata
        - mode
        - payment_id
        - processor
        - status
        - store_id
        - type
        - updated_at
    DuplicateIdempotencyKeyError:
      type: object
      properties:
        error_code:
          type: string
          enum:
            - duplicate_idempotency_key
      required:
        - error_code
    PaymentMerchantAccountChangedError:
      type: object
      properties:
        error_code:
          type: string
          enum:
            - payment_merchant_account_changed
        error_details:
          $ref: '#/components/schemas/PaymentMerchantAccountChangedErrorDetails'
      required:
        - error_code
        - error_details
    PaymentMissingProcessorTokenError:
      type: object
      properties:
        error_code:
          type: string
          enum:
            - payment_missing_processor_token
        error_details:
          $ref: '#/components/schemas/PaymentMissingProcessorTokenErrorDetails'
      required:
        - error_code
        - error_details
    PaymentNotRefundableError:
      type: object
      properties:
        error_code:
          type: string
          enum:
            - payment_not_refundable
        error_details:
          $ref: '#/components/schemas/PaymentNotRefundableErrorDetails'
      required:
        - error_code
        - error_details
    PaymentProcessorNotConfiguredError:
      type: object
      properties:
        error_code:
          type: string
          enum:
            - payment_processor_not_configured
        error_details:
          $ref: '#/components/schemas/PaymentProcessorNotConfiguredErrorDetails'
      required:
        - error_code
        - error_details
    RefundAmountExceedsPaymentError:
      type: object
      properties:
        error_code:
          type: string
          enum:
            - refund_amount_exceeds_payment
      required:
        - error_code
    RefundDeclinedError:
      type: object
      properties:
        error_code:
          type: string
          enum:
            - refund_declined
        error_details:
          $ref: '#/components/schemas/RefundDeclinedErrorDetails'
      required:
        - error_code
        - error_details
    InsufficientPermissionsError:
      type: object
      properties:
        error_code:
          type: string
          enum:
            - insufficient_permissions
        error_details:
          $ref: '#/components/schemas/InsufficientPermissionsErrorDetails'
      required:
        - error_code
        - error_details
    NoBannerAssociationError:
      type: object
      properties:
        error_code:
          type: string
          enum:
            - no_banner_association
      required:
        - error_code
    RefundInProgressError:
      type: object
      properties:
        error_code:
          type: string
          enum:
            - refund_in_progress
        error_details:
          $ref: '#/components/schemas/RefundInProgressErrorDetails'
      required:
        - error_code
        - error_details
    PaymentProcessorTimeoutError:
      type: object
      properties:
        error_code:
          type: string
          enum:
            - payment_processor_timeout
        error_details:
          $ref: '#/components/schemas/PaymentProcessorTimeoutErrorDetails'
      required:
        - error_code
        - error_details
    PaymentMode:
      type: string
      enum:
        - live
        - test
      description: Live or test. A test payment moves no money.
    PaymentProcessor:
      type: string
      enum:
        - datacap
      description: >-
        The payment processor that handled the charge, which is the one
        configured for the store.
    PaymentStatus:
      type: string
      enum:
        - authorized
        - captured
        - failed
      description: >-
        Where the payment stands: `captured` once the amount was taken from the
        card, `authorized` while the processor only holds it, and `failed` when
        the card was refused. A payment the processor has not answered for yet
        is not served at all: sending the same request again with the same
        `idempotency_key` and the same `token` settles it.
    PaymentRefundType:
      type: string
      enum:
        - return
        - void
      description: >-
        How the money was given back: `void` cancels the charge before it
        settles, and `return` sends money back to the card. Vori picks whichever
        the payment still allows.
    PaymentMerchantAccountChangedErrorDetails:
      type: object
      properties:
        payment_id:
          type: string
          description: ID of the payment the error is about.
        store_id:
          type: string
          description: ID of the store whose payment processor account changed.
          pattern: ^[0-9]+$
      required:
        - payment_id
        - store_id
    PaymentMissingProcessorTokenErrorDetails:
      type: object
      properties:
        payment_id:
          type: string
          description: ID of the payment the error is about.
      required:
        - payment_id
    PaymentNotRefundableErrorDetails:
      type: object
      properties:
        payment_id:
          type: string
          description: ID of the payment the error is about.
        status:
          description: Status the payment is in, which is not one a refund allows.
          allOf:
            - $ref: '#/components/schemas/PaymentStatus'
      required:
        - payment_id
        - status
    PaymentProcessorNotConfiguredErrorDetails:
      type: object
      properties:
        mode:
          description: >-
            Mode the payment asked for. A store can be set up to take live
            payments but not test ones, or the other way around.
          allOf:
            - $ref: '#/components/schemas/PaymentMode'
        store_id:
          type: string
          description: ID of the store that has no payment processor.
          pattern: ^[0-9]+$
      required:
        - mode
        - store_id
    RefundDeclinedErrorDetails:
      type: object
      properties:
        processor_message:
          type: string
          nullable: true
          description: What the payment processor said about the refusal, in its own words.
        refund_id:
          type: string
          description: ID of the refund the error is about.
      required:
        - processor_message
        - refund_id
    InsufficientPermissionsErrorDetails:
      type: object
      properties:
        action:
          allOf:
            - $ref: '#/components/schemas/Action'
        resource:
          allOf:
            - $ref: '#/components/schemas/Resource'
      required:
        - action
        - resource
    RefundInProgressErrorDetails:
      type: object
      properties:
        refund_id:
          type: string
          description: ID of the refund the error is about.
      required:
        - refund_id
    PaymentProcessorTimeoutErrorDetails:
      type: object
      properties:
        payment_id:
          type: string
          description: ID of the payment the error is about.
        refund_id:
          type: string
          description: >-
            ID of the refund the error is about, when the processor was
            answering about a refund of the payment.
      required:
        - payment_id
    Action:
      type: string
      enum:
        - '*'
        - cancel
        - check_in
        - create
        - delete
        - read
        - read_credentials
        - record_events
        - refund
        - restart
        - update
        - void
    Resource:
      type: string
      enum:
        - '*'
        - accounting_integration
        - agent_chats
        - agent_job_settings
        - agent_tasks
        - agents
        - api_clients
        - asynchronous_tasks
        - banners
        - billing
        - blackhawk_transactions
        - business_entities
        - capabilities
        - coupons
        - custom_quick_actions
        - datacap_transactions
        - departments
        - discounts
        - ditto_auth_tokens
        - doordash_enrollments
        - edge_agents
        - electronic_shelf_labels
        - employees
        - feature_orientations
        - files
        - food_modifiers
        - gift_cards
        - gl_code_mappings
        - house_account_payment_links
        - house_account_payments
        - house_accounts
        - inventory
        - inventory_sessions
        - inventory_settings
        - invoices
        - item_modifiers
        - label_dimension_sets
        - label_sheet_profiles
        - label_stock_products
        - lanes
        - loyalty_bonuses
        - loyalty_campaigns
        - loyalty_rewards
        - notification_templates
        - offers
        - order_guides
        - orders
        - payments
        - people
        - pos_banner_configurations
        - pos_orders
        - pos_tills
        - price_settings
        - price_tags
        - product_attributes
        - product_ranges
        - products
        - promotions
        - purchase_orders
        - receiving
        - reporting
        - revision_sessions
        - revisions
        - roles
        - shopper_tags
        - shoppers
        - store_product_inventory_counts
        - store_product_lots
        - store_product_rules
        - store_product_tag_templates
        - store_snap_incentive_program_coupons
        - store_vendor_merge_requests
        - store_vendor_product_merge_requests
        - store_vendor_products
        - store_vendors
        - stores
        - tag_printings
        - tag_template_presets
        - tag_templates
        - tax_rates
        - users
        - variable_weights
        - vendor_data_requests
        - vendor_merge_requests
        - vendor_product_merge_requests
        - vendor_products
        - vendor_store_department_accounts
        - vendors
        - wallet_payments
        - wic_products
  securitySchemes:
    bearer:
      type: http
      scheme: bearer

````

## Related topics

- [Create transactions](https://help.vori.com/api/create-transactions.md)
- [Create a payment](https://help.vori.com/api/payments/create.md)
- [Create Quick Actions in Back Office](https://help.vori.com/point-of-sale-pos/pos-customization-and-setup/create-quick-actions-in-back-office.md)
