delopay 0.7.0

Official Rust SDK for the DeloPay payments API
Documentation
//! Buyer-side checkout models: the rail catalogs the hosted checkout renders,
//! the vault handshake that captures a card without it touching this process,
//! and the checkout-event receipt.
//!
//! These belong to the `/payment-link/*` surface, which a buyer's browser can
//! reach with a payment's client secret — see
//! [`crate::CheckoutSession`].

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

/// One rail the buyer can pick, from a vendor catalog.
///
/// `payment_method`, `payment_method_type` and `payment_method_data` are
/// echoed **verbatim** on the confirm call. Never derive them from
/// [`category`](Self::category): the mapping is not one-to-one, and guessing
/// it produces a confirm the connector rejects.
#[derive(Debug, Clone, Deserialize)]
#[non_exhaustive]
pub struct CheckoutRail {
    /// Vendor code. The wire field is `type`.
    #[serde(rename = "type")]
    pub rail_type: String,
    /// Buyer-facing name of the rail.
    pub display_name: String,
    /// Tile grouping: `card_redirect`, `wallet`, `bank_transfer`,
    /// `bank_redirect`, `voucher`, `gift_card`, `reward` or `cash`.
    pub category: String,
    /// Payment method to send on confirm.
    pub payment_method: String,
    /// Payment method type to send on confirm.
    pub payment_method_type: String,
    /// Pre-built `payment_method_data` body to echo on confirm; merge the
    /// buyer's `billing` into it.
    #[serde(default)]
    pub payment_method_data: Value,
    /// Minimum accepted amount, minor units of the catalog's currency.
    #[serde(default)]
    pub pmin: Option<i64>,
    /// Maximum accepted amount, minor units of the catalog's currency.
    #[serde(default)]
    pub pmax: Option<i64>,
    /// Country to forward for country-pinned vendors. `None` for universal
    /// rails, where the buyer's billing country is the right value.
    #[serde(default)]
    pub pinned_country: Option<String>,
    /// Sanitised inline SVG for the tile icon, when the merchant set one.
    /// e-Payouts only.
    #[serde(default)]
    pub icon_svg: Option<String>,
    /// Any additional response fields not modeled above.
    #[serde(flatten)]
    pub extra: serde_json::Map<String, Value>,
}

/// The Paysepro rail catalog for one country.
#[derive(Debug, Clone, Deserialize)]
#[non_exhaustive]
pub struct PayseproMethodsResponse {
    /// The country the catalog was built for.
    pub country: String,
    /// Currency the amounts in [`methods`](Self::methods) are denominated in.
    pub currency: String,
    /// The rails, in display order.
    #[serde(default)]
    pub methods: Vec<CheckoutRail>,
    /// Any additional response fields not modeled above.
    #[serde(flatten)]
    pub extra: serde_json::Map<String, Value>,
}

/// The e-Payouts rail catalog for one country.
#[derive(Debug, Clone, Deserialize)]
#[non_exhaustive]
pub struct EpayoutsMethodsResponse {
    /// The country the catalog was built for.
    pub country: String,
    /// Currency the amounts in [`methods`](Self::methods) are denominated in.
    pub currency: String,
    /// The rails, in display order.
    #[serde(default)]
    pub methods: Vec<CheckoutRail>,
    /// Lowercase ISO 3166-1 alpha-2 codes of every country the catalog can
    /// mint some method for — what the pane's country picker offers.
    #[serde(default)]
    pub supported_countries: Vec<String>,
    /// Any additional response fields not modeled above.
    #[serde(flatten)]
    pub extra: serde_json::Map<String, Value>,
}

/// Receipt for a recorded buyer-side checkout event.
#[derive(Debug, Clone, Deserialize)]
#[non_exhaustive]
pub struct RecordCheckoutEventResponse {
    /// `false` when the event was deduplicated or the per-payment cap was
    /// reached. Informational — a checkout must not branch on it.
    pub recorded: bool,
    /// Any additional response fields not modeled above.
    #[serde(flatten)]
    pub extra: serde_json::Map<String, Value>,
}

/// What a checkout page needs to stand up a VGS Collect form.
#[derive(Debug, Clone, Deserialize)]
#[non_exhaustive]
pub struct VaultCollectSessionResponse {
    /// VGS tenant id (`tnt…`), the first argument to `VGSCollect.create`.
    pub vault_id: String,
    /// `sandbox` or `live`, the second argument to `VGSCollect.create`.
    pub environment: String,
    /// Inbound route the Collect form posts through, when one is configured.
    #[serde(default)]
    pub route_id: Option<String>,
    /// Write-only bearer token for `form.createAliases({ access_token })`.
    pub access_token: String,
    /// Remaining lifetime in seconds.
    pub expires_in: i64,
    /// Any additional response fields not modeled above.
    #[serde(flatten)]
    pub extra: serde_json::Map<String, Value>,
}

/// The registered vault card, plus the one-shot token that pays with it.
#[derive(Debug, Clone, Deserialize)]
#[non_exhaustive]
pub struct VaultPaymentMethodResponse {
    /// `None` for a guest checkout, which stores no payment method.
    #[serde(default)]
    pub payment_method_id: Option<String>,
    /// Last four of the format-preserving alias — the real card's last four.
    pub last4: String,
    /// Card network, when the vault could determine it.
    #[serde(default)]
    pub card_network: Option<String>,
    /// One-shot spendable token: send it on confirm as `payment_token`,
    /// alongside `payment_method: "card"`.
    pub payment_token: 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 a_rail_reads_its_vendor_code_from_the_wire_field_type() {
        let rail: CheckoutRail = serde_json::from_str(
            r#"{"type":"ideal","display_name":"iDEAL","category":"bank_redirect",
                "payment_method":"bank_redirect","payment_method_type":"ideal",
                "payment_method_data":{"bank_redirect":{"ideal":{}}},"pmin":100}"#,
        )
        .unwrap();
        // The field is `type` on the wire and `rail_type` in Rust; a missing
        // rename would fail the decode outright.
        assert_eq!(rail.rail_type, "ideal");
        assert_eq!(rail.payment_method_type, "ideal");
        assert_eq!(rail.pmin, Some(100));
        assert_eq!(rail.pinned_country, None);
        assert!(rail.payment_method_data["bank_redirect"]["ideal"].is_object());
    }

    #[test]
    fn epayouts_carries_the_country_list_paysepro_does_not() {
        let response: EpayoutsMethodsResponse = serde_json::from_str(
            r#"{"country":"de","currency":"EUR","methods":[],
                "supported_countries":["de","fr"]}"#,
        )
        .unwrap();
        assert_eq!(response.supported_countries, ["de", "fr"]);
    }

    #[test]
    fn a_guest_vault_registration_has_no_payment_method_id() {
        let response: VaultPaymentMethodResponse = serde_json::from_str(
            r#"{"last4":"4242","payment_token":"tok_1","card_network":"Visa"}"#,
        )
        .unwrap();
        assert_eq!(response.payment_method_id, None);
        assert_eq!(response.payment_token, "tok_1");
    }
}