openapi: 3.1.0
info:
  title: Notify Shared Webhook Components
  version: 1.0.0
  description: >
    Shared component schemas for Notify v3 and v4 webhook specs. This file is a
    build artifact — not published as a standalone page.
components:
  schemas:
    WebhookMetadata:
      type: object
      required:
        - id
        - topic
        - topic_description
        - timestamp
        - version
      properties:
        id:
          type: string
          maxLength: 50
          description: >
            Ingo-assigned unique ID for this webhook delivery. Use as your
            idempotency key to prevent duplicate processing on retry.
          example: 7a6d0270-5912-4c31-8eac-3a344c419e98
        topic:
          type: string
          maxLength: 150
          description: Topic name identifying the event type.
          example: transaction.recipient.payment.status.success
        topic_description:
          type: string
          maxLength: 250
          description: Human-readable description of the topic.
        timestamp:
          type: integer
          description: Unix timestamp of the webhook delivery.
          example: 1629386098
        version:
          type: string
          maxLength: 5
          description: Payload version number.
          example: '1'
    WebhookAncillaryNotify:
      type: object
      required:
        - notification_id
        - participant_unique_id1
      properties:
        notification_id:
          type: string
          maxLength: 15
          description: Ingo-assigned unique identifier for the original transaction.
        session_id:
          type: string
          maxLength: 50
          nullable: true
          description: Ingo-assigned unique identifier for the customer session.
        participant_unique_id1:
          type: string
          maxLength: 100
          description: >-
            Participant-provided unique identifier from the original
            transaction.
          example: 39eef189-dd96-49e4-80d3-6346240c427a
        participant_unique_id2:
          type: string
          maxLength: 100
          nullable: true
          description: >
            Second participant-provided unique identifier from the original
            transaction, if provided at staging.
        party_id:
          type: string
          maxLength: 36
          nullable: true
          description: >
            Ingo-assigned unique ID for a party to the transaction. Provided for
            events occurring after successful transaction staging.
    WebhookEventBase:
      type: object
      required:
        - status
        - client_message
      properties:
        status:
          type: string
          maxLength: 10
          description: Numeric status code for the event.
        client_message:
          type: string
          maxLength: 250
          description: Human-readable description of the event update.
        attempt_count:
          type: integer
          description: >
            Current delivery attempt number, inclusive. Present only when the
            event has attempt counter configuration.
        max_attempts:
          type: integer
          description: >
            Maximum allowed delivery attempts. Present only when the event has
            attempt counter configuration.
    EventOtacDeliveryGenerate:
      allOf:
        - $ref: '#/components/schemas/WebhookEventBase'
      description: >
        No additional payload fields. Status indicates delivery channel: 1153 =
        OTAC sent via SMS, 1154 = OTAC sent via email.
    EventOtacDeliveryLimit:
      allOf:
        - $ref: '#/components/schemas/WebhookEventBase'
      description: |
        No additional payload fields. Status 1151 = OTAC send limit reached.
    EventOtacValidationSuccess:
      allOf:
        - $ref: '#/components/schemas/WebhookEventBase'
      description: |
        No additional payload fields. Status 1155 = OTAC authentication success.
    EventOtacValidationFailure:
      allOf:
        - $ref: '#/components/schemas/WebhookEventBase'
      description: |
        No additional payload fields. Status 1152 = OTAC authentication failure.
    EventOverallAuthSuccess:
      allOf:
        - $ref: '#/components/schemas/WebhookEventBase'
      description: >
        No additional payload fields. Status 1160 = Overall authentication
        success.
    EventOverallAuthFailure:
      allOf:
        - $ref: '#/components/schemas/WebhookEventBase'
      description: >
        No additional payload fields. Status codes — 1161: max failed attempts
        (DPA), 1162: OTAC send limit reached, 1163: OTAC inaccessible, 1164: max
        failed attempts (OTAC).
    FieldResultRvdm:
      type: object
      required:
        - field_name
        - is_matching
        - is_enabled
        - was_evaluated
        - client_provided_value
        - customer_provided_value
        - hard_fail_on_mismatch
      properties:
        field_name:
          type: string
          maxLength: 150
        is_matching:
          type: boolean
        is_enabled:
          type: boolean
        was_evaluated:
          type: boolean
        client_provided_value:
          type: string
          maxLength: 150
        customer_provided_value:
          type: string
          maxLength: 150
        hard_fail_on_mismatch:
          type: boolean
    EventRvdm:
      allOf:
        - $ref: '#/components/schemas/WebhookEventBase'
        - type: object
          required:
            - has_passed
            - was_skipped
            - field_results
          properties:
            has_passed:
              type: boolean
              description: Overall result of the RVDM attempt.
            was_skipped:
              type: boolean
              description: Indicates if RVDM was not performed per configuration.
            field_results:
              type: array
              items:
                $ref: '#/components/schemas/FieldResultRvdm'
    EventOfacNoPayload:
      allOf:
        - $ref: '#/components/schemas/WebhookEventBase'
      description: No additional payload fields beyond status and client_message.
    FieldResultPaypal:
      type: object
      required:
        - field_name
        - is_matching
        - is_enabled
        - was_evaluated
        - client_provided_value
        - paypal_provided_value
        - hard_fail_on_mismatch
      properties:
        field_name:
          type: string
          maxLength: 150
        is_matching:
          type: boolean
        is_enabled:
          type: boolean
        was_evaluated:
          type: boolean
        client_provided_value:
          type: string
          maxLength: 150
          description: >
            Value provided by the client. Can be a variable value (e.g. first
            name) when matching against a PayPal value, or a static value (e.g.
            true) when matching a PayPal setting like PayPal Verified.
        paypal_provided_value:
          type: string
          maxLength: 150
        hard_fail_on_mismatch:
          type: boolean
    EventPaypalVerification:
      allOf:
        - $ref: '#/components/schemas/WebhookEventBase'
        - type: object
          required:
            - has_passed
            - was_skipped
            - field_results
          properties:
            has_passed:
              type: boolean
            was_skipped:
              type: boolean
            field_results:
              type: array
              items:
                $ref: '#/components/schemas/FieldResultPaypal'
    EventAccountVerificationNoPayload:
      allOf:
        - $ref: '#/components/schemas/WebhookEventBase'
      description: No additional payload fields beyond status and client_message.
    IssuerObject:
      type: object
      required:
        - payee_id
        - payee_name
        - issuing_network
        - credit_enabled
        - debit_enabled
      properties:
        payee_id:
          type: string
          maxLength: 20
        payee_name:
          type: string
          maxLength: 100
        payee_address:
          type: string
          maxLength: 150
          nullable: true
        payee_city:
          type: string
          maxLength: 150
          nullable: true
        payee_state:
          type: string
          maxLength: 2
          nullable: true
        payee_zip:
          type: string
          maxLength: 10
          nullable: true
        issuing_network:
          type: string
          maxLength: 10
          description: Network the account was issued under. "NA" if not known.
          example: Visa
        credit_enabled:
          type: integer
          enum:
            - 1
            - 2
          description: 1 = Enabled, 2 = Not Enabled
        debit_enabled:
          type: integer
          enum:
            - 1
            - 2
          description: 1 = Enabled, 2 = Not Enabled
        credit_info:
          type: object
          description: Present when credit_enabled is 1.
          properties:
            min:
              type: string
              maxLength: 10
            max:
              type: string
              maxLength: 10
            card_type:
              type: string
              maxLength: 20
            estimated_posting_time:
              type: string
              maxLength: 150
            estimated_posting_date:
              type: string
              maxLength: 10
        debit_info:
          type: object
          description: Present when debit_enabled is 1.
          properties:
            min:
              type: string
              maxLength: 10
            max:
              type: string
              maxLength: 10
            card_type:
              type: string
              maxLength: 10
        network_validation:
          type: object
          description: >
            Reference data from network card validation. Present based on client
            validation configuration.
          properties:
            validation_provider_id:
              type: string
              maxLength: 3
              description: 1 = Visa, 3 = MasterCard
            name_validation:
              type: object
              properties:
                name_match_status:
                  type: string
                  maxLength: 3
                  description: >
                    1 = performed, 2 = not performed, 3 = not supported, 4 = not
                    configured
                name_match_decision:
                  type: string
                  maxLength: 3
                  description: 1 = Match, 2 = Partial match, 3 = No match
                first_name_match_decision:
                  type: string
                  maxLength: 3
                last_name_match_decision:
                  type: string
                  maxLength: 3
                middle_name_match_decision:
                  type: string
                  maxLength: 3
        open_banking_finicity:
          type: object
          description: >
            Present when client is configured for Finicity open banking
            services.
          properties:
            customer_id:
              type: string
              maxLength: 50
            account_id:
              type: string
              maxLength: 50
    EventTokenizationBase:
      allOf:
        - $ref: '#/components/schemas/WebhookEventBase'
        - type: object
          required:
            - customer_account_token
            - account_type
            - last_4
            - account_id
            - issuers
          properties:
            customer_account_token:
              type: string
              maxLength: 50
              description: >
                Token representing the customer account. Use for subsequent
                process payment funding requests via Ingo Payments.
            account_type:
              type: string
              maxLength: 2
              enum:
                - CA
                - AC
                - BP
              description: CA = Card, AC = ACH, BP = BillerPayee
            last_4:
              type: string
              maxLength: 4
              description: Last four digits of the account number.
            expiration_date:
              type: string
              maxLength: 4
              description: Expiration date (YYMM format). Card accounts only.
            account_id:
              type: string
              maxLength: 36
              description: >
                Account-specific identifier. Introduced April 2024. Available
                upon request for pre-existing clients.
            issuers:
              type: array
              description: Account issuer details. Typically a single object.
              items:
                $ref: '#/components/schemas/IssuerObject'
    EventCheckIssuedPaid:
      allOf:
        - $ref: '#/components/schemas/WebhookEventBase'
        - type: object
          required:
            - check_number
            - check_amount
          properties:
            check_number:
              type: string
              maxLength: 10
            check_amount:
              type: string
              maxLength: 10
    EventCheckCanceledStopped:
      allOf:
        - $ref: '#/components/schemas/WebhookEventBase'
        - type: object
          required:
            - check_number
            - check_amount
            - reason_code
          properties:
            check_number:
              type: string
              maxLength: 10
            check_amount:
              type: string
              maxLength: 10
            reason_code:
              type: string
              maxLength: 10
    EventCheckReturned:
      allOf:
        - $ref: '#/components/schemas/WebhookEventBase'
        - type: object
          required:
            - check_number
            - check_amount
            - reason_code
          properties:
            check_number:
              type: string
              maxLength: 10
            check_amount:
              type: string
              maxLength: 10
            reason_code:
              type: string
              maxLength: 10
    EventPaymentReturned:
      allOf:
        - $ref: '#/components/schemas/WebhookEventBase'
        - type: object
          required:
            - return_transaction_id
            - reason_code
            - reason_description
          properties:
            return_transaction_id:
              type: string
              maxLength: 15
              description: Ingo-assigned identifier for the return transaction.
            reason_code:
              type: string
              maxLength: 10
              description: Numeric reason code for the return.
            reason_description:
              type: string
              maxLength: 250
              description: Description of the return reason.
    EventPaymentNoPayload:
      allOf:
        - $ref: '#/components/schemas/WebhookEventBase'
      description: No additional payload fields beyond status and client_message.