payrail 0.1.5

Provider-neutral Rust payments facade for Stripe, PayPal, and Mobile Money
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150

use crate::{IdempotencyKey, Money, PaymentProvider, PaymentStatus, ProviderReference};

/// Refund request.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct RefundRequest {
    /// Provider to route the refund to.
    pub provider: PaymentProvider,
    /// Provider payment reference.
    pub provider_reference: ProviderReference,
    /// Required idempotency key for retry-safe refund creation.
    pub idempotency_key: IdempotencyKey,
    /// Optional partial refund amount.
    pub amount: Option<Money>,
    /// Optional reason.
    pub reason: Option<String>,
}

/// Capture request.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct CaptureRequest {
    /// Provider to route the capture to.
    pub provider: PaymentProvider,
    /// Provider payment reference.
    pub provider_reference: ProviderReference,
    /// Required idempotency key for retry-safe capture.
    pub idempotency_key: IdempotencyKey,
}

/// Refund response.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct RefundResponse {
    /// Provider handling the refund.
    pub provider: PaymentProvider,
    /// Provider refund reference.
    pub provider_reference: ProviderReference,
    /// Normalized status after refund.
    pub status: PaymentStatus,
}

impl RefundResponse {
    /// Returns the provider handling the refund.
    #[inline]
    #[must_use]
    pub const fn provider(&self) -> &PaymentProvider {
        &self.provider
    }

    /// Returns the provider refund reference.
    #[inline]
    #[must_use]
    pub const fn provider_reference(&self) -> &ProviderReference {
        &self.provider_reference
    }

    /// Returns the normalized refund status.
    #[inline]
    #[must_use]
    pub const fn status(&self) -> PaymentStatus {
        self.status
    }
}

/// Capture response.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct CaptureResponse {
    /// Provider handling the capture.
    pub provider: PaymentProvider,
    /// Provider payment reference.
    pub provider_reference: ProviderReference,
    /// Normalized status after capture.
    pub status: PaymentStatus,
}

impl CaptureResponse {
    /// Returns the provider handling the capture.
    #[inline]
    #[must_use]
    pub const fn provider(&self) -> &PaymentProvider {
        &self.provider
    }

    /// Returns the provider payment reference.
    #[inline]
    #[must_use]
    pub const fn provider_reference(&self) -> &ProviderReference {
        &self.provider_reference
    }

    /// Returns the normalized capture status.
    #[inline]
    #[must_use]
    pub const fn status(&self) -> PaymentStatus {
        self.status
    }
}

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

    #[test]
    fn write_requests_carry_idempotency_keys() {
        let key = IdempotencyKey::new("ORDER-1:refund").expect("key should be valid");
        let refund = RefundRequest {
            provider: PaymentProvider::Stripe,
            provider_reference: ProviderReference::new("pi_123")
                .expect("reference should be valid"),
            idempotency_key: key.clone(),
            amount: None,
            reason: None,
        };
        let capture = CaptureRequest {
            provider: PaymentProvider::PayPal,
            provider_reference: ProviderReference::new("ORDER-1")
                .expect("reference should be valid"),
            idempotency_key: IdempotencyKey::new("ORDER-1:capture").expect("key should be valid"),
        };

        assert_eq!(refund.idempotency_key, key);
        assert_eq!(capture.provider, PaymentProvider::PayPal);
    }

    #[test]
    fn refund_response_accessors_return_normalized_fields() {
        let response = RefundResponse {
            provider: PaymentProvider::Stripe,
            provider_reference: ProviderReference::new("re_123")
                .expect("reference should be valid"),
            status: PaymentStatus::Refunded,
        };

        assert_eq!(response.provider(), &PaymentProvider::Stripe);
        assert_eq!(response.provider_reference().as_str(), "re_123");
        assert_eq!(response.status(), PaymentStatus::Refunded);
    }

    #[test]
    fn capture_response_accessors_return_normalized_fields() {
        let response = CaptureResponse {
            provider: PaymentProvider::PayPal,
            provider_reference: ProviderReference::new("ORDER-1")
                .expect("reference should be valid"),
            status: PaymentStatus::Succeeded,
        };

        assert_eq!(response.provider(), &PaymentProvider::PayPal);
        assert_eq!(response.provider_reference().as_str(), "ORDER-1");
        assert_eq!(response.status(), PaymentStatus::Succeeded);
    }
}