delopay 0.20.0

Official Rust SDK for the DeloPay payments API
Documentation
//! The dispute model.

use serde::Deserialize;
use serde_json::Value;

use crate::core::models::common::{Currency, DisputeStage, DisputeStatus, ExternalRecordMarker};

/// Whether a processor tells DeloPay how a dispute ended.
///
/// Four states rather than a bool: `"unknown"` — we have not checked — is not
/// `"not_reported"`, and `"loss_only"` (it reports a loss and never a win) is
/// neither. Rounding that to `"reported"` would promise an outcome that never
/// comes for a dispute the merchant wins.
pub type DisputeOutcomeReporting = String;

/// A dispute as returned by the API.
#[derive(Debug, Clone, Deserialize)]
#[non_exhaustive]
pub struct DisputeResponse {
    /// Unique dispute ID.
    pub dispute_id: String,
    /// ID of the disputed payment.
    pub payment_id: String,
    /// Disputed amount (as a string, in minor units).
    pub amount: String,
    /// Three-letter ISO 4217 currency code.
    pub currency: Currency,
    /// Dispute lifecycle stage.
    pub dispute_stage: DisputeStage,
    /// Dispute status.
    pub dispute_status: DisputeStatus,
    /// Connector that reported the dispute.
    #[serde(default)]
    pub connector: Option<String>,
    /// Connector's own dispute ID.
    #[serde(default)]
    pub connector_dispute_id: Option<String>,
    /// Reason reported by the connector.
    #[serde(default)]
    pub connector_reason: Option<String>,
    /// Deadline to submit a challenge, if any.
    #[serde(default)]
    pub challenge_required_by: Option<String>,
    /// Whether this processor tells DeloPay how a dispute ended — see
    /// [`DisputeOutcomeReporting`]. `None` on a router that predates the
    /// field, which reads as `"unknown"`.
    #[serde(default)]
    pub outcome_reporting: Option<DisputeOutcomeReporting>,
    /// Shop (business profile) ID.
    #[serde(default)]
    pub profile_id: Option<String>,
    /// ISO 8601 creation timestamp.
    #[serde(default)]
    pub created_at: Option<String>,
    /// The amount the processor reported in another currency than the
    /// payment's, with the rate it was converted at.
    #[serde(default)]
    pub foreign_currency: Option<DisputeForeignCurrency>,
    /// The marker of a dispute recorded by hand rather than reported by the
    /// processor.
    #[serde(default)]
    pub external_record: Option<ExternalRecordMarker>,
    /// Whether the recorded dispute has not been looked at yet.
    #[serde(default)]
    pub external_record_unread: bool,
    /// Any additional response fields not modeled above.
    #[serde(flatten)]
    pub extra: serde_json::Map<String, Value>,
}

/// A dispute amount the processor reported in a foreign currency.
#[derive(Debug, Clone, Deserialize)]
#[non_exhaustive]
pub struct DisputeForeignCurrency {
    /// The amount the processor reported, in minor units of `currency`.
    pub amount: i64,
    /// The currency the processor reported.
    pub currency: Currency,
    /// Payment-currency major units per major unit of `currency`, as a
    /// decimal string, kept exact.
    pub exchange_rate: String,
    /// Where the rate came from: `"provider"` or `"reference"`.
    pub exchange_rate_source: String,
    /// ISO 8601 time the rate was taken or last corrected.
    pub exchange_rate_at: String,
    /// The settled amount, once it was reconciled.
    #[serde(default)]
    pub reconciliation: Option<DisputeReconciliation>,
    /// Any additional response fields not modeled above.
    #[serde(flatten)]
    pub extra: serde_json::Map<String, Value>,
}

/// The settled amount of a foreign-currency dispute.
#[derive(Debug, Clone, Deserialize)]
#[non_exhaustive]
pub struct DisputeReconciliation {
    /// The settled amount in minor units of the payment currency.
    pub amount: i64,
    /// ISO 8601 time it was recorded.
    pub reconciled_at: String,
    /// The user who recorded it.
    pub reconciled_by: String,
    /// Why, when given.
    #[serde(default)]
    pub reason: Option<String>,
    /// Any additional response fields not modeled above.
    #[serde(flatten)]
    pub extra: serde_json::Map<String, Value>,
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn dispute_response_decodes_foreign_currency_and_external_records() {
        let dispute: DisputeResponse = serde_json::from_str(
            r#"{"dispute_id":"dp_1","payment_id":"pay_1","amount":"1000","currency":"EUR",
                "dispute_stage":"dispute","dispute_status":"dispute_opened",
                "foreign_currency":{"amount":1100,"currency":"USD","exchange_rate":"0.9090909",
                    "exchange_rate_source":"provider","exchange_rate_at":"2026-09-01T00:00:00Z",
                    "reconciliation":{"amount":1000,"reconciled_at":"2026-09-02T00:00:00Z",
                        "reconciled_by":"usr_1"}},
                "external_record_unread":true}"#,
        )
        .unwrap();
        let foreign = dispute.foreign_currency.as_ref().unwrap();
        // The rate stays a string: exact, never rounded through a float.
        assert_eq!(foreign.exchange_rate, "0.9090909");
        assert_eq!(foreign.reconciliation.as_ref().unwrap().amount, 1000);
        assert!(dispute.external_record_unread);
        assert!(dispute.external_record.is_none());
    }
}