JustiFi Events API

openapi: 3.2.0
info:
  title: Justifi Events API
  contact:
    email: api-development@justifi.ai
  termsOfService: https://justifi.ai/terms-and-conditions
  x-logo:
    url: https://justifi-brand-assets.s3.us-east-2.amazonaws.com/justifi-light-bg.png
  version: '1.0'
  description: 'Operations tagged Events across 27 of this provider''s published API definitions: justifi-ach-return-fees-api-openapi.yml, justifi-address-api-openapi.yml, justifi-api-credentials-api-openapi.yml, justifi-balance-transactions-api-openapi.yml, justifi-bank-account-api-openapi.yml, justifi-bind-insurance-api-openapi.yml, justifi-business-api-openapi.yml, justifi-checkouts-api-openapi.yml, justifi-disputes-api-openapi.yml, justifi-document-api-openapi.yml, justifi-fee-configurations-api-openapi.yml, justifi-identity-api-openapi.yml, justifi-payment-method-groups-api-openapi.yml, justifi-payment-methods-api-openapi.yml, justifi-payments-api-openapi.yml, justifi-payout-holds-api-openapi.yml, justifi-payouts-api-openapi.yml, justifi-proceeds-api-openapi.yml, justifi-provisioning-api-openapi.yml, justifi-refunds-api-openapi.yml, justifi-reports-api-openapi.yml, justifi-sub-accounts-api-openapi.yml, justifi-terminals-api-openapi.yml, justifi-terminals-orders-api-openapi.yml, justifi-terms-and-conditions-api-openapi.yml, justifi-voids-api-openapi.yml, justifi-web-component-tokens-api-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.justifi.ai/v1
  description: JustiFi API
tags:
- name: Events
paths: {}
webhooks:
  payments:
    post:
      description: 'Received for the following events: payment.created, payment.succeeded, payment.failed,

        payment.pending, payment.authorized, payment.captured, payment.canceled

        '
      tags:
      - Events
      operationId: paymentEvent
      summary: Payments
      requestBody:
        content:
          application/json:
            schema:
              allOf:
              - $ref: '#/components/schemas/Event'
              - properties:
                  data:
                    oneOf:
                    - $ref: '#/components/schemas/CardPayment'
                    - $ref: '#/components/schemas/BankAccountPayment'
            example: null
            examples:
              Card_payment_created_event:
                value:
                  id: evt_123xyz
                  account_id: acc_123xyz
                  account_type: test
                  platform_account_id: acc_987zyx
                  idempotency_key: string
                  request_id: req_123
                  version: v1
                  data:
                    id: py_xyz
                    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: my 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: succeeded
                    terminal_id: trm_123_xyz
                    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: {}
                        bin_details:
                          type: Debit
                          card_brand: Visa
                          card_class: Consumer
                          country: United States of America
                          issuer: WELLS FARGO BANK
                          funding_source: Debit
                        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'
                    transaction_hold:
                      id: th_123xyz
                      financial_transaction_id: ft_123xyz
                    refunds: []
                    disputes: []
                  event_name: payment.created
              Bank_account_payment_created_event:
                value:
                  id: evt_123xyz
                  account_id: acc_123xyz
                  account_type: test
                  platform_account_id: acc_987zyx
                  idempotency_key: string
                  request_id: req_123
                  version: v1
                  data:
                    id: py_xyz
                    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: my 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: succeeded
                    updated_at: '2021-01-01T12:00:00Z'
                    payment_method:
                      bank_account:
                        id: pm_123xyz
                        acct_last_four: '4242'
                        name: Sylvia Fowles
                        brand: Wells Fargo
                        token: pm_123xyz
                        created_at: '2021-01-01T12:00:00Z'
                        updated_at: '2021-01-01T12:00:00Z'
                      customer_id: cust_123xyz
                      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'
                    transaction_hold:
                      id: th_123xyz
                      financial_transaction_id: ft_123xyz
                    refunds: []
                    disputes: []
                  event_name: payment.created
      responses:
        '200':
          description: Return a 200 status to indicate that the data was received successfully. You must respond within 5 seconds.
    servers:
    - url: https://api.justifi.ai/v1
      description: JustiFi API
  payment_methods:
    post:
      description: 'Received for the following events: payment_method.created, payment_method.updated, payment_method.bin_mapped

        '
      tags:
      - Events
      operationId: paymentMethodEvent
      summary: Payment Methods
      requestBody:
        content:
          application/json:
            schema:
              allOf:
              - $ref: '#/components/schemas/Event'
              - properties:
                  data:
                    oneOf:
                    - $ref: '#/components/schemas/CardPaymentMethod'
                    - $ref: '#/components/schemas/BankAccountPaymentMethod'
            example: null
            examples:
              Card_payment_method_created_event:
                value:
                  id: evt_123xyz
                  account_id: acc_123xyz
                  account_type: test
                  platform_account_id: acc_456abc
                  idempotency_key: 30abie390hjag49h
                  request_id: req_100abc
                  version: v1
                  data:
                    signature: 9fxy123
                    customer_id: cust_987zyx
                    status: valid
                    invalid_reason: nil
                    card:
                      id: pm_123xyz
                      name: Sylvia Fowles
                      acct_last_four: '4242'
                      brand: visa
                      token: pm_123xyz
                      month: '5'
                      year: '2042'
                      metadata: {}
                      address_line1_check: pass
                      address_postal_code_check: pass
                  event_name: payment_method.created
              Bank_account_payment_method_created_event:
                value:
                  id: evt_123xyz
                  account_id: acc_123xyz
                  account_type: test
                  platform_account_id: acc_456abc
                  idempotency_key: 30abie390hjag49h
                  request_id: req_100abc
                  version: v1
                  data:
                    signature: 9fxy123
                    customer_id: cust_987zyx
                    status: valid
                    invalid_reason: nil
                    bank_account:
                      id: pm_123xyz
                      acct_last_four: '9876'
                      brand: Wells Fargo
                      name: Phil Kessel
                      token: pm_123xyz
                      metadata: {}
                  event_name: payment_method.created
              Card_payment_method_bin_mapped_event:
                value:
                  id: evt_123xyz
                  account_id: acc_123xyz
                  account_type: test
                  platform_account_id: acc_456abc
                  idempotency_key: 30abie390hjag49h
                  request_id: req_100abc
                  version: v1
                  data:
                    signature: 9fxy123
                    customer_id: cust_987zyx
                    status: valid
                    invalid_reason: nil
                    card:
                      id: pm_123xyz
                      name: Sylvia Fowles
                      acct_last_four: '4242'
                      brand: visa
                      token: pm_123xyz
                      month: '5'
                      year: '2042'
                      metadata: {}
                      address_line1_check: pass
                      address_postal_code_check: pass
                      bin_details:
                        type: Debit
                        card_brand: Visa
                        card_class: Consumer
                        country: United States of America
                        issuer: WELLS FARGO BANK
                        funding_source: Debit
                  event_name: payment_method.bin_mapped
      responses:
        '200':
          description: Return a 200 status to indicate that the data was received successfully. You must respond within 5 seconds.
    servers:
    - url: https://api.justifi.ai/v1
      description: JustiFi API
  refunds:
    post:
      description: 'Received for the following events: payment.refunded, payment.refund.updated

        '
      tags:
      - Events
      operationId: refundEvent
      summary: Refunds
      requestBody:
        content:
          application/json:
            schema:
              allOf:
              - $ref: '#/components/schemas/Event'
              - properties:
                  data:
                    $ref: '#/components/schemas/Refund'
      responses:
        '200':
          description: Return a 200 status to indicate that the data was received successfully. You must respond within 5 seconds.
    servers:
    - url: https://api.justifi.ai/v1
      description: JustiFi API
  disputes:
    post:
      description: 'Received for the following events: payment.dispute.created, payment.dispute.closed, payment.dispute.forfeited, payment.dispute.submitted

        '
      tags:
      - Events
      operationId: disputeEvent
      summary: Disputes
      requestBody:
        content:
          application/json:
            schema:
              allOf:
              - $ref: '#/components/schemas/Event'
              - properties:
                  data:
                    $ref: '#/components/schemas/Dispute'
      responses:
        '200':
          description: Return a 200 status to indicate that the data was received successfully.  You must respond within 5 seconds.
    servers:
    - url: https://api.justifi.ai/v1
      description: JustiFi API
  dispute_evidence:
    post:
      description: 'Received for the following events: payment.dispute_evidence.created, payment.dispute_evidence.uploaded

        '
      tags:
      - Events
      operationId: disputeEvidenceEvent
      summary: Dispute Evidence
      requestBody:
        content:
          application/json:
            schema:
              allOf:
              - $ref: '#/components/schemas/Event'
              - properties:
                  data:
                    $ref: '#/components/schemas/DisputeEvidence'
      responses:
        '200':
          description: Return a 200 status to indicate that the data was received successfully. You must respond within 5 seconds.
    servers:
    - url: https://api.justifi.ai/v1
      description: JustiFi API
  payouts:
    post:
      description: 'Received for the following events: payout.created, payout.paid, payout.failed, proceeds.payout.created

        '
      tags:
      - Events
      operationId: payoutEvent
      summary: Payouts
      requestBody:
        content:
          application/json:
            schema:
              allOf:
              - $ref: '#/components/schemas/Event'
              - properties:
                  data:
                    $ref: '#/components/schemas/Payout'
      responses:
        '200':
          description: Return a 200 status to indicate that the data was received successfully. You must respond within 5 seconds.
    servers:
    - url: https://api.justifi.ai/v1
      description: JustiFi API
  sub_accounts:
    post:
      description: 'Received for the following events: sub_account.updated. This is published when an account''s status changes.

        '
      tags:
      - Events
      operationId: subAccountEvent
      summary: Sub Accounts
      requestBody:
        content:
          application/json:
            schema:
              allOf:
              - $ref: '#/components/schemas/Event'
              - properties:
                  data:
                    $ref: '#/components/schemas/SubAccount'
      responses:
        '200':
          description: Return a 200 status to indicate that the data was received successfully. You must respond within 5 seconds.
    servers:
    - url: https://api.justifi.ai/v1
      description: JustiFi API
  application_fee_rates:
    post:
      description: 'Received for the following events: application_fee_rate.created, application_fee_rate.updated

        '
      tags:
      - Events
      operationId: applicationFeeRateEvent
      summary: Application Fee Rates
      requestBody:
        content:
          application/json:
            schema:
              allOf:
              - $ref: '#/components/schemas/Event'
              - properties:
                  data:
                    $ref: '#/components/schemas/ApplicationFeeRate'
      responses:
        '200':
          description: Return a 200 status to indicate that the data was received successfully. You must respond within 5 seconds.
    servers:
    - url: https://api.justifi.ai/v1
      description: JustiFi API
  checkouts:
    post:
      description: 'Received for the following events: checkout.created, checkout.completed

        '
      tags:
      - Events
      operationId: checkoutEvent
      summary: Checkouts
      requestBody:
        content:
          application/json:
            schema:
              allOf:
              - $ref: '#/components/schemas/Event'
              - properties:
                  data:
                    $ref: '#/components/schemas/Checkout'
      responses:
        '200':
          description: Return a 200 status to indicate that the data was received successfully. You must respond within 5 seconds.
    servers:
    - url: https://api.justifi.ai/v1
      description: JustiFi API
  checkout_completions:
    post:
      description: 'Received for the following events: checkout.completion.succeeded, checkout.completion.failed, and

        checkout.completion.processing. Note checkout.completion.processing is only sent for terminal payments when

        a payment amount is sent to a terminal for processing.

        '
      tags:
      - Events
      operationId: checkoutCompletionEvent
      summary: Checkout Completions
      requestBody:
        content:
          application/json:
            schema:
              allOf:
              - $ref: '#/components/schemas/Event'
              - properties:
                  data:
                    $ref: '#/components/schemas/CheckoutCompletion'
      responses:
        '200':
          description: Return a 200 status to indicate that the data was received successfully. You must respond within 5 seconds.
    servers:
    - url: https://api.justifi.ai/v1
      description: JustiFi API
  payment_setting_updated:
    post:
      description: 'Received for the following event: account.payment_setting.updated

        '
      tags:
      - Events
      operationId: accountPaymentSettingUpdatedEvent
      summary: Account Payment Setting Updated
      requestBody:
        content:
          application/json:
            schema:
              allOf:
              - $ref: '#/components/schemas/Event'
              - properties:
                  data:
                    $ref: '#/components/schemas/PaymentSetting'
      responses:
        '200':
          description: Return a 200 status to indicate that the data was received successfully.  You must respond within 5 seconds.
    servers:
    - url: https://api.justifi.ai/v1
      description: JustiFi API
  payout_setting_updated:
    post:
      description: 'Received for the following event: account.payout_setting.updated

        '
      tags:
      - Events
      operationId: accountPayoutSettingUpdatedEvent
      summary: Account Payout Setting Updated
      requestBody:
        content:
          application/json:
            schema:
              allOf:
              - $ref: '#/components/schemas/Event'
              - properties:
                  data:
                    $ref: '#/components/schemas/PayoutSetting'
      responses:
        '200':
          description: Return a 200 status to indicate that the data was received successfully.  You must respond within 5 seconds.
    servers:
    - url: https://api.justifi.ai/v1
      description: JustiFi API
  terminal_orders:
    post:
      description: 'Received for the following events: terminal_order.created, terminal_order.updated

        '
      tags:
      - Events
      operationId: terminalOrderEvent
      summary: Terminal Orders
      requestBody:
        content:
          application/json:
            schema:
              allOf:
              - $ref: '#/components/schemas/Event'
              - properties:
                  data:
                    $ref: '#/components/schemas/TerminalsOrder'
      responses:
        '200':
          description: Return a 200 status to indicate that the data was received successfully. You must respond within 5 seconds.
    servers:
    - url: https://api.justifi.ai/v1
      description: JustiFi API
  reports:
    post:
      description: 'Received for the following events: report.scheduled, report.processing, report.completed, report.failed, report.canceled

        '
      tags:
      - Events
      operationId: reportEvent
      summary: Reports
      requestBody:
        content:
          application/json:
            schema:
              allOf:
              - $ref: '#/components/schemas/Event'
              - properties:
                  data:
                    $ref: '#/components/schemas/Report'
      responses:
        '200':
          description: Return a 200 status to indicate that the data was received successfully. You must respond within 5 seconds.
    servers:
    - url: https://api.justifi.ai/v1
      description: JustiFi API
components:
  schemas:
    Fee:
      type: object
      description: A fee object specifying type and amount
      properties:
        type:
          type: string
          enum:
          - processing_fee
          - platform_fee
          description: 'The type of fee:

            - `processing_fee`: Fees related to payment processing costs

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

            '
          example: processing_fee
        amount:
          type: integer
          description: Fee amount in cents
          example: 350
      required:
      - type
      - amount
    CheckoutCompletion:
      type: object
      properties:
        id:
          description: unique checkout completion id
          type: string
          example: chc_xyz
        payment_mode:
          type: string
          example: ecom
          enum:
          - ecom
          - bnpl
          - card_present
        payment_token:
          type: string
          example: pm_xyz123
          description: the payment method token used to process the payment, only for ecom payments
        status:
          type: string
          enum:
          - succeeded
          - failed
          - processing
          example: succeeded
          description: the status of the completion, only succeeded or failed
        payment_status:
          type: string
          enum:
          - succeeded
          - failed
          - pending
          - canceled
          - skipped
          example: succeeded
          description: depending upon payment mode, the status of the payment API call, bnpl transaction, or card reader transaction.
        payment_error_code:
          type: string
          example: card_declined
          description: when payment fails, related error code
        payment_error_description:
          type: string
          example: Your card was declined
          description: when payment fails, related error description
        payment_response:
          allOf:
          - type: object
          - description: payment object if completion attempt was successful, error object if not successful
          - $ref: '#/components/schemas/CardPaymentWithEnvelope'
        checkout_id:
          type: string
          format: uuid
          description: id of the checkout for this completion
          example: cho_xyz123
        additional_transactions:
          type: array of objects
          description: legacy attribute, other transactions processed during checkout completion. For example, insurance payments
        checkout:
          $ref: '#/components/schemas/Checkout'
        payment_id:
          type: string
          format: uuid
          example: py_xyz123
          description: id of the payment associated with this checkout, when successful
        payment_method_id:
          type: string
          format: uuid
          example: pm_xyz123
          description: id of the payment associated with this checkout, when successful
        terminal_id:
          type: string
          format: uuid
          example: trm_xyz123
          description: id of the terminal used for this checkout, when mode is card present
        created_at:
          type: string
          format: date-time
          example: '2024-01-01T12:00:00Z'
        updated_at:
          type: string
          format: date-time
          example: '2024-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
    Checkout:
      type: object
      properties:
        id:
          description: unique checkout id
          type: string
          format: uuid
          example: cho_xyz
        account_id:
          description: id of the account associated with the checkout
          type: string
          format: uuid
          example: acc_xyz
        platform_account_id:
          description: id of the platform account associated with the checkout
          type: string
          format: uuid
          example: acc_xyz
        payment_intent_id:
          description: id of the payment intent associated with the checkout
          type: string
          format: uuid
          example: pi_xyz
        payment_amount:
          description: the amount charged in cents
          type: number
          example: 10000
        payment_currency:
          type: string
          enum:
          - USD
          - CAD
          example: USD
        payment_description:
          type: string
          description: your custom description of the payment if passed in the `payment` property during checkout creation, otherwise "Checkout [checkout id]"
          example: my order xyz
        payment_methods:
          type: array
          description: if `payment_method_group_id` was provided, list of payment methods contained in that payment method group
          example:
          - id: pm_123xyz
            type: card
            status: valid
            invalid_reason: null
            name: John Doe
            brand: visa
            acct_last_four: '4321'
            month: '12'
            year: '2031'
            address_line1_check: pass
            address_postal_code_check: pass
            bin_details: {}
          - id: pm_789abc
            type: bank_account
            status: valid
            invalid_reason: null
            account_owner_name: Mary Lane
            account_type: checking
            bank_name: Altra
            acct_last_four: '4512'
        payment_method_group_id:
          type: string
          description: id of payment method group used for checkout, if provided
          format: uuid
          example: pmg_xyz
        status:
          type: string
          enum:
          - created
          - completed
          - attempted
          - expired
          description: status of the checkout
        mode:
          type: string
          enum:
          - test
          - live
          description: mode of the checkout
          example: test
        successful_payment_id:
          type: string
          format: uuid
          example: py_123xyz
          description: payment id, if this checkout was paid for successfully
        statement_descriptor:
          type: string
          description: description of the payment that will be available on the account's bank statement
          example: Big Business
        metadata:
          type: object
          example: {}
        application_fees:
          type: object
          deprecated: true
          description: '**Deprecated**: Use the `fees` object instead for granular control over fee types and selective refunds.


            **New integrations** should use `payment.fees` instead for selective refund support. See [Enhanced Fee Management](#section/Enhanced-Fee-Management).

            '
          properties:
            card:
              type: object
              properties:
                amount:
                  description: custom application fee amount that applies to card payment method
                  example: 300
            bank_account:
              type: object
              properties:
                amount:
                  description: custom application fee amount that applies to bank account payment method
                  example: 150
        payment_settings:
          type: object
          description: payment configuration information for the checkout
          example:
            ach_payments: true
            bnpl_payments: false
            credit_card_payments: true
            insurance_payments: false
            bank_account_verification: false
        payment:
          type: object
          description: data passed to the `payment` property during checkout creation, or null
          properties:
            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
            metadata:
              type: object
              format: json
              description: any useful custom information stored alongside this payment
              example:
                new: info
            expedited:
              type: boolean
              description: settlement priority of the payment, defaults to false
              example: true
            fees:
              type: array
              description: 'Array of fee objects specifying the fees to be applied when the checkout is completed.

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

                '
              items:
                $ref: '#/components/schemas/Fee'
              example:
              - type: processing_fee
                amount: 295
              - type: platform_fee
                amount: 150
        created_at:
          type: string
          format: date-time
          example: '2024-01-01T12:00:00Z'
        updated_at:
          type: string
          format: date-time
          example: '2024

# --- truncated at 32 KB (82 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/justifi/refs/heads/main/openapi/justifi-events-api-openapi.yml