delopay 0.20.0

Official Rust SDK for the DeloPay payments API
Documentation
//! The webhook delivery event model.

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

/// A webhook delivery event as returned by the API.
///
/// Only the common fields are modeled; the full payload is preserved in
/// [`extra`](EventResponse::extra).
#[derive(Debug, Clone, Deserialize)]
#[non_exhaustive]
pub struct EventResponse {
    /// Unique event ID.
    #[serde(default)]
    pub event_id: Option<String>,
    /// Merchant account the event belongs to.
    #[serde(default)]
    pub merchant_id: Option<String>,
    /// Shop (business profile) the event belongs to.
    #[serde(default)]
    pub profile_id: Option<String>,
    /// Event type identifier, e.g. `"payment_succeeded"` — see [`EventType`].
    #[serde(default)]
    pub event_type: Option<String>,
    /// Event class, e.g. `"payments"`, `"refunds"`, `"subscriptions"`.
    #[serde(default)]
    pub event_class: Option<String>,
    /// The object this event is about: the payment, refund, dispute, mandate,
    /// payout or subscription id.
    #[serde(default)]
    pub object_id: Option<String>,
    /// The event's first delivery attempt.
    #[serde(default)]
    pub initial_attempt_id: Option<String>,
    /// What kind of delivery this row is — see [`WebhookDeliveryAttempt`].
    /// `"manual_trigger"` marks an event a person fired by hand, whose payload
    /// is an assertion rather than an observation.
    #[serde(default)]
    pub delivery_attempt: Option<WebhookDeliveryAttempt>,
    /// Whether the event was ultimately delivered, by any of its attempts.
    #[serde(default)]
    pub is_delivery_successful: Option<bool>,
    /// Whether this attempt itself was delivered: `true` when the endpoint
    /// answered 2xx to this one attempt.
    #[serde(default)]
    pub attempt_delivered: Option<bool>,
    /// Why delivery stopped for good, when it has: `"endpoint_rejected"`,
    /// `"retries_exhausted"` or `"no_webhook_url"`. `None` while the event is
    /// still being retried.
    #[serde(default)]
    pub delivery_terminal_reason: Option<String>,
    /// Which environment the event was raised in.
    #[serde(default)]
    pub test_mode: Option<bool>,
    /// ISO 8601 creation timestamp.
    #[serde(default)]
    pub created: Option<String>,
    /// Any additional fields not modeled above.
    #[serde(flatten)]
    pub extra: serde_json::Map<String, Value>,
}

/// What kind of delivery a webhook row records: `"initial_attempt"`,
/// `"automatic_retry"`, `"manual_retry"` or `"manual_trigger"`.
pub type WebhookDeliveryAttempt = String;

/// The event types the API raises.
///
/// Payments and refunds: `"payment_succeeded"`, `"payment_failed"`,
/// `"payment_processing"`, `"payment_cancelled"`,
/// `"payment_cancelled_post_capture"`, `"payment_authorized"`,
/// `"payment_partially_authorized"`, `"payment_captured"`,
/// `"payment_expired"`, `"action_required"`, `"refund_succeeded"`,
/// `"refund_failed"`.
///
/// Disputes, mandates and payouts: `"dispute_opened"`, `"dispute_expired"`,
/// `"dispute_accepted"`, `"dispute_cancelled"`, `"dispute_challenged"`,
/// `"dispute_won"`, `"dispute_lost"`, `"mandate_active"`,
/// `"mandate_revoked"`, `"payout_success"`, `"payout_failed"`,
/// `"payout_initiated"`, `"payout_processing"`, `"payout_cancelled"`,
/// `"payout_expired"`, `"payout_reversed"`.
///
/// Subscriptions: `"invoice_paid"`, plus the lifecycle types —
/// `"subscription_created"`, `"subscription_active"`,
/// `"subscription_past_due"`, `"subscription_paused"`,
/// `"subscription_resumed"`, `"subscription_cancelled"`,
/// `"subscription_expired"` and `"invoice_payment_failed"` — which carry a
/// [`LifecycleWebhook`](crate::core::models::subscription::LifecycleWebhook)
/// snapshot rather than an invoice.
pub type EventType = String;

/// The event types a manual fire accepts: the twelve payment and refund types
/// listed on [`EventType`].
///
/// A dispute, mandate, payout or subscription event has no status a manual
/// fire could assert, and the endpoint rejects it.
pub type ManualTriggerEventType = String;

/// A page of webhook events.
///
/// The wire envelope is `{ "events": [...], "total_count": n }` — it is not the
/// `data`-keyed envelope the rest of the API uses.
#[derive(Debug, Clone, Deserialize)]
#[non_exhaustive]
pub struct EventListResponse {
    /// The page of events.
    #[serde(default = "Vec::new")]
    pub events: Vec<EventResponse>,
    /// How many events match the filter in total.
    #[serde(default)]
    pub total_count: Option<i64>,
    /// Any additional envelope fields not modeled above.
    #[serde(flatten)]
    pub extra: serde_json::Map<String, Value>,
}

/// One event with the request and response bodies of its delivery.
#[derive(Debug, Clone, Deserialize)]
#[non_exhaustive]
pub struct EventDetailResponse {
    /// The event itself.
    #[serde(flatten)]
    pub event: EventResponse,
    /// What was sent to the merchant's endpoint.
    #[serde(default)]
    pub request: Option<Value>,
    /// What the endpoint answered.
    #[serde(default)]
    pub response: Option<Value>,
    /// Set when the request and response bodies were withheld because the
    /// reader's role hides the processor or payment method the webhook is
    /// about; today `"payment_visibility"`. The request body is then empty
    /// and the response body absent.
    #[serde(default)]
    pub withheld: Option<String>,
}

/// What a manual fire did, returned to the operator who fired it.
#[derive(Debug, Clone, Deserialize)]
#[non_exhaustive]
pub struct EventManualTriggerResponse {
    /// The event that was fired, with its delivery request and response.
    #[serde(flatten)]
    pub event: EventDetailResponse,
    /// The status the object actually held when the event was fired, as
    /// DeloPay records it. `None` when the object carries no status DeloPay
    /// could read.
    #[serde(default)]
    pub object_status: Option<String>,
    /// `true` when the payload's forced status differs from
    /// [`object_status`](Self::object_status) — the merchant has now been told
    /// something DeloPay's own records contradict.
    #[serde(default)]
    pub status_overridden: Option<bool>,
}

/// A delivery-attempt shape no route answers.
///
/// `Events::list_delivery_attempts` answers [`EventDetailResponse`]s; this
/// type is kept so code naming it still compiles.
#[derive(Debug, Clone, Deserialize)]
#[non_exhaustive]
pub struct EventDeliveryAttemptResponse {
    /// Unique identifier for this delivery attempt.
    #[serde(default)]
    pub attempt_id: Option<String>,
    /// Delivery status, e.g. `"success"`, `"failed"`.
    #[serde(default)]
    pub status: Option<String>,
    /// ISO 8601 timestamp of the attempt.
    #[serde(default)]
    pub created_at: Option<String>,
    /// HTTP status code your endpoint returned, when a response was received.
    #[serde(default)]
    pub response_status_code: Option<i64>,
    /// Response headers your endpoint returned.
    #[serde(default)]
    pub response_headers: Option<Value>,
    /// Response body your endpoint returned (may be truncated server-side).
    #[serde(default)]
    pub response_body: Option<String>,
    /// Delivery error, when the attempt failed before an HTTP response.
    #[serde(default)]
    pub error_message: Option<String>,
    /// Any additional fields not modeled above.
    #[serde(flatten)]
    pub extra: serde_json::Map<String, Value>,
}