Financial Reports

Reports

In order to begin report generation for your partner integration you must make a request to Immersve specifying which reports you wish to receive.

These reports are generated in .jsonl format covering either a daily or monthly period of time. When reports become available for download a notification will be sent. The details of this notification as well as the list of supported report types can be found in the report completed webhook documentation.

Enum values listed in this guide may be extended in future releases. Parsing code should treat unknown values as informational rather than fail on them.

Funding Source Reporting

Funding reports describe balance changes across funding sources held by cardholders and partners. They include events for increases and decreases in balances, plus the related movement of funds. Each line item contains a snapshot of the relevant funding source or funding source interaction and the details of the event that altered its state.

1. Funding Source Interaction Report Line Item

{
  "event": {
    "id": "fsi-id-000000000000001",
    "type": "confirmed",
    "createdAt": "2026-04-05T10:00:05Z"
  },
  "fundingSourceInteraction": {
    "id": "fsi-id",
    "type": "payment",
    "status": "confirmed",
    "createdAt": "2026-04-05T10:00:00Z",
    "accountId": "account-id",
    "fundingSource": {
      "id": "fs-id",
      "fundingChannelId": "fc-id"
    },
    "amount": { "value": "30000000", "currency": "USDC" },
    "creditDebitIndicator": "debit",
    "relatedTransaction": { "type": "payment", "paymentId": "payment-id" }
  }
}

Enum values:

• event.type:
  • created — interaction recorded; no balance movement yet.
  • pending — processing initiated; balance has not moved.
  • confirmed — settled. The only balance-affecting status.
  • discarded — cancelled before settlement; the balance was never affected.
• fundingSourceInteraction.type: deposit, withdrawal, refund, payment.
• fundingSourceInteraction.status: same set as event.type, reflecting the state of the interaction at the time of the event.
• fundingSourceInteraction.creditDebitIndicator: credit or debit.
• fundingSourceInteraction.relatedTransaction.type: blockchain or payment.
  • When blockchain, transactionHash is populated and the row carries chainId and block.
  • When payment, paymentId is populated. It is the card payment transaction identifier, joinable to the Payment report.

amount.value is a string of the amount in minor units of the token (e.g. "30000000" for 30 USDC).

2. Funding Source Report Line Item

{
  "event": {
    "id": "fs-id-000000000000002",
    "type": "balance-decreased",
    "createdAt": "2026-04-05T10:00:05Z",
    "interactionEventId": "fsi-id-000000000000001",
    "amount": { "value": "30000000", "currency": "USDC" }
  },
  "fundingSource": {
    "id": "fs-id",
    "createdAt": "2026-03-01T12:00:00Z",
    "externalId": "external-id",
    "accountId": "account-id",
    "fundingChannel": {
      "id": "fc-id",
      "name": "usdc-funding-1"
    },
    "purpose": "card-funding",
    "mode": "deposit",
    "strategy": "custodial",
    "partnerAccountId": "partner-account-id",
    "balance": { "value": "70000000", "currency": "USDC" }
  }
}

Enum values:

• event.type: created, balance-increased, balance-decreased (created events carry no balance change and have amount.value of "0")

amount.value and balance.value are strings of the amount in minor units of the token.

Payment Reporting

Payment reports follow the same principle. They provide payment event line items with a snapshot of the payment state at each stage of its lifecycle. This model is also consistent with the payment updated webhook payload.

1. Payment Report Line Item

{
  "event": {
    "id": "payment-id-000000000000002",
    "type": "auth-accepted",
    "createdAt": "2026-04-20T03:10:02.938Z"
  },
  "payment": {
    "id": "payment-id",
    "createdAt": "2026-04-20T03:10:00.000Z",
    "modifiedAt": "2026-04-20T03:10:02.938Z",
    "pending": true,
    "type": "purchase",
    "creditDebitIndicator": "debit",
    "status": "holding",
    "amount": { "value": "1000", "currency": "USDC" },
    "acquirerAmount": { "value": "1000", "currency": "USD" },
    "feeAmount": { "value": "10", "currency": "USDC" },
    "feeComposition": [
      {
        "category": "fx",
        "rate": 0.015,
        "amount": {
          "value": "15",
          "currency": "USD"
        },
        "type": "variable"
      }
    ],
    "merchant": {
        "name": "mockCardAcceptorName",
        "regionCode": "US",
        "categoryCode": "mockMcc",
        "id": "mockCardAcceptorId",
        "terminalId": "mockCardAcceptorTerminalId",
        "city": "mockCardAcceptorCity"
    },
    "networkReference": "1429694598",
    "failureReason": null,
    "relatedPaymentId": null,
    "cardholder": { "id": "cardholder-account-id" },
    "card": { "id": "card-id" },
    "securityChallenge": {
      "outcome": "challenge-confirmed",
      "ref": "3ds-ref-123"
    }
  }
}

Enum values:

• event.type, one of:
  • auth-accepted
  • auth-completion-accepted
  • auth-completion-declined
  • auth-declined
  • auth-expired
  • auth-reversal-accepted
  • auth-reversal-declined
  • clearing-accepted
  • clearing-reversal-accepted
  • clearing-reversal-declined
  • payment-failed
• payment.type: purchase, refund, adjustment.
• payment.status: created, holding, cleared, canceled, failed.
• payment.creditDebitIndicator: credit or debit.

Join Logic for Downstream Processing

Use the following joins to ensure end-to-end traceability across report layers:

1. Funding Source event.interactionEventId links to fundingSourceInteraction.event.id.
2. When fundingSourceInteraction.type is payment, fundingSourceInteraction.relatedTransaction.paymentId links to Payment id.

Reconciling balances

To compute a running balance for a funding source, filter on event.type='confirmed' and sum amounts using the sign from creditDebitIndicator.

Scenario. A funding source has five interactions in one day:

Expected net balance change: +100 − 20 + 200 − 30 = +250 USDC. The discarded deposit never moved the balance.

The FSI report emits one row per partner-visible lifecycle transition (typically created and then confirmed or discarded). To reconcile, keep only the confirmed rows and apply the sign:

keep   rows where event.type = 'confirmed'
+amount when creditDebitIndicator = 'credit'
−amount when creditDebitIndicator = 'debit'
result: +100 + 200 − 20 − 30 = +250 USDC

The created and discarded rows for the same interactions are present in the report — they describe lifecycle transitions, not balance movement. Skipping them is essential:

• created rows would double-count the eventual confirmed amount.
• discarded rows describe interactions that were cancelled before settlement and never moved the balance.

The non-confirmed rows are not used for balance arithmetic but support operational analytics such as settlement latency (time between created and confirmed) and failure rates (count of discarded rows).

Migrating from legacy APIs

If you are moving from the legacy List Funding Source Interactions, Get Funding Source Balance, List Payment Notifications, and Get Payment Notification APIs to the new reports, the table below maps each legacy field to its new equivalent.

Schedule

Reports are generated on two schedules:

1. Daily reports cover 00:00:00 until 23:59:59.999 UTC and are generated immediately after the window closes. The report-completed webhook fires once the file is available.
2. Monthly reports cover 00:00:00 on the first day of the month until 23:59:59.999 UTC on the last day of the month and are generated immediately after the window closes. The report-completed webhook fires once the file is available.

You can choose to receive both, one or none of these time frames for each given report type. Also note the time it takes to complete a report can vary based on partner volume.

Webhook

To be notified when a report is ready for download, subscribe to the report-completed webhook topic. Refer to the report completed webhook documentation for full payload details and list of available report types.

Download

To download a report, call the report download API using the reportId from the webhook payload as the path parameter. The endpoint returns a pre-signed S3 URL with a TTL of 24 hours that can be used to download the report file.

Download API call example:

curl -L 'https://test.immersve.com/api/reports/{reportId}/download' \
  -H 'Content-Type: application/json' \
  -H "X-Api-Key: ${account_admin_api_key}" \
  -H "X-Api-Secret: ${account_admin_api_secret}"