use serde::Deserialize;
use serde_json::Value;
use crate::core::money::Money;
pub type SettlementPayoutStatus = String;
pub type ConnectorOwnership = String;
#[derive(Debug, Clone, Deserialize)]
#[non_exhaustive]
pub struct SettlementBucket {
#[serde(default)]
pub connector: Option<String>,
pub ownership: ConnectorOwnership,
pub currency: String,
pub gross_amount: i64,
#[serde(default)]
pub platform_fee_amount: i64,
#[serde(default)]
pub platform_fee_incomplete: bool,
pub merchant_fee_amount: i64,
pub refund_amount: i64,
pub net_to_shop: i64,
pub line_count: i64,
pub refund_count: i64,
#[serde(default)]
pub fee_percentage: Option<String>,
#[serde(default)]
pub fee_flat_amount: Option<i64>,
#[serde(flatten)]
pub extra: serde_json::Map<String, Value>,
}
impl SettlementBucket {
#[must_use]
pub fn gross(&self) -> Money {
Money::new(self.gross_amount, &self.currency)
}
#[must_use]
pub fn merchant_fee(&self) -> Money {
Money::new(self.merchant_fee_amount, &self.currency)
}
#[must_use]
pub fn refund(&self) -> Money {
Money::new(self.refund_amount, &self.currency)
}
#[must_use]
pub fn net(&self) -> Money {
Money::new(self.net_to_shop, &self.currency)
}
#[must_use]
pub fn platform_fee(&self) -> Money {
Money::new(self.platform_fee_amount, &self.currency)
}
}
#[derive(Debug, Clone, Deserialize)]
#[non_exhaustive]
pub struct FeeStatementSummary {
pub id: String,
pub merchant_id: String,
pub profile_id: String,
pub period_start: String,
pub period_end: String,
pub test_mode: bool,
pub gross_usd: i64,
#[serde(default)]
pub platform_fee_usd: i64,
pub merchant_fee_usd: i64,
pub refund_usd: i64,
pub net_to_shop_usd: i64,
pub line_count: i64,
pub refund_count: i64,
#[serde(default)]
pub fx_incomplete: bool,
#[serde(default)]
pub platform_fee_incomplete: bool,
#[serde(default)]
pub includes_backfill: bool,
pub payout_status: SettlementPayoutStatus,
#[serde(default)]
pub paid_amount_usd: i64,
#[serde(default)]
pub paid_at: Option<String>,
#[serde(default)]
pub payout_note: Option<String>,
pub generated_at: String,
#[serde(default)]
pub adjustments_usd: i64,
#[serde(default)]
pub net_after_adjustments_usd: i64,
#[serde(flatten)]
pub extra: serde_json::Map<String, Value>,
}
impl FeeStatementSummary {
#[must_use]
pub fn payable(&self) -> Money {
Money::new(self.net_after_adjustments_usd, "USD")
}
#[must_use]
pub fn gross(&self) -> Money {
Money::new(self.gross_usd, "USD")
}
#[must_use]
pub fn merchant_fee(&self) -> Money {
Money::new(self.merchant_fee_usd, "USD")
}
}
#[derive(Debug, Clone, Deserialize)]
#[non_exhaustive]
pub struct FeeStatementDetail {
#[serde(flatten)]
pub summary: FeeStatementSummary,
#[serde(default)]
pub breakdown: Vec<SettlementBucket>,
}
#[derive(Debug, Clone, Deserialize)]
#[non_exhaustive]
pub struct SettlementStatementListResponse {
#[serde(default)]
pub statements: Vec<FeeStatementSummary>,
#[serde(default)]
pub total_count: i64,
#[serde(flatten)]
pub extra: serde_json::Map<String, Value>,
}
#[derive(Debug, Clone, Deserialize)]
#[non_exhaustive]
pub struct ShopSettlementOverview {
pub profile_id: String,
#[serde(default)]
pub profile_name: Option<String>,
#[serde(default)]
pub unpaid_net_usd: i64,
#[serde(default)]
pub unpaid_statement_count: i64,
#[serde(default)]
pub current_period_net_usd: i64,
#[serde(default)]
pub current_period_merchant_fee_usd: i64,
#[serde(default)]
pub current_period_gross_usd: i64,
#[serde(default)]
pub fx_incomplete: bool,
#[serde(default)]
pub has_fee_config: bool,
#[serde(default)]
pub visible_to_shop: bool,
#[serde(flatten)]
pub extra: serde_json::Map<String, Value>,
}
#[derive(Debug, Clone, Deserialize)]
#[non_exhaustive]
pub struct SettlementOverviewResponse {
#[serde(default)]
pub shops: Vec<ShopSettlementOverview>,
#[serde(flatten)]
pub extra: serde_json::Map<String, Value>,
}
#[derive(Debug, Clone, Deserialize)]
#[non_exhaustive]
pub struct SettlementCurrentResponse {
pub period_start: String,
pub period_end: String,
pub test_mode: bool,
#[serde(default)]
pub gross_usd: i64,
#[serde(default)]
pub platform_fee_usd: i64,
#[serde(default)]
pub merchant_fee_usd: i64,
#[serde(default)]
pub refund_usd: i64,
#[serde(default)]
pub net_to_shop_usd: i64,
#[serde(default)]
pub line_count: i64,
#[serde(default)]
pub refund_count: i64,
#[serde(default)]
pub fx_incomplete: bool,
#[serde(default)]
pub platform_fee_incomplete: bool,
#[serde(default)]
pub breakdown: Vec<SettlementBucket>,
#[serde(flatten)]
pub extra: serde_json::Map<String, Value>,
}
#[derive(Debug, Clone, Deserialize)]
#[non_exhaustive]
pub struct StatementAdjustment {
pub id: String,
pub label: String,
pub amount_usd: i64,
pub created_at: String,
#[serde(flatten)]
pub extra: serde_json::Map<String, Value>,
}
impl StatementAdjustment {
#[must_use]
pub fn amount(&self) -> Money {
Money::new(self.amount_usd, "USD")
}
}
#[derive(Debug, Clone, Deserialize)]
#[non_exhaustive]
pub struct StatementAdjustmentListResponse {
#[serde(default)]
pub adjustments: Vec<StatementAdjustment>,
#[serde(flatten)]
pub extra: serde_json::Map<String, Value>,
}
#[derive(Debug, Clone, Deserialize)]
#[non_exhaustive]
pub struct SettlementLine {
pub payment_id: String,
pub attempt_id: String,
#[serde(default)]
pub connector: Option<String>,
pub connector_ownership: ConnectorOwnership,
#[serde(default)]
pub payment_method: Option<String>,
#[serde(default)]
pub payment_method_type: Option<String>,
pub currency: String,
pub gross_amount: i64,
#[serde(default)]
pub platform_fee_amount: i64,
pub merchant_fee_amount: i64,
pub net_to_shop: i64,
pub merchant_fee_source: String,
#[serde(default)]
pub platform_fee_source: Option<String>,
pub merchant_ledger_outcome: String,
pub test_mode: bool,
#[serde(default)]
pub backfilled: bool,
pub transaction_at: String,
#[serde(flatten)]
pub extra: serde_json::Map<String, Value>,
}
impl SettlementLine {
#[must_use]
pub fn gross(&self) -> Money {
Money::new(self.gross_amount, &self.currency)
}
#[must_use]
pub fn merchant_fee(&self) -> Money {
Money::new(self.merchant_fee_amount, &self.currency)
}
#[must_use]
pub fn net(&self) -> Money {
Money::new(self.net_to_shop, &self.currency)
}
}
#[derive(Debug, Clone, Deserialize)]
#[non_exhaustive]
pub struct SettlementLineListResponse {
#[serde(default)]
pub lines: Vec<SettlementLine>,
#[serde(default)]
pub total_count: i64,
#[serde(flatten)]
pub extra: serde_json::Map<String, Value>,
}
#[derive(Debug, Clone, Deserialize)]
#[non_exhaustive]
pub struct ShopFeeConfigEntry {
pub schedule_id: String,
#[serde(default)]
pub connector: Option<String>,
#[serde(default)]
pub profile_specific: bool,
pub fee_type: String,
#[serde(default)]
pub percentage_fee: Option<f64>,
#[serde(default)]
pub flat_fee_amount: Option<i64>,
#[serde(default)]
pub flat_fee_currency: Option<String>,
#[serde(default)]
pub min_fee_amount: Option<i64>,
#[serde(default)]
pub max_fee_amount: Option<i64>,
#[serde(flatten)]
pub extra: serde_json::Map<String, Value>,
}
impl ShopFeeConfigEntry {
#[must_use]
pub fn flat_fee(&self) -> Option<Money> {
match (self.flat_fee_amount, self.flat_fee_currency.as_deref()) {
(Some(amount), Some(currency)) => Some(Money::new(amount, currency)),
_ => None,
}
}
}
#[derive(Debug, Clone, Deserialize)]
#[non_exhaustive]
pub struct ShopFeeConfigResponse {
pub profile_id: String,
#[serde(default)]
pub schedules: Vec<ShopFeeConfigEntry>,
#[serde(flatten)]
pub extra: serde_json::Map<String, Value>,
}
#[derive(Debug, Clone, Deserialize)]
#[non_exhaustive]
pub struct SettlementBackfillResponse {
pub enqueued: bool,
pub job_id: String,
#[serde(flatten)]
pub extra: serde_json::Map<String, Value>,
}
#[derive(Debug, Clone, Deserialize)]
#[non_exhaustive]
pub struct ShopVisibilityResponse {
pub profile_id: String,
pub visible_to_shop: bool,
#[serde(flatten)]
pub extra: serde_json::Map<String, Value>,
}
#[cfg(test)]
mod tests {
use super::*;
const BUCKET_JSON: &str = r#"{
"connector": "stripe",
"ownership": "host",
"currency": "JPY",
"gross_amount": 1999,
"platform_fee_amount": 20,
"platform_fee_incomplete": true,
"merchant_fee_amount": 200,
"refund_amount": 0,
"net_to_shop": 1799,
"line_count": 3,
"refund_count": 0,
"fee_percentage": "10",
"fee_flat_amount": 0,
"surprise_field": 1
}"#;
#[test]
fn bucket_amounts_carry_their_own_currency() {
let bucket: SettlementBucket = serde_json::from_str(BUCKET_JSON).unwrap();
assert_eq!(bucket.gross().to_major_string().as_deref(), Some("1999"));
assert_eq!(bucket.net().to_major_string().as_deref(), Some("1799"));
assert_eq!(bucket.merchant_fee().amount, 200);
assert!(bucket.platform_fee_incomplete);
assert_eq!(bucket.extra["surprise_field"], 1);
}
#[test]
fn statement_detail_flattens_the_summary_beside_the_breakdown() {
let json = format!(
r#"{{
"id": "stmt_1",
"merchant_id": "mer_1",
"profile_id": "pro_1",
"period_start": "2026-07-01T00:00:00Z",
"period_end": "2026-08-01T00:00:00Z",
"test_mode": false,
"gross_usd": 100000,
"platform_fee_usd": 1000,
"merchant_fee_usd": 15000,
"refund_usd": 0,
"net_to_shop_usd": 85000,
"line_count": 12,
"refund_count": 0,
"payout_status": "unpaid",
"generated_at": "2026-08-01T00:20:00Z",
"adjustments_usd": 5000,
"net_after_adjustments_usd": 80000,
"breakdown": [{BUCKET_JSON}]
}}"#
);
let detail: FeeStatementDetail = serde_json::from_str(&json).unwrap();
assert_eq!(detail.summary.id, "stmt_1");
assert_eq!(detail.breakdown.len(), 1);
assert_eq!(
detail.summary.payable().to_major_string().as_deref(),
Some("800.00")
);
assert_eq!(detail.summary.net_to_shop_usd, 85000);
assert!(!detail.summary.extra.contains_key("breakdown"));
}
#[test]
fn statement_defaults_absent_flags_to_false() {
let json = r#"{
"id": "stmt_1",
"merchant_id": "mer_1",
"profile_id": "pro_1",
"period_start": "2026-07-01T00:00:00Z",
"period_end": "2026-08-01T00:00:00Z",
"test_mode": true,
"gross_usd": 0,
"platform_fee_usd": 0,
"merchant_fee_usd": 0,
"refund_usd": 0,
"net_to_shop_usd": 0,
"line_count": 0,
"refund_count": 0,
"payout_status": "unpaid",
"generated_at": "2026-08-01T00:20:00Z"
}"#;
let summary: FeeStatementSummary = serde_json::from_str(json).unwrap();
assert!(!summary.platform_fee_incomplete);
assert!(!summary.fx_incomplete);
assert_eq!(summary.adjustments_usd, 0);
}
#[test]
fn a_redacted_bucket_and_summary_still_decode() {
let bucket: SettlementBucket = serde_json::from_str(
r#"{"ownership":"shop","currency":"EUR","gross_amount":1999,
"merchant_fee_amount":200,"refund_amount":0,"net_to_shop":1799,
"line_count":1,"refund_count":0}"#,
)
.unwrap();
assert_eq!(bucket.platform_fee_amount, 0);
let summary: FeeStatementSummary = serde_json::from_str(
r#"{"id":"stmt_1","merchant_id":"mer_1","profile_id":"pro_1",
"period_start":"2026-07-01T00:00:00Z","period_end":"2026-08-01T00:00:00Z",
"test_mode":false,"gross_usd":100000,"merchant_fee_usd":15000,
"refund_usd":0,"net_to_shop_usd":85000,"line_count":12,"refund_count":0,
"payout_status":"unpaid","generated_at":"2026-08-01T00:20:00Z"}"#,
)
.unwrap();
assert_eq!(summary.platform_fee_usd, 0);
assert_eq!(summary.net_to_shop_usd, 85000);
assert_eq!(summary.merchant_fee_usd, 15000);
}
#[test]
fn adjustment_amount_keeps_its_sign() {
let json = r#"{
"id": "adj_1",
"label": "Goodwill credit",
"amount_usd": -2500,
"created_at": "2026-08-02T10:00:00Z"
}"#;
let adjustment: StatementAdjustment = serde_json::from_str(json).unwrap();
assert_eq!(
adjustment.amount().to_major_string().as_deref(),
Some("-25.00")
);
}
#[test]
fn line_redaction_is_visible_as_an_absent_source() {
let json = r#"{
"payment_id": "pay_1",
"attempt_id": "pay_1_1",
"connector_ownership": "shop",
"currency": "EUR",
"gross_amount": 1999,
"merchant_fee_amount": 200,
"net_to_shop": 1799,
"merchant_fee_source": "schedule",
"merchant_ledger_outcome": "deducted",
"test_mode": false,
"transaction_at": "2026-07-15T12:00:00Z"
}"#;
let line: SettlementLine = serde_json::from_str(json).unwrap();
assert_eq!(line.platform_fee_source, None);
assert_eq!(line.platform_fee_amount, 0);
assert_eq!(line.gross().to_major_string().as_deref(), Some("19.99"));
}
#[test]
fn flat_fee_needs_both_halves() {
let with_currency: ShopFeeConfigEntry = serde_json::from_str(
r#"{"schedule_id":"fee_1","fee_type":"merchant","flat_fee_amount":30,
"flat_fee_currency":"USD"}"#,
)
.unwrap();
assert_eq!(
with_currency
.flat_fee()
.unwrap()
.to_major_string()
.as_deref(),
Some("0.30")
);
let without_currency: ShopFeeConfigEntry = serde_json::from_str(
r#"{"schedule_id":"fee_1","fee_type":"merchant","flat_fee_amount":30}"#,
)
.unwrap();
assert_eq!(without_currency.flat_fee(), None);
}
}