asyncapi: 3.0.0
info:
  title: Mobile Check Cashing SDK — Webhooks
  version: 1.0.0
  description: >
    Asynchronous event notifications from the Mobile Check Cashing SDK. Use them
    to power push notifications, email alerts, data warehouse entries, and
    customer support dashboards in your own systems.


    **How delivery works.** Ingo does NOT push notifications directly to mobile
    devices (security and app vendor constraints). Instead, Ingo POSTs events to
    your partner-registered server URL; your server then forwards to your push
    provider (Urban Airship, Apple, etc.), email system, or analytics pipeline.


    **Registering your endpoint.** Your post handler URL **must be registered**
    with Ingo when this service is enabled. Separate URLs for UAT and Production
    are supported. Provide them to your Ingo Project Manager or Technical Lead
    during onboarding.


    **Payload shape.** All events POST `application/json` with a flat field map.
    Every payload includes `NotificationType` (numeric) and
    `NotificationTypeDescription` (text). All amounts are in cents. All dates
    are GMT-0 UTC. Blank values or missing keys mean no data for that element.
    Absence of `NotificationType` should be considered an error.


    **Security.** If credentials are required on your endpoint, they must be
    encoded in the URL — Ingo does not support alternative auth mechanisms for
    the SDK webhook channel at this time.
  contact:
    name: Ingo Payments Integrations
    url: https://developers.ingopayments.com
defaultContentType: application/json
servers:
  webhook:
    host: your-webhook-endpoint.example.com
    protocol: https
    description: Ingo delivers SDK events via HTTP POST to your registered HTTPS endpoint.
channels:
  SdkCustomerEnrollment:
    address: sdk.customer.enrollment
    title: Customer Enrollment
    tags:
      - name: Customer Lifecycle
    description: |
      Fired when a new customer is enrolled via the SDK. `NotificationType` = 5.
    messages:
      SdkCustomerEnrollmentMessage:
        $ref: '#/components/messages/SdkNotificationMessage'
  SdkCardRegistrationFailed:
    address: sdk.card.registration.failed
    title: Card Registration Failed
    tags:
      - name: Card Lifecycle
    description: >
      Fired when a card registration attempt fails — AVS mismatch, expired card,
      BIN not configured, card-company decline, or similar. `NotificationType` =
      6.
    messages:
      SdkCardRegistrationFailedMessage:
        $ref: '#/components/messages/SdkNotificationMessage'
  SdkCardRegistrationSuccess:
    address: sdk.card.registration.success
    title: Card Registration Success
    tags:
      - name: Card Lifecycle
    description: >
      Fired when a card is successfully registered to a customer.
      `NotificationType` = 8.
    messages:
      SdkCardRegistrationSuccessMessage:
        $ref: '#/components/messages/SdkNotificationMessage'
  SdkTransactionInMinutes:
    address: sdk.transaction.in_minutes
    title: In Minutes Transaction
    tags:
      - name: Transaction Lifecycle
    description: >
      Fired whenever a new In Minutes transaction is generated.
      `NotificationType` = 9.
    messages:
      SdkTransactionInMinutesMessage:
        $ref: '#/components/messages/SdkNotificationMessage'
  SdkTransactionInDays:
    address: sdk.transaction.in_days
    title: In Days Transaction
    tags:
      - name: Transaction Lifecycle
    description: >
      Fired whenever a new In Days transaction is generated. `NotificationType`
      = 10.
    messages:
      SdkTransactionInDaysMessage:
        $ref: '#/components/messages/SdkNotificationMessage'
  SdkTransactionDeclined:
    address: sdk.transaction.declined
    title: Transaction Declined
    tags:
      - name: Transaction Lifecycle
    description: >
      Fired when a transaction is declined — either at approval (check doesn't
      meet Ingo's standards) or at load time for In Days transactions that
      decline due to return. `NotificationType` = 7. The `DeclineReason` and
      `DeclineCode` fields describe why.
    messages:
      SdkTransactionDeclinedMessage:
        $ref: '#/components/messages/SdkNotificationMessage'
  SdkTransactionCancelled:
    address: sdk.transaction.cancelled
    title: Cancel Transaction
    tags:
      - name: Transaction Lifecycle
    description: >
      Fired when a user or the system cancels a transaction. Users can cancel
      manually or decline the fee; the system cancels timed-out abandoned
      transactions. `NotificationType` = 11. `CancelledByDescription` indicates
      the source.
    messages:
      SdkTransactionCancelledMessage:
        $ref: '#/components/messages/SdkNotificationMessage'
  SdkTransactionAutoCancellation:
    address: sdk.transaction.auto_cancellation
    title: Auto Cancellation Transaction
    tags:
      - name: Transaction Lifecycle
    description: >
      Fired when a transaction is auto-cancelled by Ingo's system.
      `NotificationType` = 13.
    messages:
      SdkTransactionAutoCancellationMessage:
        $ref: '#/components/messages/SdkNotificationMessage'
  SdkTransactionReturned:
    address: sdk.transaction.returned
    title: Transaction Returned
    tags:
      - name: Transaction Lifecycle
    description: >
      Fired when the check is returned, post-approval (and post-card-load for In
      Minutes transactions). `NotificationType` = 16. This notification does NOT
      signify the return of funds from the customer's card.
    messages:
      SdkTransactionReturnedMessage:
        $ref: '#/components/messages/SdkNotificationMessage'
  SdkTransactionFunded:
    address: sdk.transaction.funded
    title: Transaction Funded
    tags:
      - name: Transaction Lifecycle
    description: >
      Final approval after funds have been loaded to the customer's card.
      `NotificationType` = 24. Most In Minutes flows end here.
    messages:
      SdkTransactionFundedMessage:
        $ref: '#/components/messages/SdkNotificationMessage'
  SdkTransactionFundingFailure:
    address: sdk.transaction.funding_failure
    title: Transaction Funding Failure
    tags:
      - name: Transaction Lifecycle
    description: >
      Fired when the transaction fails to load post-approval. Edge case — can
      occur when the customer's card exceeds balance limits or is closed before
      funding completes. `NotificationType` = 25.
    messages:
      SdkTransactionFundingFailureMessage:
        $ref: '#/components/messages/SdkNotificationMessage'
  SdkCheckFrankingRequired:
    address: sdk.check.franking.required
    title: Check Franking Required
    tags:
      - name: Transaction Lifecycle
    description: >
      Fired when the transaction requires the customer to capture an image of
      the voided/franked check before card load. Applies to certain transaction
      types and configurations. Post-approval, pre-card-load. `NotificationType`
      = 26.
    messages:
      SdkCheckFrankingRequiredMessage:
        $ref: '#/components/messages/SdkNotificationMessage'
  SdkCheckFrankingReset:
    address: sdk.check.franking.reset
    title: Check Franking Reset
    tags:
      - name: Transaction Lifecycle
    description: >
      Fired when the franking state for a transaction is reset (e.g., partner or
      Ingo support intervention). `NotificationType` = 32.
    messages:
      SdkCheckFrankingResetMessage:
        $ref: '#/components/messages/SdkNotificationMessage'
  SdkVoidedCheckReview:
    address: sdk.check.voided.review
    title: Voided Check Review
    tags:
      - name: Transaction Lifecycle
    description: >
      Fired when a voided check capture is queued for review. `NotificationType`
      = 31.
    messages:
      SdkVoidedCheckReviewMessage:
        $ref: '#/components/messages/SdkNotificationMessage'
  SdkVerifyKycDocuments:
    address: sdk.kyc.verify_documents
    title: Verify KYC Documents
    tags:
      - name: Customer Lifecycle
    description: >
      Fired when the customer must upload KYC documents (typically photo ID)
      before the transaction can proceed. `NotificationType` = 22.
    messages:
      SdkVerifyKycDocumentsMessage:
        $ref: '#/components/messages/SdkNotificationMessage'
  SdkDeviceVerificationFailureMailInRegistration:
    address: sdk.customer.device_verification.failure_mail_in_registration
    title: Device Verification Failure — Mail In Registration
    tags:
      - name: Customer Lifecycle
    description: >
      Fired when device verification fails for a customer routed through mail-in
      registration. `NotificationType` = 27.
    messages:
      SdkDeviceVerificationFailureMailInRegistrationMessage:
        $ref: '#/components/messages/SdkNotificationMessage'
  SdkEditProfile:
    address: sdk.customer.edit_profile
    title: Edit Profile
    tags:
      - name: Customer Lifecycle
    description: >
      Fired when a customer profile is edited via the SDK. `NotificationType` =
      15.
    messages:
      SdkEditProfileMessage:
        $ref: '#/components/messages/SdkNotificationMessage'
components:
  messages:
    SdkNotificationMessage:
      name: SdkNotification
      title: SDK Notification Payload
      summary: Flat JSON payload covering all SDK webhook event types.
      contentType: application/json
      payload:
        $ref: '#/components/schemas/SdkNotificationPayload'
  schemas:
    SdkNotificationPayload:
      type: object
      required:
        - NotificationType
        - NotificationTypeDescription
      description: >
        Shared payload shape for every SDK webhook event. The exact subset of
        populated fields depends on `NotificationType` — see individual channel
        descriptions for the typical key set per event.


        Conventions:

        - All amounts are in **cents**.

        - All dates are **GMT-0 UTC**.

        - Blank value or missing key indicates no data for that element.

        - `NotificationType` is always present; absence indicates a delivery
        error.

        - All field values are serialized as strings or numbers consistent with
        the type column below.
      properties:
        FirstName:
          type: string
          description: Customer's first name. E.g., "Jane".
        LastName:
          type: string
          description: Customer's last name. E.g., "Doe".
        CustomerEmailAddress:
          type: string
          format: email
          description: Primary email address on the Ingo Money account.
        CustomerId:
          type: string
          format: uuid
          description: Unique customer identifier.
        TransactionId:
          type: string
          format: uuid
          description: Unique transaction identifier.
        KeyedAmount:
          type: integer
          description: Customer-keyed check amount, in cents.
        LoadAmount:
          type: integer
          description: Amount that will be loaded to the card after fees, in cents.
        Fee:
          type: integer
          description: Fee charged for the transaction, in cents.
        FeeDeltaInCents:
          type: integer
          description: >-
            Difference between Ingo-assessed fees and partner-assessed SDK fees,
            in cents.
        IsPpg:
          type: boolean
          description: True if the check is a Pre-Printed Government check.
        PromoCode:
          type: string
          description: Promotion code name entered, if any.
        PromoType:
          type: string
          enum:
            - Addon Amount
            - Campaign Addon Amount
            - FriendBuy Campaign Addon Amount
          description: >
            Promotion code type. Bold items below are the most pertinent to SDK
            Partners.

            **Addon Amount**, **Campaign Addon Amount**, FriendBuy Campaign
            Addon Amount.
        PromoAmount:
          type: number
          description: Promotion amount value, in dollars and cents.
        CardId:
          type: string
          format: uuid
          description: Unique card identifier.
        CardNickName:
          type: string
          description: User-assigned card nickname.
        LastFourOfCard:
          type: string
          maxLength: 4
          description: Last four digits of the card account.
        CardBinNumber:
          type: string
          description: Card BIN.
        FundingDestinationIdentifier:
          type: string
          format: uuid
          description: Unique identifier for the partner funding destination.
        CheckSubmissionDate:
          type: string
          description: >-
            When the check was submitted into the Ingo network. Example format
            `MM/DD/YYYY HH:MM:SS` UTC.
        FundsAvailableDate:
          type: string
          description: >-
            When funds will be loaded to the customer's card. Same format as
            `CheckSubmissionDate`.
        NotificationId:
          type: string
          format: uuid
          description: Unique identifier for this notification delivery.
        NotificationType:
          type: integer
          enum:
            - 0
            - 5
            - 6
            - 7
            - 8
            - 9
            - 10
            - 11
            - 13
            - 15
            - 16
            - 22
            - 24
            - 25
            - 26
            - 27
            - 31
            - 32
          description: >
            Numeric notification type. Mapping:

            `0` Unknown · `5` Customer Enrollment · `6` Card Registration Failed
            · `7` Transaction Declined · `8` Card Registration Success · `9` In
            Minutes Transaction · `10` In Days Transaction · `11` Cancel
            Transaction · `13` Auto Cancellation Transaction · `15` Edit Profile
            · `16` Transaction Returned · `22` Verify KYC Documents · `24`
            Transaction Funded · `25` Transaction Funding Failure · `26` Check
            Franking Required · `27` Device Verification Failure Mail In
            Registration · `31` Voided Check Review · `32` Check Franking Reset.
        NotificationTypeDescription:
          type: string
          description: >-
            Text description of the notification type. Mirrors the enum mapping
            in `NotificationType`.
        TransactionType:
          type: integer
          enum:
            - 0
            - 1
            - 2
          description: |
            `0` Unknown · `1` In Minutes · `2` In Days.
        TransactionTypeDescription:
          type: string
          description: Text description of the transaction type.
        TransactionStatus:
          type: integer
          enum:
            - 0
            - 1
            - 2
            - 3
            - 4
            - 5
            - 6
            - 7
            - 8
            - 9
            - 10
            - 11
            - 12
            - 13
            - 14
          description: >
            `0` Unknown · `1` Ready To Process · `2` Credit Pending · `3`
            Completed · `4` New · `5` Cancelled · `6` Returned · `7` Load Failed
            · `8` Declined · `9` Review Pending · `10` In Review · `11` Credit
            Initiated · `12` Check Franking Pending · `13` Check Franking In
            Review · `14` Check Franking Reset.
        TransactionStatusDescription:
          type: string
          description: Text description of the transaction status.
        CancelledBy:
          type: integer
          description: Numeric identifier of who or what cancelled the transaction.
        CancelledByDescription:
          type: string
          enum:
            - None
            - User
            - System
            - RejectFee
            - DeviceVerification
            - InvalidDepositType
            - MDC
            - Velocity
            - KYC
          description: >
            Cause of cancellation. `0` None · `1` User · `2` System · `3`
            RejectFee · `4` DeviceVerification · `5` InvalidDepositType · `6`
            MDC · `7` Velocity · `8` KYC.
        DeclineReason:
          type: string
          description: >-
            Reason text for a decline. Decline reasons are not enumerated
            programmatically — do not branch on decline reason content.
        DeclineCode:
          type: string
          description: >-
            Decline code mapping to `DeclineReason`. Master list is maintained
            by Ingo and is out of scope for programmatic integration.
      example:
        FirstName: Jane
        LastName: Doe
        CustomerEmailAddress: jane.doe@example.com
        KeyedAmount: 14400
        LoadAmount: 13900
        Fee: 500
        LastFourOfCard: '0696'
        CardBinNumber: '471620'
        CheckSubmissionDate: 06/16/10:03:34
        FundsAvailableDate: 06/16/10:03:34
        NotificationType: 24
        NotificationTypeDescription: Transaction Funded
        TransactionType: 1
        TransactionTypeDescription: In Minutes
        TransactionStatus: 3
        TransactionStatusDescription: Completed
        CancelledByDescription: None
        DeclineReason: ''
        DeclineCode: ''
        CustomerId: 49e8cc02-d644-4025-a7a5-b30d9baea2a9
        CardId: c594e285-1ffb-425f-abf8-d5dcff94bbcb
        TransactionId: dd107f4c-8cc5-47cc-8654-01d0a5858fba