JustiFi Voids API

openapi: 3.2.0
info:
  description: '## Introduction


    The JustiFi API is a REST-based payment processing API.'
  title: JustiFi API Documentation Voids 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: Voids
paths:
  /payments/{id}/void:
    post:
      tags:
      - Voids
      summary: Void a Payment
      description: 'Void a payment transaction to cancel a payment before it reaches settlement.

        Payment transactions are voidable within 25 minutes of the original transaction.

        This includes `authorized` payments (that were created with `capture_strategy` manual and have not been captured yet).'
      operationId: VoidPayment
      parameters:
      - $ref: '#/components/parameters/id-path'
      - $ref: '#/components/parameters/idempotency-key-header'
      - $ref: '#/components/parameters/authorization-header'
      responses:
        '200':
          description: Payment was voided successfully
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/Envelope'
                - properties:
                    data:
                      oneOf:
                      - $ref: '#/components/schemas/CardPayment'
                      - $ref: '#/components/schemas/BankAccountPayment'
              example: null
              examples:
                Card_payment_voided:
                  value:
                    id: py_123xyz
                    type: payment
                    data:
                      id: py_123xyz
                      account_id: acc_123xyz
                      amount_disputed: 0
                      amount_refunded: 0
                      amount_returned: 0
                      amount: 10000
                      amount_refundable: 10000
                      application_fee_rate_id: afr_123xyz
                      balance: 99850
                      capture_strategy: automatic
                      captured: true
                      created_at: '2021-01-01T12:00:00Z'
                      currency: usd
                      description: order xyz
                      disputed: false
                      error_code: null
                      error_description: null
                      fee_amount: 150
                      financial_transaction_id: ft_123xyz
                      is_test: true
                      metadata: {}
                      payment_intent_id: pi_xyz
                      refunded: false
                      returned: false
                      status: canceled
                      payment_mode: ecom
                      updated_at: '2021-01-01T12:00:00Z'
                      payment_method:
                        card:
                          id: pm_123xyz
                          acct_last_four: 4242
                          brand: visa
                          name: Sylvia Fowles
                          token: pm_123xyz
                          metadata: {}
                          created_at: '2021-01-01T12:00:00Z'
                          updated_at: '2021-01-01T12:00:00Z'
                        customer_id: null
                        signature: 123abc
                      application_fee:
                        id: fee_123xyz
                        amount: 150
                        currency: usd
                        created_at: '2021-01-01T12:00:00Z'
                        updated_at: '2021-01-01T12:00:00Z'
                      refunds: []
                      disputes: []
                    page_info: null
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
    ApplicationFee:
      type: object
      properties:
        id:
          description: unique application fee id
          type: string
          format: uuid
          example: fee_123xyz
        amount:
          description: application fee amount, in cents
          type: number
          example: 150
        currency:
          type: string
          enum:
          - usd
          - cad
          example: usd
        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'
    TransactionHold:
      type: object
      properties:
        id:
          description: unique transaction hold id
          type: string
          example: th_123xyz
        financial_transaction_id:
          type: string
          description: financial transaction id the transaction hold is associated to
          format: uuid
          example: ft_123xyz
    CardPayment:
      type: object
      properties:
        id:
          description: unique payment id
          type: string
          example: py_xyz
        account_id:
          type: string
          format: uuid
          example: acc_xyz
        amount:
          description: payment amount in cents
          type: number
          example: 10000
        amount_disputed:
          description: sum of open or lost disputes for this payment, in cents
          type: number
          example: 0
        amount_refunded:
          description: sum of refunds for this payment, in cents
          type: number
          example: 0
        amount_refundable:
          description: amount of this payment currently able to be refunded, in cents
          type: number
          example: 10000
        balance:
          description: sum of debits and credits for this payment, in cents (reflects the amount this account has earned from this payment). Compiled and calculated value, eventually consistent. To see all changes affecting the payment's balance call [Get Balance Transactions](#operation/GetPaymentBalanceTransactions)
          type: number
          example: 99850
        fee_amount:
          type: number
          description: sum of fees for this payment
          example: 150
        financial_transaction_id:
          type: string
          description: associated financial transaction id
          example: ft_123xyz
        captured:
          description: whether or not this payment is captured
          type: boolean
          example: true
        capture_strategy:
          type: string
          example: automatic
          enum:
          - automatic
          - manual
        currency:
          type: string
          enum:
          - usd
          - cad
          example: usd
        description:
          type: string
          description: your meaningful description of the payment (e.g. an order number or other value from your system)
          example: my_order_xyz
        disputed:
          type: boolean
          description: whether or not this payment has any open or lost disputes
          example: false
        disputes:
          type: array
          description: list of associated disputes
          example: []
        error_code:
          type: string
          description: error code if the payment fails
          example: credit_card_number_invalid
        error_description:
          type: string
          description: text description of the error code
          example: Credit Card Number Invalid (Failed LUHN checksum)
        is_test:
          type: boolean
          description: whether or not this payment was made using the test account
          example: true
        metadata:
          type: object
          format: json
          description: any useful information you'd like to store alongside this payment
          example: {}
        payment_intent_id:
          type: string
          description: unique id of associated payment intent
          example: pi_123xyz
        checkout_id:
          type: string
          description: unique id of associated checkout
          example: cho_123xyz
        payment_method:
          $ref: '#/components/schemas/CardPaymentMethod'
        application_fee:
          $ref: '#/components/schemas/ApplicationFee'
        application_fee_rate_id:
          type: string
          description: unique id of application fee rate applied to this payment, if any
          example: afr_123xyz
        fees:
          type: array
          description: 'Array of fee objects showing the fees charged on this payment with their remaining refundable amounts.

            Populated whether the fees were provided via the `fees` array in the payment request or calculated automatically (for example, from a Standard Fee Configuration, or the `processing_fee` on a CAD payment).


            **Note:** This array is empty in the Create Payment response. Fees are processed asynchronously —

            subscribe to payment webhook events (recommended) to receive the full fee objects

            (with `id`, `remaining_amount`, and `currency`), or poll with a subsequent Get Payment request.


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

            '
          items:
            $ref: '#/components/schemas/FeeResponse'
          example:
          - id: pyfee_abc
            type: processing_fee
            amount: 350
            currency: usd
            remaining_amount: 350
            source_configuration_id: sfc_abc123
            source_fee_type: processing_ecomm
            refund_id: null
          - id: pyfee_xyz
            type: platform_fee
            amount: 500
            currency: usd
            remaining_amount: 500
            source_configuration_id: sfc_abc123
            source_fee_type: platform
            refund_id: null
        refunded:
          type: boolean
          description: whether or not this payment has any refunds
          example: false
        status:
          type: string
          enum:
          - pending
          - authorized
          - canceled
          - succeeded
          - failed
          - partially_refunded
          - fully_refunded
          - disputed
          description: status of the payment
        payment_mode:
          type: string
          example: ecom
          enum:
          - ecom
          - ach
          - card_present
        terminal_id:
          type: string
          description: id of terminal used to process the card payment, if any
          example: trm_123xyz
        transaction_hold:
          allOf:
          - type: object
          - description: present when the payment has been flagged for review and held from payouts
          - $ref: '#/components/schemas/TransactionHold'
        expedited:
          type:
          - boolean
          - 'null'
          description: settlement priority of the payment, only applies to ACH payments
          example: null
        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'
    CardPaymentMethod:
      type: object
      properties:
        card:
          $ref: '#/components/schemas/Card'
        customer_id:
          description: customer_id is a deprecated field. Please use our payment method groups instead.
          type:
          - string
          - 'null'
          example: cust_xyz
        signature:
          description: signature that uniquely identifies a credit card or bank account across payment methods
          type:
          - string
          - 'null'
          example: 4guAJNkVA3lRLVlanNVoBK
        account_id:
          description: account id associated with payment method
          type:
          - string
          - 'null'
          example: acc_123
    BankAccountPayment:
      type: object
      properties:
        id:
          description: unique payment id
          type: string
          example: py_xyz
        account_id:
          type: string
          format: uuid
          example: acc_xyz
        amount:
          description: payment amount in cents
          type: number
          example: 10000
        amount_disputed:
          description: sum of open or lost disputes for this payment, in cents
          type: number
          example: 0
        amount_refunded:
          description: sum of refunds for this payment, in cents
          type: number
          example: 0
        amount_refundable:
          description: amount of this payment currently able to be refunded, in cents
          type: number
          example: 10000
        balance:
          description: sum of debits and credits for this payment, in cents (reflects the amount this account has earned from this payment). Compiled and calculated value, eventually consistent. To see all changes affecting the payment's balance see [Get Balance Transactions](#operation/GetPaymentBalanceTransactions)
          type: number
          example: 99850
        fee_amount:
          type: number
          description: sum of fees for this payment
          example: 150
        financial_transaction_id:
          type: string
          description: associated financial transaction id
          example: ft_123xyz
        captured:
          description: whether or not this payment is captured
          type: boolean
          example: true
        capture_strategy:
          type: string
          example: automatic
          enum:
          - automatic
          - manual
        currency:
          type: string
          enum:
          - usd
          example: usd
        description:
          type: string
          description: your meaningful description of the payment (e.g. an order number or other value from your system)
          example: my_order_xyz
        disputed:
          type: boolean
          description: whether or not this payment has any open or lost disputes
          example: false
        disputes:
          type: array
          description: list of associated disputes
          example: []
        error_code:
          type: string
          description: error code if the payment fails
          example: credit_card_number_invalid
        error_description:
          type: string
          description: text description of the error code
          example: Credit Card Number Invalid (Failed LUHN checksum)
        is_test:
          type: boolean
          description: whether or not this payment was made using the test account
          example: true
        metadata:
          type: object
          format: json
          description: any useful information you'd like to store alongside this payment
          example: {}
        payment_intent_id:
          type: string
          description: unique id of associated payment intent
          example: pi_123xyz
        checkout_id:
          type: string
          description: unique id of associated checkout
          example: cho_123
        payment_method:
          $ref: '#/components/schemas/BankAccountPaymentMethod'
        application_fee:
          $ref: '#/components/schemas/ApplicationFee'
        application_fee_rate_id:
          type: string
          description: unique id of application fee rate applied to this payment, if any
          example: afr_123xyz
        fees:
          type: array
          description: 'Array of fee objects showing the fees charged on this payment with their remaining refundable amounts.

            Populated whether the fees were provided via the `fees` array in the payment request or calculated automatically (for example, from a Standard Fee Configuration).


            **Note:** This array is empty in the Create Payment response. Fees are processed asynchronously —

            subscribe to payment webhook events (recommended) to receive the full fee objects

            (with `id`, `remaining_amount`, and `currency`), or poll with a subsequent Get Payment request.


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

            '
          items:
            $ref: '#/components/schemas/FeeResponse'
          example:
          - id: pyfee_abc
            type: processing_fee
            amount: 50
            currency: usd
            remaining_amount: 50
            source_configuration_id: sfc_abc123
            source_fee_type: processing_ecomm
            refund_id: null
          - id: pyfee_xyz
            type: platform_fee
            amount: 150
            currency: usd
            remaining_amount: 150
            source_configuration_id: sfc_abc123
            source_fee_type: platform
            refund_id: null
        refunded:
          type: boolean
          description: whether or not this payment has any refunds
          example: false
        status:
          type: string
          enum:
          - pending
          - authorized
          - canceled
          - succeeded
          - failed
          - partially_refunded
          - fully_refunded
          - disputed
          description: status of the payment
        payment_mode:
          type: string
          example: ecom
          enum:
          - ecom
          - ach
          - card_present
        terminal_id:
          type: string
          description: id of terminal used to process a card payment, null for bank account payments
          example: trm_123xyz
        transaction_hold:
          allOf:
          - type: object
          - description: present when the payment has been flagged for review and held from payouts
          - $ref: '#/components/schemas/TransactionHold'
        expedited:
          type:
          - boolean
          - 'null'
          description: settlement priority of the payment, only applies to ACH payments
          example: true
        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'
    Card:
      type: object
      properties:
        id:
          description: unique card id
          type: string
          format: uuid
          example: pm_123xyz
        acct_last_four:
          description: last 4 digits of the card number
          type: string
          example: 4242
        brand:
          description: card brand or bank name
          example: Visa
        digital_wallet:
          description: which digital wallet provider the card is tied to
          type:
          - string
          - 'null'
          enum:
          - apple_pay
          - google_pay
          - null
          example: apple_pay
        name:
          description: card or account holder name
          type:
          - string
          - 'null'
          example: Amanda Kessel
        token:
          description: 'same value as unique card id; can be saved and used to process multiple

            payments with the same card

            '
          example: pm_123xyz
        month:
          description: expiration date month
          example: '5'
        year:
          description: expiration date year
          example: '2042'
        metadata:
          type:
          - object
          - 'null'
          format: json
          description: any useful information you'd like to store alongside this card
          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'
        address_line1_check:
          description: Result of the address line 1 verification check. `pass` — matches the cardholder's address on file; `fail` — does not match; `unavailable` — verification could not be performed; `unchecked` — no address was provided for verification.
          type: string
          example: unchecked
          enum:
          - fail
          - pass
          - unavailable
          - unchecked
        address_postal_code_check:
          description: Result of the postal code verification check. `pass` — matches the cardholder's postal code on file; `fail` — does not match; `unavailable` — verification could not be performed; `unchecked` — no postal code was provided for verification.
          type: string
          example: unchecked
          enum:
          - fail
          - pass
          - unavailable
          - unchecked
    FeeResponse:
      type: object
      description: 'A fee object in API responses. The `fees` array is empty in the Create Payment response —

        subscribe to payment webhook events (recommended) to receive the full fee objects, or poll with a subsequent Get Payment request.

        '
      properties:
        id:
          type: string
          description: Unique identifier for this fee. Present when fetching a payment.
          example: pyfee_xyz
        type:
          type: string
          enum:
          - processing_fee
          - platform_fee
          - refund_processing_fee
          description: 'The type of fee:

            - `processing_fee`: Fees related to payment processing costs

            - `platform_fee`: Fees for your platform''s services

            - `refund_processing_fee`: A processing fee charged when a refund is processed. Currently applies to CAD payments only.

            '
          example: processing_fee
        amount:
          type: integer
          description: Fee amount in cents
          example: 350
        currency:
          type: string
          description: Currency of the fee amount. Present when fetching a payment.
          enum:
          - usd
          - cad
          example: usd
        remaining_amount:
          type: integer
          description: Amount still available for refund in cents. Updates after each partial refund. Present when fetching a payment.
          example: 350
        source_configuration_id:
          type:
          - string
          - 'null'
          description: The public ID of the Standard Fee Configuration used to calculate this fee. Null when the fee was explicitly provided in the payment request rather than auto-calculated.
          example: sfc_abc123
        source_fee_type:
          type:
          - string
          - 'null'
          description: 'The fee type from the Standard Fee Configuration that generated this fee (e.g., `processing_ecomm`, `amex_brand_ecomm`, `platform`).

            Null when the fee was explicitly provided in the payment request.

            '
          example: amex_brand_ecomm
        refund_id:
          type:
          - string
          - 'null'
          description: The public ID of the refund this fee is associated with. Populated for `refund_processing_fee` fees (currently CAD payments only); null for all other fees. Present when fetching a payment.
          example: re_xyz
      required:
      - type
      - amount
    BankAccount:
      type: object
      properties:
        id:
          description: unique bank account payment method id
          type: string
          format: uuid
          example: pm_123xyz
        account_owner_name:
          description: account owner name
          type: string
          example: Lindsay Whalen
        account_type:
          description: type of account (checking, savings, etc.)
          type: string
          example: checking
        bank_name:
          description: bank name
          type:
          - string
          - 'null'
          example: Wells Fargo
        acct_last_four:
          description: last 4 digits of the account number
          type: string
          example: 1111
        token:
          description: 'same value as unique bank account id; can be saved and used to process multiple

            payments with the same bank account

            '
          example: pm_123xyz
        metadata:
          type:
          - object
          - 'null'
          format: json
          description: any useful information you'd like to store alongside this bank account
          example:
            new: info
    BankAccountPaymentMethod:
      type: object
      properties:
        bank_account:
          $ref: '#/components/schemas/BankAccount'
        customer_id:
          description: customer_id is a deprecated field. Please use our payment method groups instead.
          type:
          - string
          - 'null'
          example: cust_xyz
        signature:
          description: signature that uniquely identifies a credit card or bank account across payment methods
          type:
          - string
          - 'null'
          example: 4guAJNkVA3lRLVlanNVoBK
        account_id:
          description: account id associated with payment method
          type:
          - string
          - 'null'
          example: acc_123
  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)
    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