JustiFi

JustiFi Disputes API

A customer may dispute their payment with the card issuer/bank if they believe the charge is erroneous. When this happens, a dispute record is created and associated with their original payment.

GitHub OpenAPI

Operations 6

GET /disputes List Disputes #
GET /disputes/{id} Get a Dispute #
PATCH /disputes/{id} Update a Dispute #
PUT /disputes/{id}/evidence Create dispute evidence #
PATCH /disputes/{id}/response Update dispute response #
POST /disputes/{id}/response Submit dispute response #

Documentation

📖
Authentication
https://raw.githubusercontent.com/api-evangelist/justifi/refs/heads/main/authentication/justifi-authentication.yml

Specifications

⚙
OpenAPI
https://raw.githubusercontent.com/api-evangelist/justifi/refs/heads/main/openapi/justifi-disputes-api-openapi.yml

Other Resources

🔗
Webhooks
https://raw.githubusercontent.com/api-evangelist/justifi/refs/heads/main/asyncapi/justifi-webhooks.yml
🔗
ErrorCatalog
https://raw.githubusercontent.com/api-evangelist/justifi/refs/heads/main/errors/justifi-problem-types.yml
🔗
DeclineCodes
https://raw.githubusercontent.com/api-evangelist/justifi/refs/heads/main/errors/justifi-decline-codes.yml
🔗
DataModel
https://raw.githubusercontent.com/api-evangelist/justifi/refs/heads/main/data-model/justifi-data-model.yml

Work with this as data

Every API here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for apis

7 MCP tools reach this
  • find_apisBrowse and filter every API in the catalog.
  • get_api_artifactsOne API's artifacts, grouped by type.
  • get_openapiThe primary OpenAPI for this API.
  • find_similar_apisAPIs that look like this one.
  • apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.
  • resolveTurn a domain, URL or GitHub org into the provider it belongs to.
  • find_cohortsEvery scored population of providers in the catalog.
All 92 tools →

Call it yourself

curl for this page
This API 
curl "https://apis.io/api/v1/apis/justifi-disputes-api"
All apis 
curl "https://apis.io/api/v1/apis?limit=25"

Discovery needs no key. Ratings and market analysis are Pro.

Get an API key

Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.

GitHub Google LinkedIn

A second provider on the same verified email joins the account you already have.

OpenAPI Specification

justifi-disputes-api-openapi.yml Raw ↑ 
openapi: 3.2.0
info:
  description: '## Introduction


    The JustiFi API is a REST-based payment processing API.'
  title: JustiFi API Documentation Disputes 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: Disputes
  description: 'A customer may dispute their payment with the card issuer/bank if they believe

    the charge is erroneous. When this happens, a dispute record is created and

    associated with their original payment.'
paths:
  /disputes:
    get:
      summary: List Disputes
      description: Any disputes associated with a payment are also included in the response of the get payment API and the list payments API response
      operationId: ListDisputes
      tags:
      - Disputes
      parameters:
      - $ref: '#/components/parameters/authorization-header'
      - $ref: '#/components/parameters/sub-account'
      responses:
        '200':
          description: Successfully list disputes
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/Envelope-list'
                - properties:
                    type:
                      example: array
                    data:
                      items:
                        $ref: '#/components/schemas/Dispute'
  /disputes/{id}:
    get:
      summary: Get a Dispute
      description: Get information about a dispute.
      operationId: GetDispute
      tags:
      - Disputes
      parameters:
      - $ref: '#/components/parameters/id-path'
      - $ref: '#/components/parameters/authorization-header'
      responses:
        '200':
          description: Successfully get a dispute
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/Envelope'
                - properties:
                    type:
                      example: dispute
                    data:
                      $ref: '#/components/schemas/Dispute'
    patch:
      summary: Update a Dispute
      description: Change a dispute's metadata.
      operationId: UpdateDispute
      parameters:
      - $ref: '#/components/parameters/id-path'
      - $ref: '#/components/parameters/idempotency-key-header'
      - $ref: '#/components/parameters/authorization-header'
      tags:
      - Disputes
      requestBody:
        required: true
        content:
          application/json:
            schema:
              properties:
                metadata:
                  type: object
                  format: json
                  description: any useful information you'd like to store alongside this dispute; when you update metadata, any previous metadata will be overwritten
      responses:
        '200':
          description: Dispute update was successful
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/Envelope'
                - properties:
                    type:
                      example: dispute
                    data:
                      $ref: '#/components/schemas/Dispute'
  /disputes/{id}/evidence:
    put:
      summary: Create dispute evidence
      description: 'Creates dispute evidence and generate presigned url


        > ⚠️ **Not available for Canada accounts**

        >

        > The dispute response and evidence endpoints are not available for Canada accounts.'
      operationId: CreateDisputeEvidence
      parameters:
      - $ref: '#/components/parameters/id-path'
      - $ref: '#/components/parameters/authorization-header'
      tags:
      - Disputes
      requestBody:
        required: true
        content:
          application/json:
            schema:
              required:
              - file_name
              - file_type
              - dispute_evidence_type
              properties:
                file_name:
                  type: string
                  example: receipt.pdf
                  description: dispute evidence file name
                file_type:
                  type: string
                  description: dispute evidence file type
                  example: application/pdf
                  enum:
                  - image/jpeg
                  - image/png
                  - application/pdf
                  - application/zip
                  - application/x-zip-compressed
                dispute_evidence_type:
                  type: string
                  description: dispute evidence type matching the file that will be uploaded
                  example: receipt
                  enum:
                  - cancellation_policy
                  - customer_communication
                  - customer_signature
                  - duplicate_charge_documentation
                  - receipt
                  - refund_policy
                  - service_documentation
                  - shipping_documentation
                  - uncategorized_file
                description:
                  type: string
                  description: description of the dispute evidence file that will be uploaded
                metadata:
                  type: object
                  format: json
                  description: any useful information you'd like to store alongside the dispute evidence
      responses:
        '201':
          description: Dispute evidence created and presigned url generated
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/Envelope'
                - properties:
                    type:
                      example: dispute evidence
                    data:
                      $ref: '#/components/schemas/DisputeEvidence'
  /disputes/{id}/response:
    patch:
      summary: Update dispute response
      description: 'Updates the dispute response


        > ⚠️ **Not available for Canada accounts**

        >

        > The dispute response and evidence endpoints are not available for Canada accounts.'
      operationId: UpdateDisputeResponse
      parameters:
      - $ref: '#/components/parameters/id-path'
      - $ref: '#/components/parameters/authorization-header'
      tags:
      - Disputes
      requestBody:
        required: true
        content:
          application/json:
            schema:
              properties:
                additional_statement:
                  type: string
                  description: any additional evidence or statements
                cancellation_policy_disclosure:
                  type: string
                  description: an explanation of how and when the customer was shown your cancellation policy prior to purchase
                cancellation_rebuttal:
                  type: string
                  description: a justification for why the customer’s subscription was not canceled
                customer_billing_address:
                  type: string
                  description: the billing address provided by the customer
                customer_email_address:
                  type: string
                  description: the email address of the customer
                customer_name:
                  type: string
                  description: the name of the customer
                customer_purchase_ip_address:
                  type: string
                  description: the IP address that the customer used when making the purchase
                duplicate_charge_explanation:
                  type: string
                  description: an explanation of the difference between the disputed charge versus the prior charge that appears to be a duplicate
                product_description:
                  type: string
                  description: a description of the product or service that was sold
                refund_policy_disclosure:
                  type: string
                  description: documentation demonstrating that the customer was shown your refund policy prior to purchase
                refund_refusal_explanation:
                  type: string
                  description: justification for why the customer is not entitled to a refund
                service_date:
                  type: string
                  description: the date on which the customer received or began receiving the purchased service
                  example: '2024-10-31'
                shipping_address:
                  type: string
                  description: the address to which a physical product was shipped
                shipping_carrier:
                  type: string
                  description: the delivery service that shipped a physical product, such as Fedex, UPS, USPS, etc. If multiple carriers were used for this purchase, please separate them with commas
                shipping_date:
                  type: string
                  description: the date on which a physical product began its route to the shipping address
                  example: '2024-10-31'
                shipping_tracking_number:
                  type: string
                  description: the tracking number for a physical product. If multiple tracking numbers were generated for this purchase, please separate them with commas
                duplicate_charge_original_payment_id:
                  type: string
                  description: the payment id for the prior charge which appears to be a duplicate of the disputed charge
      responses:
        '200':
          description: Dispute response updated
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/Envelope'
                - properties:
                    type:
                      example: dispute response
                    data:
                      $ref: '#/components/schemas/DisputeResponse'
    post:
      summary: Submit dispute response
      description: 'Submits the dispute response


        > ⚠️ **Not available for Canada accounts**

        >

        > The dispute response and evidence endpoints are not available for Canada accounts.'
      operationId: SubmitDisputeResponse
      parameters:
      - $ref: '#/components/parameters/id-path'
      - $ref: '#/components/parameters/authorization-header'
      tags:
      - Disputes
      requestBody:
        required: true
        content:
          application/json:
            schema:
              required:
              - forfeit
              properties:
                forfeit:
                  type: boolean
                  description: when true forfeits the dispute and all other parameters passed in are ignored
                additional_statement:
                  type: string
                  description: any additional evidence or statements
                cancellation_policy_disclosure:
                  type: string
                  description: an explanation of how and when the customer was shown your cancellation policy prior to purchase
                cancellation_rebuttal:
                  type: string
                  description: a justification for why the customer’s subscription was not canceled
                customer_billing_address:
                  type: string
                  description: the billing address provided by the customer
                customer_email_address:
                  type: string
                  description: the email address of the customer
                customer_name:
                  type: string
                  description: the name of the customer
                customer_purchase_ip_address:
                  type: string
                  description: the IP address that the customer used when making the purchase
                duplicate_charge_explanation:
                  type: string
                  description: an explanation of the difference between the disputed charge versus the prior charge that appears to be a duplicate
                product_description:
                  type: string
                  description: a description of the product or service that was sold
                refund_policy_disclosure:
                  type: string
                  description: documentation demonstrating that the customer was shown your refund policy prior to purchase
                refund_refusal_explanation:
                  type: string
                  description: justification for why the customer is not entitled to a refund
                service_date:
                  type: string
                  description: the date on which the customer received or began receiving the purchased service
                  example: '2024-10-31'
                shipping_address:
                  type: string
                  description: the address to which a physical product was shipped
                shipping_carrier:
                  type: string
                  description: the delivery service that shipped a physical product, such as Fedex, UPS, USPS, etc. If multiple carriers were used for this purchase, please separate them with commas
                shipping_date:
                  type: string
                  description: the date on which a physical product began its route to the shipping address
                  example: '2024-10-31'
                shipping_tracking_number:
                  type: string
                  description: the tracking number for a physical product. If multiple tracking numbers were generated for this purchase, please separate them with commas
                duplicate_charge_original_payment_id:
                  type: string
                  description: the payment id for the prior charge which appears to be a duplicate of the disputed charge
      responses:
        '200':
          description: Dispute response submitted
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/Envelope'
                - properties:
                    type:
                      example: dispute
                    data:
                      $ref: '#/components/schemas/Dispute'
components:
  schemas:
    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
    DisputeEvidence:
      type: object
      properties:
        id:
          description: unique dispute evidence id
          type: string
          example: dpe_xyz
        file_name:
          type: string
          example: receipt.pdf
          description: dispute evidence file name
        file_type:
          type: string
          description: dispute evidence file type
          example: application/pdf
          enum:
          - image/jpeg
          - image/png
          - application/pdf
          - application/zip
          - application/x-zip-compressed
        dispute_evidence_type:
          type: string
          description: dispute evidence type matching the file that will be uploaded
          example: receipt
          enum:
          - cancellation_policy
          - customer_communication
          - customer_signature
          - duplicate_charge_documentation
          - receipt
          - refund_policy
          - service_documentation
          - shipping_documentation
          - uncategorized_file
        status:
          type: string
          description: dispute evidence status
          enum:
          - pending
          - uploaded
        description:
          type: string
          description: description of the dispute evidence file that will be uploaded
        presigned_url:
          type: string
          description: url that should be used to submit a put request to upload the evidence file
    DisputeResponse:
      type: object
      properties:
        additional_statement:
          type: string
          description: any additional evidence or statements
        cancellation_policy_disclosure:
          type: string
          description: an explanation of how and when the customer was shown your cancellation policy prior to purchase
        cancellation_rebuttal:
          type: string
          description: a justification for why the customer’s subscription was not canceled
        customer_billing_address:
          type: string
          description: the billing address provided by the customer
        customer_email_address:
          type: string
          description: the email address of the customer
        customer_name:
          type: string
          description: the name of the customer
        customer_purchase_ip_address:
          type: string
          description: the IP address that the customer used when making the purchase
        duplicate_charge_explanation:
          type: string
          description: an explanation of the difference between the disputed charge versus the prior charge that appears to be a duplicate
        product_description:
          type: string
          description: a description of the product or service that was sold
        refund_policy_disclosure:
          type: string
          description: documentation demonstrating that the customer was shown your refund policy prior to purchase
        refund_refusal_explanation:
          type: string
          description: justification for why the customer is not entitled to a refund
        service_date:
          type: string
          description: the date on which the customer received or began receiving the purchased service
          example: '2024-10-31'
        shipping_address:
          type: string
          description: the address to which a physical product was shipped
        shipping_carrier:
          type: string
          description: the delivery service that shipped a physical product, such as Fedex, UPS, USPS, etc. If multiple carriers were used for this purchase, please separate them with commas
        shipping_date:
          type: string
          description: the date on which a physical product began its route to the shipping address
          example: '2024-10-31'
        shipping_tracking_number:
          type: string
          description: the tracking number for a physical product. If multiple tracking numbers were generated for this purchase, please separate them with commas
        duplicate_charge_original_payment_id:
          type: string
          description: the payment id for the prior charge which appears to be a duplicate of the disputed charge
    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'
    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
    Dispute:
      type: object
      properties:
        id:
          description: unique dispute id
          type: string
          example: dp_xyz
        payment_id:
          description: the disputed payment
          type: string
          format: uuid
          example: py_xyz
        account_id:
          description: id of the account associated with the dispute
          type: string
          format: uuid
          example: acc_xyz
        amount:
          description: amount disputed in cents
          type: number
          example: 100
        currency:
          type: string
          enum:
          - usd
          - cad
          example: usd
        reason:
          type: string
          description: the reason this payment was disputed
          example: fraudulent
        due_date:
          type: string
          format: date
          description: due date for evidence submission to counter the dispute
          example: '2025-02-23'
        status:
          description: status of the dispute
          type: string
          example: won
          enum:
          - needs_response
          - under_review
          - won
          - lost
        metadata:
          type: object
          format: json
          description: any useful information you'd like to store alongside this dispute
          example: {}
        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'
        dispute_response:
          allOf:
          - type: object
          - description: present when evidence was submitted to counter dispute
          - $ref: '#/components/schemas/DisputeResponse'
          - {}
        dispute_reversal:
          type:
          - object
          - 'null'
          description: present when dispute gets reversed from lost to won
          properties:
            description:
              type: string
              example: Dispute was reversed
            created_at:
              type: string
              format: date-time
              example: '2021-01-01T12:00:00Z'
  parameters:
    id-path:
      in: path
      name: id
      schema:
        type: string
        format: uuid
      required: true
    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

        '
    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)
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