JustiFi Refunds API

openapi: 3.2.0
info:
  description: '## Introduction


    The JustiFi API is a REST-based payment processing API.'
  title: JustiFi API Documentation Refunds API
  termsOfService: https://justifi.ai/terms-and-conditions
  x-logo:
    url: https://justifi-brand-assets.s3.us-east-2.amazonaws.com/justifi-light-bg.png
  contact:
    email: api-development@justifi.ai
servers:
- url: https://api.justifi.ai/v1
  description: JustiFi API
tags:
- name: Refunds
  description: 'When you refund a payment, a refund object is created. You can retrieve

    information about the refunds you''ve issued.'
paths:
  /payments/{id}/refunds:
    post:
      tags:
      - Refunds
      summary: Refund a Payment
      description: 'Issue a refund for a payment. You may refund the full payment amount or just a portion. When refunding a portion, multiple refunds are supported up until the full payment amount has been refunded.


        *Note: If the sub account status is not `enabled`, `400` will be returned.*'
      operationId: CreateRefund
      parameters:
      - in: path
        name: id
        schema:
          type: string
          format: uuid
        required: true
      - $ref: '#/components/parameters/idempotency-key-header'
      - $ref: '#/components/parameters/authorization-header'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              properties:
                amount:
                  type: number
                  example: 10000
                  description: amount to refund; must be less than or equal to the `amount_refundable` on the payment
                description:
                  description: an optional note about this refund
                  type: string
                reason:
                  description: the reason this refund is being issued
                  type: string
                  example: duplicate
                  enum:
                  - duplicate
                  - fraudulent
                  - customer_request
                fees:
                  type: array
                  description: 'Array of fee objects to return to the merchant as part of this refund. If omitted, no fees are returned (current behavior preserved).


                    Each fee object specifies:

                    - `type`: The fee type to refund (`processing_fee` or `platform_fee`)

                    - `amount`: Amount to return in cents


                    **Validation:**

                    - The requested amount cannot exceed the `remaining_amount` for that fee type on the original payment

                    - The fee type must exist on the original payment


                    > **CAD Payments:** This parameter is not available for CAD payments. See [Canadian Payments](https://docs.justifi.tech/payments/canadianPayments) for details.


                    See [Enhanced Fee Management](#section/Enhanced-Fee-Management) for full documentation.

                    '
                  items:
                    type: object
                    properties:
                      type:
                        type: string
                        enum:
                        - processing_fee
                        - platform_fee
                        description: The type of fee to refund
                        example: processing_fee
                      amount:
                        type: integer
                        description: Amount to refund in cents
                        example: 175
                    required:
                    - type
                    - amount
                  example:
                  - type: processing_fee
                    amount: 175
                metadata:
                  type: object
                  format: json
                  description: any useful information you'd like to store alongside this refund
                  example: {}
            examples:
              Full_refund:
                value:
                  amount: 10000
                  reason: customer_request
                  description: Customer requested full refund
              Partial_refund_with_processing_fee_return:
                value:
                  amount: 5000
                  reason: customer_request
                  description: Partial refund with processing fee returned
                  fees:
                  - type: processing_fee
                    amount: 175
              Partial_refund_with_all_fees_returned:
                value:
                  amount: 5000
                  reason: customer_request
                  description: Partial refund with both fees returned
                  fees:
                  - type: processing_fee
                    amount: 175
                  - type: platform_fee
                    amount: 250
      responses:
        '201':
          description: Refund was created successfully
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/Envelope'
                - properties:
                    type:
                      example: refund
                    data:
                      $ref: '#/components/schemas/Refund'
  /refunds:
    get:
      summary: List Refunds
      description: List the refunds for your account. This endpoint supports pagination.
      operationId: ListRefunds
      tags:
      - Refunds
      parameters:
      - $ref: '#/components/parameters/authorization-header'
      - $ref: '#/components/parameters/sub-account'
      responses:
        '200':
          description: Successfully list refunds
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/Envelope-list'
                - properties:
                    type:
                      example: array
                    data:
                      items:
                        $ref: '#/components/schemas/Refund'
  /refunds/{id}:
    get:
      summary: Get a Refund
      description: Get information about a refund.
      operationId: GetRefund
      tags:
      - Refunds
      parameters:
      - $ref: '#/components/parameters/id-path'
      - $ref: '#/components/parameters/authorization-header'
      responses:
        '200':
          description: Successfully get a refund
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/Envelope'
                - properties:
                    type:
                      example: refund
                    data:
                      $ref: '#/components/schemas/Refund'
    patch:
      summary: Update a Refund
      description: Update the refund metadata.
      operationId: UpdateRefund
      parameters:
      - $ref: '#/components/parameters/id-path'
      - $ref: '#/components/parameters/idempotency-key-header'
      - $ref: '#/components/parameters/authorization-header'
      tags:
      - Refunds
      requestBody:
        required: true
        content:
          application/json:
            schema:
              properties:
                metadata:
                  type: object
                  format: json
                  description: any useful information you'd like to store alongside this refund; when you update metadata, any previous metadata will be overwritten
      responses:
        '200':
          description: Refund update was successful
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/Envelope'
                - properties:
                    type:
                      example: refund
                    data:
                      $ref: '#/components/schemas/Refund'
components:
  parameters:
    id-path:
      in: path
      name: id
      schema:
        type: string
        format: uuid
      required: true
    idempotency-key-header:
      in: header
      name: Idempotency-Key
      schema:
        type: string
        format: uuid
      required: true
      example: my-request-123abc
      description: a string to identify your request (we recommend using a generated uuid, but you may use any unique string) see [Idempotent Requests](https://docs.justifi.tech/api-spec#section/Idempotent-Requests)
    authorization-header:
      in: header
      name: Authorization
      schema:
        type: string
      required: true
      example: Bearer {access_token}
      description: the `access_token` value returned from the JustiFi `oauth/token` endpoint (be sure to append `Bearer` before the token)
    sub-account:
      in: header
      name: Sub-Account
      schema:
        type: string
      required: false
      example: acc_123xyz
      description: 'the id of the [sub account](https://docs.justifi.tech/api-spec#tag/Sub-Accounts) that this request applies to

        '
  schemas:
    PageInfo:
      type: object
      properties:
        end_cursor:
          description: the encoded id of the last record in the current list
          type: string
          example: WyIyMDIyLTAyLTA4IDE5OjUyOjM3LjEwNDE3MzAwMCIsIjY4MDliYTU5LTYxYjctNDg3MS05YWFiLWE2Y2MyNmY3M2M1ZCJd
        has_next:
          description: true if the collection contains records following the current list
          type: boolean
          default: false
        has_previous:
          description: true if the collection contains records ahead of the current list
          type: boolean
          default: false
        start_cursor:
          description: the encoded id of the first record in the current list
          type: string
          example: WyIyMDIyLTAyLTA4IDIwOjAxOjU4LjEyMDIzMjAwMCIsIjU5ZTFjNGI1LWFlOWQtNDIyZC04MTVkLWNjNzQ5NzdlYmFjYSJd
    ReturnedFeeResponse:
      type: object
      description: A returned fee object showing fee details returned to the merchant with a refund
      properties:
        id:
          type: string
          description: Unique identifier for this returned fee
          example: rtfee_xyz
        payment_fee_id:
          type: string
          description: Unique identifier for the original payment fee that was partially or fully returned
          example: pyfee_abc
        type:
          type: string
          enum:
          - processing_fee
          - platform_fee
          description: 'The type of fee that was returned:

            - `processing_fee`: Processing fee returned to merchant

            - `platform_fee`: Platform fee returned to merchant

            '
          example: processing_fee
        returned_amount:
          type: integer
          description: Amount returned to the merchant in cents
          example: 175
        original_amount:
          type: integer
          description: Original fee amount in cents from the payment
          example: 350
        currency:
          type: string
          description: Currency of the fee amounts
          example: usd
        remaining_amount:
          type: integer
          description: Amount still available for refund on the original payment fee in cents
          example: 175
      required:
      - id
      - payment_fee_id
      - type
      - returned_amount
      - original_amount
      - currency
      - remaining_amount
    Envelope:
      type: object
      properties:
        id:
          description: the object id, also found in the data object
          type: string
          format: uuid
          example: prefix_xyz (same as id of data object)
        type:
          description: the object type, or array of objects
          type: string
          example: account
        data:
          description: the attributes for the object
          type: object
        page_info:
          description: information for cursor style pagination, is null for single records
          type: null
    Envelope-list:
      type: object
      properties:
        id:
          description: the object id
          type: number
          example: 1
        type:
          description: the object type, or array of objects
          type: string
          example: account
        data:
          description: the list of objects
          type: array
        page_info:
          description: information for cursor style pagination
          $ref: '#/components/schemas/PageInfo'
    Refund:
      type: object
      properties:
        id:
          description: refund unique id
          type: string
          example: re_xyz
        payment_id:
          description: the payment for which this refund is being issued
          type: string
          format: uuid
          example: py_xyz
        amount:
          description: the amount of this refund in cents
          type: number
          example: 100
        description:
          type: string
          description: an optional note about this refund
          example: customer canceled their order
        reason:
          description: the reason this refund is being issued
          type: string
          example: duplicate
          enum:
          - duplicate
          - fraudulent
          - customer_request
        status:
          description: the status of this refund
          type: string
          example: succeeded
          enum:
          - pending
          - succeeded
          - failed
        metadata:
          type: object
          format: json
          description: any useful information you'd like to store alongside this refund
          example: {}
        returned_fees:
          type: array
          description: 'Array of returned fee objects showing the fees returned to the merchant with this refund.

            Present when fees were specified in the refund request.

            See [Enhanced Fee Management](https://docs.justifi.tech/api-spec#section/Enhanced-Fee-Management) for full documentation.

            '
          items:
            $ref: '#/components/schemas/ReturnedFeeResponse'
          example:
          - id: rtfee_xyz
            payment_fee_id: pyfee_abc
            type: processing_fee
            returned_amount: 175
            original_amount: 350
            currency: usd
            remaining_amount: 175
        created_at:
          type: string
          format: date-time
          example: '2021-01-01T12:00:00Z'
        updated_at:
          type: string
          format: date-time
          example: '2021-01-01T12:00:00Z'
x-tagGroups:
- name: Authorization
  tags:
  - API Credentials
  - Web Component Tokens
- name: For Platforms
  tags:
  - Sub Accounts
  - Platform Wallet Accounts
  - Onboarding via Component
  - Hosted Onboarding
  - Onboarding via API
  - Fee Configurations
  - Proceeds
  - Reports
- name: Payment Resources
  tags:
  - Payments
  - Payment Methods
  - Tokenize via Component
  - Payment Method Groups
  - Refunds
  - Disputes
  - Payouts
  - Payout Holds
  - Balance Transactions
  - Ach Return Fees
  - Payment Method Migration
- name: Checkout Resources
  tags:
  - Checkouts
  - Checkout via Component
  - Checkout via API
- name: Insurance Resources
  tags:
  - Bind Insurance
- name: Entity Resources
  tags:
  - Business
  - Identity
  - Address
  - Document
  - Bank Account
  - Terms and Conditions
  - Provisioning
- name: Card Present Resources
  tags:
  - Terminals
  - Terminals Orders
- name: Libraries
  tags:
  - JustiFi Web Components
  - JustiFi SDK
- name: Event Publishing
  tags:
  - Events
  - Webhook Delivery