delopay 0.20.0

Official Rust SDK for the DeloPay payments API
Documentation
//! Per-payment reads beside the payment itself: its buyer risk evaluations,
//! the agent signal of its checkout client, its product lines, the routing
//! decision of each attempt, and its integration-test mark.

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

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

/// A payment's buyer risk evaluations, newest first (at most 50). A payment
/// never scored answers an empty list.
#[derive(Debug, Clone, Deserialize)]
#[non_exhaustive]
pub struct BuyerRiskEvaluationsResponse {
    /// The evaluations, newest first.
    #[serde(default)]
    pub evaluations: Vec<BuyerRiskEvaluation>,
    /// Any additional response fields not modeled above.
    #[serde(flatten)]
    pub extra: serde_json::Map<String, Value>,
}

/// One buyer risk evaluation: made at every confirm about to reach a
/// processor.
#[derive(Debug, Clone, Deserialize)]
#[non_exhaustive]
pub struct BuyerRiskEvaluation {
    /// 0 to 100: the sum of the points of the signals that fired, capped.
    pub score: i32,
    /// `"low"`, `"elevated"`, `"high"` or `"critical"`.
    pub band: String,
    /// What the model asks for this band: `"allow"`, `"flag"`,
    /// `"require_three_ds"` or `"refuse"`.
    pub action: String,
    /// What was done. Differs from `action` for a merchant-initiated payment
    /// and where 3-D Secure could not be asked for.
    pub applied_action: String,
    /// Why `applied_action` differs from `action`: `merchant_initiated` or
    /// `three_ds_unsupported`. `None` when they agree.
    #[serde(default)]
    pub action_reason: Option<String>,
    /// The signals that fired, in the model's order.
    #[serde(default)]
    pub reasons: Vec<BuyerRiskReason>,
    /// The setting revisions the model was resolved from, outermost first.
    pub model_version: String,
    /// A payment the merchant initiated (`off_session`): scored without
    /// device signals and never refused or sent to 3-D Secure.
    pub merchant_initiated: bool,
    /// ISO 8601 time of the evaluation.
    pub evaluated_at: String,
    /// Any additional response fields not modeled above.
    #[serde(flatten)]
    pub extra: serde_json::Map<String, Value>,
}

/// One signal that fired in a buyer risk evaluation.
#[derive(Debug, Clone, Deserialize)]
#[non_exhaustive]
pub struct BuyerRiskReason {
    /// The signal, e.g. `"device_ips"` or `"network_vpn"`.
    pub signal: String,
    /// Points it added: the signal's weight.
    pub points: i32,
    /// The value observed.
    pub value: i32,
    /// The threshold it reached.
    pub threshold: i32,
    /// Machine facts about the observation (a source, a country code), when
    /// there are any.
    #[serde(default)]
    pub detail: Option<Value>,
    /// Any additional response fields not modeled above.
    #[serde(flatten)]
    pub extra: serde_json::Map<String, Value>,
}

/// What a payment's checkout client was, for AI shopping agents. The hosted
/// checkout's render and the buyer's confirm are both judged, and the
/// strongest observation is kept.
#[derive(Debug, Clone, Deserialize)]
#[non_exhaustive]
pub struct PaymentAgentSignalResponse {
    /// The payment.
    pub payment_id: String,
    /// `"verified_agent"`, `"unverified_agent"`, `"automated"` or
    /// `"browser"`.
    pub classification: String,
    /// The agent's operator, as configured, for a verified agent.
    #[serde(default)]
    pub agent_operator: Option<String>,
    /// `web_bot_auth`, `visa_trusted_agent` or `mastercard_agent_pay`, for a
    /// verified agent.
    #[serde(default)]
    pub agent_protocol: Option<String>,
    /// The key's JWK thumbprint (RFC 7638), for a verified agent.
    #[serde(default)]
    pub key_id: Option<String>,
    /// Why an agent signature did not verify, for an unverified agent: a
    /// machine key such as `expired` or `unknown_key`.
    #[serde(default)]
    pub reason: Option<String>,
    /// Where the kept observation was made: `"render"` or `"confirm"`.
    pub stage: String,
    /// ISO 8601 time of the kept observation.
    pub recorded_at: String,
    /// Any additional response fields not modeled above.
    #[serde(flatten)]
    pub extra: serde_json::Map<String, Value>,
}

/// A payment's product names and prices, frozen when the payment was
/// created.
#[derive(Debug, Clone, Deserialize)]
#[non_exhaustive]
pub struct PaymentProductLines {
    /// The payment.
    pub payment_id: String,
    /// The lines.
    #[serde(default)]
    pub lines: Vec<PaymentProductLine>,
    /// The currency the totals are in.
    #[serde(default)]
    pub currency: Option<Currency>,
    /// The sum of every line's `line_total`. `None`, not `0`, when the
    /// payment has no lines.
    #[serde(default)]
    pub lines_total: Option<i64>,
    /// `lines_total - payment.amount`, reported so no reader has to compute
    /// it.
    #[serde(default)]
    pub amount_difference: Option<i64>,
    /// The sum of the reported per-line tax amounts. `None` as soon as any
    /// line has no reported `tax_amount`.
    #[serde(default)]
    pub tax_total: Option<i64>,
    /// Any additional response fields not modeled above.
    #[serde(flatten)]
    pub extra: serde_json::Map<String, Value>,
}

/// One frozen product line of a payment.
#[derive(Debug, Clone, Deserialize)]
#[non_exhaustive]
pub struct PaymentProductLine {
    /// The line's own ID, which add-ons and components point at.
    pub id: String,
    /// The catalog product the line was attributed to. `None` on an
    /// unattributed line.
    #[serde(default)]
    pub product_id: Option<String>,
    /// Whether the line is tied to a catalog product.
    pub attributed: bool,
    /// The product's name as it read when the payment was made.
    pub name: String,
    /// The name the caller used, when it was not the product's own name.
    #[serde(default)]
    pub alias: Option<String>,
    /// Units bought.
    pub quantity: i32,
    /// The product's price at the time, in minor units of `currency`: not a
    /// share of the payment amount.
    pub unit_amount: i64,
    /// `unit_amount × quantity`.
    pub line_total: i64,
    /// The currency this line's amounts are in.
    pub currency: String,
    /// The tax rate the caller stated for this line. Never derived.
    #[serde(default)]
    pub tax_rate: Option<f64>,
    /// The tax amount the caller reported. `None` is not zero.
    #[serde(default)]
    pub tax_amount: Option<i64>,
    /// The connector's own ID for what this line was attributed through.
    #[serde(default)]
    pub connector_reference: Option<String>,
    /// `"product"`, `"addon"`, `"bundle"` or `"component"`.
    pub role: String,
    /// The line an add-on or component belongs to.
    #[serde(default)]
    pub parent_line_id: Option<String>,
    /// What refunds have credited to the line.
    #[serde(default)]
    pub refunds: Option<PaymentLineRefunds>,
    /// Whether the buyer may still change the payment's add-ons: `"open"` or
    /// `"closed"`. Set on the payment's head line only.
    #[serde(default)]
    pub addon_choice: Option<String>,
    /// `true` when the catalog product has since been deleted.
    #[serde(default)]
    pub product_deleted: Option<bool>,
    /// Any additional response fields not modeled above.
    #[serde(flatten)]
    pub extra: serde_json::Map<String, Value>,
}

/// What refunds have credited to one product line, in minor units of the
/// line's currency.
#[derive(Debug, Clone, Deserialize)]
#[non_exhaustive]
pub struct PaymentLineRefunds {
    /// Units given back by succeeded refunds.
    pub refunded_quantity: i32,
    /// Money credited to the line by succeeded refunds.
    pub refunded_amount: i64,
    /// Tax part of `refunded_amount`, as the credits stated it.
    #[serde(default)]
    pub refunded_tax_amount: Option<i64>,
    /// Units credited by refunds still in flight.
    pub pending_quantity: i32,
    /// Money credited by refunds still in flight.
    pub pending_amount: i64,
    /// Units a new refund may still credit. Never negative.
    pub refundable_quantity: i32,
    /// Money a new refund may still credit to the line. Never negative.
    pub refundable_amount: i64,
    /// Tax a new refund may still state for the line.
    #[serde(default)]
    pub refundable_tax_amount: Option<i64>,
    /// Any additional response fields not modeled above.
    #[serde(flatten)]
    pub extra: serde_json::Map<String, Value>,
}

/// How each attempt of a payment was routed.
#[derive(Debug, Clone, Deserialize)]
#[non_exhaustive]
pub struct PaymentRoutingDecisionsResponse {
    /// The payment.
    pub payment_id: String,
    /// The number of attempts returned, never the number that exist: a
    /// connector grant may have hidden some.
    pub count: i64,
    /// The attempts, each with its decision.
    #[serde(default)]
    pub attempts: Vec<RoutingDecisionAttempt>,
    /// Any additional response fields not modeled above.
    #[serde(flatten)]
    pub extra: serde_json::Map<String, Value>,
}

/// One attempt of a payment and the routing decision recorded for it.
#[derive(Debug, Clone, Deserialize)]
#[non_exhaustive]
pub struct RoutingDecisionAttempt {
    /// The attempt.
    pub attempt_id: String,
    /// The connector the attempt ran on, if it reached one.
    #[serde(default)]
    pub connector: Option<String>,
    /// The connector account the attempt ran on.
    #[serde(default)]
    pub merchant_connector_id: Option<String>,
    /// The decision. `None` is no record, not an error: attempts that never
    /// reached routing, and older attempts, have none.
    #[serde(default)]
    pub decision: Option<PaymentRoutingDecision>,
    /// Any additional response fields not modeled above.
    #[serde(flatten)]
    pub extra: serde_json::Map<String, Value>,
}

/// How the connector of one attempt was chosen.
///
/// This, not the payment's `routing_approach`, is the account of how the
/// connector was chosen: read [`decision_kind`](Self::decision_kind).
#[derive(Debug, Clone, Deserialize)]
#[non_exhaustive]
pub struct PaymentRoutingDecision {
    /// What kind of decision it was, e.g. `"rule_matched"`,
    /// `"volume_split"` or `"fallback_no_algorithm"`.
    pub decision_kind: String,
    /// The category the attempt carries in `routing_approach`, when the path
    /// stamped one.
    #[serde(default)]
    pub routing_approach: Option<String>,
    /// The active configuration consulted, when one was.
    #[serde(default)]
    pub algorithm_id: Option<String>,
    /// When the configuration content the decision was evaluated against
    /// took effect, in seconds since the Unix epoch.
    #[serde(default)]
    pub algorithm_valid_from: Option<i64>,
    /// The configuration's name during that window.
    #[serde(default)]
    pub algorithm_name: Option<String>,
    /// The configuration's 1-based version for that window.
    #[serde(default)]
    pub algorithm_version: Option<i32>,
    /// The closed version of that window. `None` for the live window.
    #[serde(default)]
    pub algorithm_version_id: Option<String>,
    /// The rule that selected the candidates.
    #[serde(default)]
    pub matched_rule_name: Option<String>,
    /// The connectors considered.
    #[serde(default)]
    pub candidates: Vec<RoutingDecisionCandidate>,
    /// The volume split drawn from, for a split decision.
    #[serde(default)]
    pub volume_split: Option<Vec<RoutingDecisionVolumeSplitEntry>>,
    /// The volume counters the rules read.
    #[serde(default)]
    pub volume_counters: Option<Vec<RoutingDecisionVolumeCounter>>,
    /// The attempt this one retried, on an auto-retry.
    #[serde(default)]
    pub retry_of_attempt_id: Option<String>,
    /// When the decision was taken, in seconds since the Unix epoch.
    pub decided_at: i64,
    /// Any additional response fields not modeled above.
    #[serde(flatten)]
    pub extra: serde_json::Map<String, Value>,
}

/// A connector a routing decision considered.
#[derive(Debug, Clone, Deserialize)]
#[non_exhaustive]
pub struct RoutingDecisionCandidate {
    /// The connector, as the routing rule names it.
    pub connector: String,
    /// The connector account, when the rule named one.
    #[serde(default)]
    pub merchant_connector_id: Option<String>,
    /// `"routed"` (the routing stage produced it) or `"fallback"` (appended
    /// from the merchant's default list).
    pub origin: String,
    /// The first filter that removed this candidate, or `None` for one that
    /// reached the connector list.
    #[serde(default)]
    pub eliminated_by: Option<String>,
    /// Any additional response fields not modeled above.
    #[serde(flatten)]
    pub extra: serde_json::Map<String, Value>,
}

/// One entry of a volume split a routing decision drew from.
#[derive(Debug, Clone, Deserialize)]
#[non_exhaustive]
pub struct RoutingDecisionVolumeSplitEntry {
    /// The connector.
    pub connector: String,
    /// The connector account.
    #[serde(default)]
    pub merchant_connector_id: Option<String>,
    /// The configured weight, as written in the rule.
    pub split: i32,
    /// Whether this entry was drawn.
    pub drawn: bool,
    /// Any additional response fields not modeled above.
    #[serde(flatten)]
    pub extra: serde_json::Map<String, Value>,
}

/// A volume counter a routing decision read.
#[derive(Debug, Clone, Deserialize)]
#[non_exhaustive]
pub struct RoutingDecisionVolumeCounter {
    /// `None` for the program-wide budget; the rule-level budget key
    /// otherwise.
    #[serde(default)]
    pub key: Option<String>,
    /// The counter's window.
    pub window: String,
    /// The counter's scope.
    pub scope: String,
    /// The currency the threshold is written in; `None` means the payment's
    /// own currency.
    #[serde(default)]
    pub currency: Option<String>,
    /// The counter, in minor units of that currency; `None` when the read
    /// yielded nothing.
    #[serde(default)]
    pub value: Option<i64>,
    /// The rules that condition on this counter.
    #[serde(default)]
    pub rules: Vec<String>,
    /// Any additional response fields not modeled above.
    #[serde(flatten)]
    pub extra: serde_json::Map<String, Value>,
}

/// A payment's integration-test mark after it was set.
#[derive(Debug, Clone, Deserialize)]
#[non_exhaustive]
pub struct PaymentIntegrationTestResponse {
    /// The payment the request was for.
    pub payment_id: String,
    /// The mark now stored on the payment.
    pub is_integration_test: bool,
    /// `false` when the payment already carried the requested mark, so
    /// nothing was written and no history entry was added.
    pub changed: bool,
    /// Any additional response fields not modeled above.
    #[serde(flatten)]
    pub extra: serde_json::Map<String, Value>,
}