delopay 0.3.0

Official Rust SDK for the DeloPay payments API
Documentation
//! Shop (business profile) models: the shop itself, its gateway connections,
//! its logo upload result and its order/revenue statistics.

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

use crate::core::models::common::Currency;

/// Charset used for the random body of a custom-format payment ID, e.g.
/// `"numeric"`, `"alphanumeric"`, `"alphanumeric_uppercase"`.
///
/// Kept as a `String` for the same reason as
/// the other open vocabularies in this crate: a closed enum would reject a
/// newly-added variant and break deserialization.
pub type PaymentIdStyle = String;

// A shop *is* a business profile, so its payment-ID format is the same object
// `ProfileResponse` carries. Defined once in `profile`, re-exported here so
// `shop::PaymentIdFormatConfig` still resolves; two definitions would let the
// two drift apart while both claiming to model one wire field.
pub use crate::core::models::profile::PaymentIdFormatConfig;

/// A shop (business profile) as returned by the API.
///
/// `Debug` is hand-written: [`payment_response_hash_key`](Self::payment_response_hash_key)
/// is a webhook signing secret and is redacted.
#[derive(Clone, Deserialize)]
#[non_exhaustive]
pub struct ShopResponse {
    /// Unique shop (business profile) ID.
    pub shop_id: String,
    /// Display name of the shop.
    pub shop_name: String,
    /// Whether the shop is active.
    pub is_active: bool,
    /// ISO 8601 creation timestamp.
    pub created_at: String,
    /// ISO 8601 last-modification timestamp.
    pub modified_at: String,

    /// URL customers are returned to after checkout.
    #[serde(default)]
    pub return_url: Option<String>,
    /// URL webhooks for this shop are delivered to.
    #[serde(default)]
    pub webhook_url: Option<String>,
    /// Project this shop is grouped under, if any.
    #[serde(default)]
    pub project_id: Option<String>,
    /// Webhook signing secret for this shop, when the API echoes it back.
    /// Outgoing webhooks are HMAC-SHA512 signed with this key, so it is
    /// redacted from `Debug` output.
    #[serde(default)]
    pub payment_response_hash_key: Option<String>,
    /// Branding and behavior overrides for the hosted checkout (open shape —
    /// see the API reference).
    #[serde(default)]
    pub payment_link_config: Option<Value>,
    /// Origins permitted to embed this shop's hosted checkout in an iframe.
    #[serde(default)]
    pub iframe_allowed_origins: Option<Vec<String>>,
    /// Custom format for generated payment IDs. Absent means default
    /// `pay_<random>` IDs.
    #[serde(default)]
    pub payment_id_format: Option<PaymentIdFormatConfig>,
    /// Any additional response fields not modeled above.
    #[serde(flatten)]
    pub extra: serde_json::Map<String, Value>,
}

// Hand-written rather than derived so the webhook signing secret cannot leak
// into logs via `{:?}`. Only its presence is reported.
impl std::fmt::Debug for ShopResponse {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.debug_struct("ShopResponse")
            .field("shop_id", &self.shop_id)
            .field("shop_name", &self.shop_name)
            .field("is_active", &self.is_active)
            .field("created_at", &self.created_at)
            .field("modified_at", &self.modified_at)
            .field("return_url", &self.return_url)
            .field("webhook_url", &self.webhook_url)
            .field("project_id", &self.project_id)
            .field(
                "payment_response_hash_key",
                &self
                    .payment_response_hash_key
                    .as_ref()
                    .map(|_| "<redacted>"),
            )
            .field("payment_link_config", &self.payment_link_config)
            .field("iframe_allowed_origins", &self.iframe_allowed_origins)
            .field("payment_id_format", &self.payment_id_format)
            .field("extra", &self.extra)
            .finish()
    }
}

/// A gateway (connector) connection on a shop.
///
/// `Debug` is hand-written: the connector credential fields are redacted.
#[derive(Clone, Deserialize)]
#[non_exhaustive]
pub struct GatewayResponse {
    /// Connector category, e.g. `"payment_processor"`.
    pub connector_type: String,
    /// Connector identifier, e.g. `"stripe"`.
    pub connector_name: String,
    /// Unique ID of this merchant connector account.
    pub merchant_connector_id: String,
    /// Shop (business profile) the connection belongs to.
    pub profile_id: String,
    /// Connection status, e.g. `"active"`.
    pub status: String,

    /// Your own label for this connection.
    #[serde(default)]
    pub connector_label: Option<String>,
    /// Connector credentials as echoed back by the API (open shape). Redacted
    /// from `Debug` output.
    #[serde(default)]
    pub connector_account_details: Option<Value>,
    /// Connector webhook details, including signing secrets (open shape).
    /// Redacted from `Debug` output.
    #[serde(default)]
    pub connector_webhook_details: Option<Value>,
    /// Payment methods enabled on this connector (open shape).
    #[serde(default)]
    pub payment_methods_enabled: Option<Vec<Value>>,
    /// Arbitrary key-value metadata.
    #[serde(default)]
    pub metadata: Option<Value>,
    /// Whether the connector runs against the PSP's test environment.
    #[serde(default)]
    pub test_mode: Option<bool>,
    /// Whether the connection is disabled.
    #[serde(default)]
    pub disabled: Option<bool>,
    /// ISO 8601 creation timestamp.
    #[serde(default)]
    pub created_at: Option<String>,
    /// Any additional response fields not modeled above.
    #[serde(flatten)]
    pub extra: serde_json::Map<String, Value>,
}

// Hand-written rather than derived: two of these fields carry PSP credentials
// and webhook signing secrets, which must never reach a log through `{:?}`.
// Only their presence is reported.
impl std::fmt::Debug for GatewayResponse {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.debug_struct("GatewayResponse")
            .field("connector_type", &self.connector_type)
            .field("connector_name", &self.connector_name)
            .field("merchant_connector_id", &self.merchant_connector_id)
            .field("profile_id", &self.profile_id)
            .field("status", &self.status)
            .field("connector_label", &self.connector_label)
            .field(
                "connector_account_details",
                &self
                    .connector_account_details
                    .as_ref()
                    .map(|_| "<redacted>"),
            )
            .field(
                "connector_webhook_details",
                &self
                    .connector_webhook_details
                    .as_ref()
                    .map(|_| "<redacted>"),
            )
            .field("payment_methods_enabled", &self.payment_methods_enabled)
            .field("metadata", &self.metadata)
            .field("test_mode", &self.test_mode)
            .field("disabled", &self.disabled)
            .field("created_at", &self.created_at)
            .field("extra", &self.extra)
            .finish()
    }
}

/// Result of uploading a shop logo.
#[derive(Debug, Clone, Deserialize)]
#[non_exhaustive]
pub struct ProfileLogoUploadResponse {
    /// Publicly-reachable HTTPS URL of the uploaded logo.
    pub logo_url: String,
    /// Any additional response fields not modeled above.
    #[serde(flatten)]
    pub extra: serde_json::Map<String, Value>,
}

/// Revenue taken in one currency. Amounts are in that currency's minor units.
#[derive(Debug, Clone, Deserialize)]
#[non_exhaustive]
pub struct CurrencyRevenue {
    /// Three-letter ISO 4217 currency code, e.g. `"EUR"`.
    pub currency: Currency,
    /// Revenue in that currency's minor units.
    pub amount_minor: i64,
    /// Number of orders taken in that currency.
    pub orders: i64,
    /// Any additional response fields not modeled above.
    #[serde(flatten)]
    pub extra: serde_json::Map<String, Value>,
}

/// Order and revenue figures for one shop, as they appear nested inside
/// [`ProjectStatsResponse`](crate::core::models::project::ProjectStatsResponse).
#[derive(Debug, Clone, Deserialize)]
#[non_exhaustive]
pub struct ShopStats {
    /// The shop these figures belong to.
    pub shop_id: String,
    /// Display name of the shop.
    pub shop_name: String,
    /// Project the shop is grouped under, or `None` when unassigned.
    #[serde(default)]
    pub project_id: Option<String>,
    /// Number of successful orders in the window.
    pub orders: i64,
    /// Raw sum of minor units across every currency, with no FX conversion —
    /// meaningless for a multi-currency shop. Use
    /// [`revenue_usd`](Self::revenue_usd) or
    /// [`revenue_by_currency`](Self::revenue_by_currency) instead.
    pub revenue: i64,
    /// FX-converted revenue in USD major units. Excludes
    /// [`unconverted_orders`](Self::unconverted_orders).
    pub revenue_usd: f64,
    /// Revenue split by the currency it was taken in.
    #[serde(default)]
    pub revenue_by_currency: Vec<CurrencyRevenue>,
    /// Orders left out of `revenue_usd` because their currency had no fresh
    /// USD rate. Non-zero means the USD figure understates reality.
    pub unconverted_orders: i64,
    /// Any additional response fields not modeled above.
    #[serde(flatten)]
    pub extra: serde_json::Map<String, Value>,
}

/// Stats for one shop, as returned by the `shops.stats` endpoint.
///
/// The same figures as [`ShopStats`], plus the window they cover.
#[derive(Debug, Clone, Deserialize)]
#[non_exhaustive]
pub struct ShopStatsResponse {
    /// The shop these figures belong to.
    pub shop_id: String,
    /// Display name of the shop.
    pub shop_name: String,
    /// Project the shop is grouped under, or `None` when unassigned.
    #[serde(default)]
    pub project_id: Option<String>,
    /// Number of successful orders in the window.
    pub orders: i64,
    /// Raw cross-currency minor-unit sum — do not display. Use
    /// [`revenue_usd`](Self::revenue_usd) or
    /// [`revenue_by_currency`](Self::revenue_by_currency).
    pub revenue: i64,
    /// FX-converted revenue in USD major units.
    pub revenue_usd: f64,
    /// Revenue split by the currency it was taken in.
    #[serde(default)]
    pub revenue_by_currency: Vec<CurrencyRevenue>,
    /// Orders left out of `revenue_usd` for want of a fresh USD rate.
    pub unconverted_orders: i64,
    /// Window the figures cover, in days. `None` for an all-time total.
    #[serde(default)]
    pub period_days: Option<i64>,
    /// Any additional response fields not modeled above.
    #[serde(flatten)]
    pub extra: serde_json::Map<String, Value>,
}