asyncapi: 3.0.0
info:
  title: Ingo Payments — Notify Webhooks
  version: 1.0.0
  description: >
    Ingo delivers webhook events to your registered HTTPS endpoint via HTTP POST
    for all Notify (SaaS) disbursement activity. Return any 2xx status to
    acknowledge receipt. Non-2xx responses are retried every 60 minutes for up
    to 24 hours.
  contact:
    name: Ingo Money Integrations
    url: https://ingopayments.com/contact
defaultContentType: application/json
channels:
  notificationStatusSent:
    address: transaction.recipient.notification.status.sent
    title: Notification Sent
    description: >-
      Fired when Ingo successfully delivers a disbursement notification to the
      recipient.
    messages:
      notificationStatusSent:
        $ref: '#/components/messages/NotificationStatus'
  rvdmSuccess:
    address: transaction.recipient.verification.rvdm.success
    title: RVDM Verification — Success
    description: >-
      Fired when Recipient Verification Data Matching (RVDM) completes
      successfully.
    messages:
      rvdmSuccess:
        $ref: '#/components/messages/RvdmSuccess'
  rvdmFailure:
    address: transaction.recipient.verification.rvdm.failure
    title: RVDM Verification — Failure
    description: Fired when RVDM verification fails for the recipient.
    messages:
      rvdmFailure:
        $ref: '#/components/messages/RvdmFailure'
  tokenizationSuccess:
    address: transaction.account.tokenization.success
    title: Account Tokenization — Success
    description: >-
      Fired when a recipient account is successfully tokenized via the iFrame
      plugin.
    messages:
      tokenizationSuccess:
        $ref: '#/components/messages/TokenizationSuccess'
operations:
  receiveNotificationStatusSent:
    action: receive
    channel:
      $ref: '#/channels/notificationStatusSent'
    summary: Recipient notification delivered
    tags:
      - name: Recipient Notification Events
  receiveRvdmSuccess:
    action: receive
    channel:
      $ref: '#/channels/rvdmSuccess'
    summary: RVDM verification passed
    tags:
      - name: Recipient Verification Events
  receiveRvdmFailure:
    action: receive
    channel:
      $ref: '#/channels/rvdmFailure'
    summary: RVDM verification failed
    tags:
      - name: Recipient Verification Events
  receiveTokenizationSuccess:
    action: receive
    channel:
      $ref: '#/channels/tokenizationSuccess'
    summary: Account tokenized successfully
    tags:
      - name: Account Tokenization Events
components:
  messages:
    NotificationStatus:
      name: NotificationStatus
      title: Notification Status
      contentType: application/json
      payload:
        $ref: '#/components/schemas/NotifyBasePayload'
      examples:
        - name: Notification Sent
          payload:
            metadata:
              id: prod01-6aaa3079-c1ff-4cae-b77a-4b76026fc846
              topic: transaction.recipient.notification.status.sent
              topic_description: Ingo successfully delivered a notification to the recipient.
              timestamp: 1777509495
              version: '1'
            data:
              ancillary:
                notification_id: '10042781'
                session_id: ''
                participant_unique_id1: INV-2024-00891
                participant_unique_id2: CUST-44712
                party_id: null
              event:
                status: '1200'
                client_message: Success - Notification Sent
                attempt_count: 1
                max_attempts: 3
    RvdmSuccess:
      name: RvdmSuccess
      title: RVDM Success
      contentType: application/json
      payload:
        $ref: '#/components/schemas/RvdmPayload'
      examples:
        - name: RVDM Passed
          payload:
            metadata:
              id: prod01-a2b3c4d5-e6f7-8901-abcd-ef1234567890
              topic: transaction.recipient.verification.rvdm.success
              topic_description: RVDM verification completed successfully.
              timestamp: 1777509600
              version: '1'
            data:
              ancillary:
                notification_id: '10042782'
                session_id: sess-abc123
                participant_unique_id1: INV-2024-00892
                participant_unique_id2: null
                party_id: null
              event:
                status: '1101'
                client_message: Success - Recipient Verified
                attempt_count: 1
                max_attempts: 3
                has_passed: true
                was_skipped: false
                field_results:
                  - field_name: last_name
                    is_matching: true
                    is_enabled: true
                    was_evaluated: true
                    client_provided_value: Frost
                    customer_provided_value: Frost
                    hard_fail_on_mismatch: true
    RvdmFailure:
      name: RvdmFailure
      title: RVDM Failure
      contentType: application/json
      payload:
        $ref: '#/components/schemas/RvdmPayload'
      examples:
        - name: RVDM Failed
          payload:
            metadata:
              id: prod01-b3c4d5e6-f7a8-9012-bcde-f12345678901
              topic: transaction.recipient.verification.rvdm.failure
              topic_description: RVDM verification failed for the recipient.
              timestamp: 1777509700
              version: '1'
            data:
              ancillary:
                notification_id: '10042783'
                session_id: ''
                participant_unique_id1: INV-2024-00893
                participant_unique_id2: null
                party_id: null
              event:
                status: '1102'
                client_message: Failure - Recipient Verification Failed
                attempt_count: 2
                max_attempts: 3
                has_passed: false
                was_skipped: false
                field_results:
                  - field_name: last_name
                    is_matching: false
                    is_enabled: true
                    was_evaluated: true
                    client_provided_value: Frost
                    customer_provided_value: Smith
                    hard_fail_on_mismatch: true
    TokenizationSuccess:
      name: TokenizationSuccess
      title: Account Tokenization Success
      contentType: application/json
      payload:
        $ref: '#/components/schemas/TokenizationSuccessPayload'
      examples:
        - name: Card Tokenized
          payload:
            metadata:
              id: prod01-c4d5e6f7-a8b9-0123-cdef-123456789012
              topic: transaction.account.tokenization.success
              topic_description: A recipient account was successfully tokenized.
              timestamp: 1777509800
              version: '1'
            data:
              ancillary:
                tracer_token: trc-7f8a9b0c1d2e3f4a
                session_id: sess-def456
                participant_unique_id1: INV-2024-00894
                participant_unique_id2: null
              event:
                status: '1115'
                client_message: Success - Account Tokenized
                attempt_count: 1
                max_attempts: 3
                customer_account_token: tok-a1b2c3d4e5f6
                account_type: CA
                last_4: '4242'
                expiration_date: '1226'
                account_id: acct-a1b2c3d4-e5f6-7890-abcd-ef12345678
  schemas:
    WebhookMetadata:
      type: object
      required:
        - id
        - topic
        - topic_description
        - timestamp
        - version
      description: Delivery metadata present on every webhook event.
      properties:
        id:
          type: string
          maxLength: 50
          description: >
            Ingo-assigned unique ID for this webhook delivery. Use as your
            idempotency key to deduplicate retries.
          example: prod01-6aaa3079-c1ff-4cae-b77a-4b76026fc846
        topic:
          type: string
          maxLength: 150
          description: Topic name identifying the event type. Matches the channel address.
          example: transaction.recipient.notification.status.sent
        topic_description:
          type: string
          maxLength: 250
          description: Human-readable description of the event.
          example: Ingo successfully delivered a notification to the recipient.
        timestamp:
          type: integer
          description: Unix timestamp of the webhook delivery.
          example: 1777509495
        version:
          type: string
          maxLength: 5
          description: Payload contract version.
          example: '1'
    NotifyCorrelation:
      type: object
      required:
        - notification_id
        - participant_unique_id1
      description: >
        Transaction correlation identifiers for Notify (SaaS) webhook events.
        Use these fields to match the event to a transaction in your system.
      properties:
        notification_id:
          type: string
          maxLength: 15
          description: Ingo-assigned unique identifier for the staged notification.
          example: '10042781'
        session_id:
          type: string
          maxLength: 50
          nullable: true
          description: Ingo-assigned session identifier, when applicable.
        participant_unique_id1:
          type: string
          maxLength: 100
          description: Your primary correlation ID from the original Notify request.
          example: INV-2024-00891
        participant_unique_id2:
          type: string
          maxLength: 100
          nullable: true
          description: Your optional secondary correlation ID.
          example: CUST-44712
        party_id:
          type: string
          maxLength: 36
          nullable: true
          description: >
            Ingo-assigned ID for the specific party this event relates to.
            Present on multi-party (Notify v4) events.
    IngoPayCorrelation:
      type: object
      required:
        - participant_unique_id1
      description: >
        Transaction correlation identifiers for IngoPay and Embedded iFrame
        webhook events. Use these fields to match the event to a transaction in
        your system.
      properties:
        tracer_token:
          type: string
          maxLength: 250
          nullable: true
          description: Ingo-assigned tracer identifier for the original request.
          example: trc-7f8a9b0c1d2e3f4a
        session_id:
          type: string
          maxLength: 50
          nullable: true
          description: Ingo-assigned session identifier for the iFrame interaction.
        participant_unique_id1:
          type: string
          maxLength: 100
          description: Your primary correlation ID from the original request.
          example: INV-2024-00894
        participant_unique_id2:
          type: string
          maxLength: 100
          nullable: true
          description: Your optional secondary correlation ID.
    WebhookEventBase:
      type: object
      required:
        - status
        - client_message
      description: Core event fields present on every webhook event.
      properties:
        status:
          type: string
          maxLength: 10
          description: Numeric status code for the event outcome.
          example: '1200'
        client_message:
          type: string
          maxLength: 250
          description: Human-readable description of the event outcome.
          example: Success - Notification Sent
        attempt_count:
          type: integer
          description: >
            Current delivery attempt number. Present when the event type has a
            configurable attempt counter.
          example: 1
        max_attempts:
          type: integer
          description: >
            Maximum allowed attempts. Present when the event type has a
            configurable attempt counter.
          example: 3
    EventRvdmResult:
      type: object
      required:
        - has_passed
        - was_skipped
        - field_results
      description: RVDM verification outcome detail.
      properties:
        has_passed:
          type: boolean
          description: Overall result of the RVDM verification attempt.
          example: true
        was_skipped:
          type: boolean
          description: Whether RVDM was bypassed per client configuration.
          example: false
        field_results:
          type: array
          description: Per-field match detail for each data element evaluated.
          items:
            $ref: '#/components/schemas/RvdmFieldResult'
    RvdmFieldResult:
      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
          description: Name of the field assessed.
          example: last_name
        is_matching:
          type: boolean
          description: Whether the field values matched.
          example: true
        is_enabled:
          type: boolean
          description: Whether this field was enabled for matching.
          example: true
        was_evaluated:
          type: boolean
          description: Whether this field was evaluated during this attempt.
          example: true
        client_provided_value:
          type: string
          maxLength: 150
          description: Value you submitted for this field in the Notify request.
          example: Frost
        customer_provided_value:
          type: string
          maxLength: 150
          description: Value the customer entered during the iFrame interaction.
          example: Frost
        hard_fail_on_mismatch:
          type: boolean
          description: Whether a mismatch on this field constitutes a hard failure.
          example: true
    EventTokenizationSuccess:
      type: object
      required:
        - customer_account_token
        - account_type
        - last_4
        - account_id
      description: Account tokenization result detail.
      properties:
        customer_account_token:
          type: string
          maxLength: 50
          description: >
            Opaque token representing the tokenized account. Use in subsequent
            Process or Debit requests to reference this account.
          example: tok-a1b2c3d4e5f6
        account_type:
          type: string
          maxLength: 2
          description: Account type code (CA, AC, PD, PU, VE).
          example: CA
        last_4:
          type: string
          maxLength: 4
          description: Last four digits of the account number.
          example: '4242'
        expiration_date:
          type: string
          maxLength: 4
          description: |
            Expiration date (MMYY format). Present for card-based accounts only.
          example: '1226'
        account_id:
          type: string
          maxLength: 36
          description: Ingo-assigned unique identifier for this account.
          example: acct-a1b2c3d4-e5f6-7890-abcd-ef12345678
    NotifyBasePayload:
      type: object
      required:
        - metadata
        - data
      properties:
        metadata:
          $ref: '#/components/schemas/WebhookMetadata'
        data:
          type: object
          required:
            - ancillary
            - event
          properties:
            ancillary:
              $ref: '#/components/schemas/NotifyCorrelation'
            event:
              $ref: '#/components/schemas/WebhookEventBase'
    RvdmPayload:
      type: object
      required:
        - metadata
        - data
      properties:
        metadata:
          $ref: '#/components/schemas/WebhookMetadata'
        data:
          type: object
          required:
            - ancillary
            - event
          properties:
            ancillary:
              $ref: '#/components/schemas/NotifyCorrelation'
            event:
              allOf:
                - $ref: '#/components/schemas/WebhookEventBase'
                - $ref: '#/components/schemas/EventRvdmResult'
    TokenizationSuccessPayload:
      type: object
      required:
        - metadata
        - data
      properties:
        metadata:
          $ref: '#/components/schemas/WebhookMetadata'
        data:
          type: object
          required:
            - ancillary
            - event
          properties:
            ancillary:
              $ref: '#/components/schemas/IngoPayCorrelation'
            event:
              allOf:
                - $ref: '#/components/schemas/WebhookEventBase'
                - $ref: '#/components/schemas/EventTokenizationSuccess'