juspay / juspay/hyperswitch

[TASK] Add split payment dimensions to analytics

Open
#11,623 0 comments 0 reactions 0 assignees View on GitHub
Dominant language
Rust
Stars
43.7k
Forks
5.1k
Avg merge
2d 20h
Merged PRs (30d)
205

Description

## Summary

Add support for filtering and grouping payment intent analytics by split payment attributes. This enables merchants to analyze split payments processed through Stripe Connect, Adyen Platform, and Xendit Sub-merchant.

## Goal

Enable merchants to:
- Filter analytics to show only split payments using `is_split_payment` boolean
- Group distribution charts by split payment connector (stripe, adyen, xendit)
- Track split payment volume and distribution across different connectors

## Technical Approach

### Data Flow
Payment Intent → Kafka Event → ClickHouse → Analytics API

New fields to track:
- `is_split_payment` (boolean) - Whether the payment is a split payment
- `split_payment_connector` (string) - Connector name: "stripe", "adyen", or "xendit"

### Files to Modify

**1. Kafka Events**
- `crates/router/src/services/kafka/payment_intent_event.rs`
- Add `is_split_payment: bool` and `split_payment_connector: Option` to PaymentIntentKafkaEvent struct

**2. ClickHouse Schema**
- `crates/analytics/docs/clickhouse/scripts/payment_intents.sql`
- Add columns to queue, table, and materialized view:
- `is_split_payment UInt8`
- `split_payment_connector LowCardinality(Nullable(String))`

**3. Analytics Filters**
- `crates/analytics/src/payment_intents/filters.rs`
- Add filter variants for new dimensions
- Update PaymentIntentFilterRow struct

**4. Analytics Types**
- `crates/analytics/src/payment_intents/types.rs`
- Add IsSplitPayment and SplitPaymentConnector to PaymentIntentDimensions enum
- Update PaymentIntentFilters struct and QueryFilter impl

**5. API Models**
- `crates/api_models/src/analytics/payment_intents.rs`
- Add dimensions to PaymentIntentDimensions enum
- Update PaymentIntentMetricsBucketIdentifier struct with new params
- Update new() constructor and Hash impl

**6. Metrics**
- `crates/analytics/src/payment_intents/metrics.rs`
- Add fields to PaymentIntentMetricRow
- `crates/analytics/src/payment_intents/metrics/*.rs` (13 files)
- Update all PaymentIntentMetricsBucketIdentifier::new() calls

**7. Utils**
- `crates/analytics/src/utils.rs`
- Add dimensions to get_payment_intent_dimensions() function

### API Changes

**Endpoint:** `POST /analytics/v1/payment_intents/filters`

**Request:**
```json
{
"dimensions": ["is_split_payment", "split_payment_connector"],
"filters": {
"is_split_payment": true,
"split_payment_connector": ["stripe", "adyen"]
}
}
```

### Edge Cases

- Existing payments without split data: default to false/NULL
- Partial data availability across connectors
- Filter combinations (is_split_payment + connector)

## Subtasks

- [ ] Add is_split_payment and split_payment_connector to Kafka payment_intent_event.rs
- [ ] Update ClickHouse schema (queue, table, materialized view)
- [ ] Add filter variants in payment_intents/filters.rs
- [ ] Update PaymentIntentDimensions enum in payment_intents/types.rs
- [ ] Update API models in api_models/src/analytics/payment_intents.rs
- [ ] Add fields to PaymentIntentMetricRow in metrics.rs
- [ ] Update all 13 metric files with new bucket identifier params
- [ ] Add dimensions to get_payment_intent_dimensions() in utils.rs
- [ ] Write tests for Kafka event serialization
- [ ] Write integration tests for ClickHouse schema
- [ ] Write API tests for filter endpoints

Contributor guide

Open the contributing guide

Research direction

Trace the payment intent event through crates/router/src/services/kafka/payment_intent_event.rs, the ClickHouse schema, and the analytics payment_intents filters, types, metrics, API models, and utils files listed. Review existing dimensions and bucket identifiers first, then add the two split-payment dimensions consistently across the data flow. Done means the Kafka serialization, ClickHouse schema, filter endpoint, and integration/API tests cover the new fields and filter combinations.

Written by the indexing model from the issue text.

Assessment

Tech stack
clickhouse, kafka, rust
Domain
analytics, api, backend, data-engineering, databases
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Quiet
Clarity
Clearly specified
Newbie friendliness
42/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.