Historical Transaction Uploads

Overview

Kard supports bulk file-based ingestion of historical transactions for issuers onboarding new users or backfilling historical data after enrollment. Instead of submitting historical transactions one user at a time via the per-user upload API, you can upload a single file containing historical transactions for many users at once. Kard processes the file asynchronously and notifies you via webhook when processing is complete.

This guide covers how to request a presigned upload URL, prepare and upload your transaction file, and interpret the webhook notification you’ll receive once processing is complete.

Key Concepts

Transaction Types

Each line in the file describes a single historical transaction. Two transaction types are supported — pick the one that matches your data source.

File Format

Transaction files use JSONL format — one JSON object per line, with no wrapping array or commas between lines. Files can be plain text or gzip-compressed; Kard auto-detects the format. A single upload supports files up to 5 GB.

Processing Model

The flow is asynchronous and mirrors Kard’s daily Bulk Transaction Upload API:

1. Request an upload URL. Call the file uploads endpoint to receive a presigned S3 URL.
2. Upload the file. Send your JSONL file directly to S3 using the presigned URL.
3. Kard processes the file. Each line is validated and accepted records are forwarded to historical transaction storage.
4. Receive a completion webhook. Once processing finishes, Kard sends a fileProcessingResult notification with a download link to a results file containing any per-line errors.

Implementation

Step 1: Request a Presigned Upload URL

Call the file uploads endpoint to receive one presigned S3 URL per file you intend to upload. You may request up to 10 URLs in a single call — one per file.

POST /v2/issuers/{{organizationId}}/transactions/uploads

Request body:

1
{
2
  "data": [
3
    {
4
      "type": "historicalTransactionsFile",
5
      "attributes": {
6
        "filename": "historical_transactions_2024-10-15.jsonl"
7
      }
8
    }
9
  ]
10
}

Response (201 OK):

1
{
2
  "data": [
3
    {
4
      "type": "historicalTransactionsFile",
5
      "id": "2Rk3pHqLm9vNwXs1TyBf0Jc4dE",
6
      "attributes": {
7
        "url": "https://s3.amazonaws.com/kard-uploads/...",
8
        "expiresIn": 900
9
      }
10
    }
11
  ]
12
}

Step 2: Prepare Your Transaction File

Each line in the file is a single JSON object representing one transaction. Choose the transaction type that matches your data source.

type: historicalTransaction

Use this type if you have card-linked transaction data with merchant and card metadata.

Example line (formatted across multiple lines for readability — in your .jsonl file each transaction must be on a single line):

1
{
2
  "id": "309rjfoincor3icno3rind093cdow3jciwjdwcm",
3
  "type": "historicalTransaction",
4
  "attributes": {
5
    "userId": "6FHt5b6Fnp0qdomMEy5AN6PXcSJIeX69",
6
    "transactionId": "2467de37-cbdc-416d-a359-75de87bfffb0",
7
    "status": "APPROVED",
8
    "amount": 1000,
9
    "subtotal": 800,
10
    "currency": "USD",
11
    "direction": "DEBIT",
12
    "paymentType": "CARD",
13
    "description": "ADVANCEAUTO",
14
    "description2": "ADVANCEAUTO",
15
    "mcc": "1234",
16
    "cardBIN": "123456",
17
    "cardLastFour": "4321",
18
    "cardNetwork": "VISA",
19
    "authorizationDate": "2021-07-02T17:47:06Z",
20
    "authorizationCode": "123456",
21
    "retrievalReferenceNumber": "100804333919",
22
    "acquirerReferenceNumber": "1234567890123456789012345678",
23
    "systemTraceAuditNumber": "333828",
24
    "merchant": {
25
      "id": "12345678901234567",
26
      "name": "ADVANCEAUTO",
27
      "addrStreet": "125 Main St",
28
      "addrCity": "Philadelphia",
29
      "addrState": "PA",
30
      "addrZipcode": "19147",
31
      "addrCountry": "United States",
32
      "latitude": "37.9419429",
33
      "longitude": "-73.1446869",
34
      "storeId": "12345"
35
    }
36
  }
37
}

Field reference:

merchant object:

type: coreHistoricalTransaction

Use this type if you operate on a core banking system that lacks card or merchant detail. This type mirrors the relationship between coreTransaction and transaction in the daily ingestion flow.

Example line:

1
{
2
  "id": "a1b2c3d4e5f6g7h8i9j0",
3
  "type": "coreHistoricalTransaction",
4
  "attributes": {
5
    "userId": "6FHt5b6Fnp0qdomMEy5AN6PXcSJIeX69",
6
    "transactionId": "2467de37-cbdc-416d-a359-75de87bfffb0",
7
    "amount": 1000,
8
    "currency": "USD",
9
    "description": "ADVANCEAUTO",
10
    "direction": "DEBIT",
11
    "status": "SETTLED",
12
    "settledDate": "2021-07-02T17:47:06Z",
13
    "authorizationDate": "2021-07-02T17:47:06Z",
14
    "financialInstitutionId": "First National Bank",
15
    "cardLastFours": ["4321", "8765"]
16
  }
17
}

Field reference:

Step 3: Upload the File

Once you have a presigned URL, upload your file using a standard HTTP PUT. The file is sent directly to Kard’s secure storage.

Plain text:

PUT {{presignedUrl}}
Content-Type: application/octet-stream
<binary file content>

Gzip-compressed:

PUT {{presignedUrl}}
Content-Type: application/gzip
<gzip-compressed file content>

A 201 response means the upload succeeded and Kard has begun processing the file.

Step 4: Receive the Completion Webhook

Once Kard finishes processing your file, a single fileProcessingResult notification is sent to your configured webhook URL. The notification contains a presigned download URL pointing to a results file in Kard’s S3 bucket.

To configure webhook subscriptions, see the Create Subscription API.

Example payload:

1
{
2
  "data": {
3
    "type": "fileProcessingResult",
4
    "id": "c94a93a7-beb9-4e58-960c-2c812f849398",
5
    "attributes": {
6
      "fileName": "historical_transactions_2024-10-15.jsonl",
7
      "sentAt": "2025-03-09T21:56:23Z",
8
      "lastModified": "2025-03-19T21:56:23Z",
9
      "downloadUrl": "https://s3.amazonaws.com/kard-results/xyz789/results.json?<signed-params>"
10
    }
11
  }
12
}

Step 5: Download and Interpret the Results File

Use the downloadUrl from the notification to fetch the results file via a standard HTTP GET. The presigned URL expires after a set period — download promptly.

The results file lists any per-line errors encountered during ingestion. A successful ingestion with no errors will return a single success message with an empty errors array.

Example results file:

1
{
2
  "data": {
3
    "type": "fileProcessingResult",
4
    "id": "c94a93a7-beb9-4e58-960c-2c812f849398",
5
    "attributes": {
6
      "fileType": "historicalTransactionsFile",
7
      "fileName": "historical_transactions_2024-10-15.jsonl",
8
      "fileId": "xyz789"
9
    }
10
  },
11
  "errors": [
12
    {
13
      "status": "400",
14
      "title": "Invalid Request",
15
      "detail": "Invalid request: .userId should be a string",
16
      "id": "txn-123"
17
    }
18
  ]
19
}

If errors is empty, the file processed cleanly. Otherwise, use errors[].detail and errors[].id to correlate failures back to specific lines in your original file, then remediate and re-submit any failed transactions in a new file.

Best Practices

• Use gzip compression for large files. For files with millions of rows, compression significantly reduces upload time and bandwidth.
• Use consistent user identifiers. The userId on each line must match the user identifier you use elsewhere in your Kard integration so transactions are attributed correctly.
• Validate locally before uploading. Ensure each line is valid JSON and conforms to the schema for the type you’re sending. Invalid lines are reported in the results file but the rest of the file still processes.
• Use the presigned URL exactly as returned. Do not modify the URL, query parameters, or method.
• Request a new URL if yours expires. Presigned URLs are valid for 15 minutes. If your upload takes longer to prepare, simply request another one.