Immersve Docs
Github X

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.

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-card-pay-1-2",
    "type": "confirmed",
    "createdAt": "2026-04-05T10:00:05Z"
  },
  "fundingSourceInteraction": {
    "id": "fsi-card-pay-1",
    "type": "payment",
    "status": "confirmed",
    "createdAt": "2026-04-05T10:00:00Z",
    "accountId": "cardholder-789",
    "fundingSource": {
      "id": "fs-card-xyz",
      "fundingChannelId": "fc-binance-1"
    },
    "amount": { "value": "30.00", "currency": "USDC" },
    "relatedTransaction": { "type": "payment", "id": "pay-001" }
  }
}
  1. Funding Source Report Line Item
{
  "event": {
    "id": "fs-card-xyz-42",
    "type": "balance-decrease",
    "createdAt": "2026-04-05T10:00:05Z",
    "interactionEventId": "fsi-card-pay-1-2",
    "amount": { "value": "30.00", "currency": "USDC" }
  },
  "fundingSource": {
    "id": "fs-card-xyz",
    "createdAt": "2026-03-01T12:00:00Z",
    "externalId": "card-xyz-wallet",
    "accountId": "cardholder-789",
    "fundingChannel": {
      "id": "fc-binance-1",
      "name": "binance-usdc-1"
    },
    "purpose": "card-funding",
    "mode": "deposit",
    "strategy": "custodial",
    "partnerAccountId": "partner-acc-123",
    "balance": { "value": "70.00", "currency": "USDC" }
  }
}

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": {
    "type": "auth-accepted",
    "createdAt": "2026-04-20T03:10:02.938Z"
  },
  "payment": {
    "id": "abc123",
    "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"
    }
  }
}

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.id links to Payment id.

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:

Terminal window
curl -L 'https://app.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}"