payment_kit/
lib.rs

1//! # 💳 payment_kit
2//!
3//! A powerful and extensible payment toolkit for Rust — featuring core data models, robust error handling,
4//! flexible status flows, and seamless integration into any payment system.
5//!
6//! Designed to be embedded in services that communicate with third-party payment providers,
7//! the `payment_kit` ensures consistency and testability across environments.
8//! 
9//! ---
10//!
11//! ## ✨ Features
12//!
13//! - Pluggable `PaymentGateway` trait for easy integration with third-party providers
14//! - Strongly-typed `PaymentRequest` and `PaymentResponse` structures
15//! - Input validation via the `ValidatableRequest` trait as an option
16//! - Rich, structured error types with `PaymentError`
17//! - Built-in mock gateway for testing and development
18//! - Support for various payment instruments (e.g., credit cards, e-wallets, bank transfers).
19//! 
20//! ---
21//! 
22//! ## 🚀 Quick Start
23//!
24//! ```rust
25//! use payment_kit::models::{PaymentInstrument, PaymentRequest, PaymentResponse, RefundResponse};
26//! use payment_kit::processor::PaymentProcessor;
27//! use payment_kit::utils::validation::ValidatableRequest;
28//! use payment_kit::error::PaymentError;
29//! use payment_kit::gateway::PaymentGateway;
30//! use payment_kit::status::PaymentStatus;
31//! 
32//! pub struct MockPaymentGateway;
33//! 
34//! impl PaymentGateway for MockPaymentGateway {
35//! 
36//!     fn create_payment(&self, req: PaymentRequest) -> Result<PaymentResponse, PaymentError> {
37//!         if req.amount == 0 || req.order_id.contains("fail") {
38//!             return Err(PaymentError::InvalidRequest("Simulated failure".into()));
39//!         }
40//! 
41//!         Ok(PaymentResponse {
42//!             transaction_id: format!("mock_txn_{}", req.order_id),
43//!             amount: req.amount,
44//!             payment_instrument: req.payment_instrument,
45//!             status: PaymentStatus::Pending,
46//!             redirect_url: Some("https://mock.payment/redirect".to_string()),
47//!         })
48//!     }
49//!     fn check_status(&self, transaction_id: &str) -> Result<PaymentStatus, PaymentError> {
50//!         if transaction_id.contains("fail") {
51//!             Err(PaymentError::ProcessingError("Transaction failed".into()))
52//!         } else {
53//!             Ok(PaymentStatus::Success)
54//!         }
55//!     }
56//! 
57//!     fn refund(&self, transaction_id: &str) -> Result<RefundResponse, PaymentError> {
58//!         if transaction_id.contains("notfound") {
59//!             Err(PaymentError::InvalidRequest("Transaction ID not found".into()))
60//!         } else {
61//!             Ok(RefundResponse {
62//!                 refund_id: format!("refund_{}", transaction_id),
63//!                 status: PaymentStatus::Refunded,
64//!                 transaction_id: transaction_id.to_string(),
65//!                 refunded: true,
66//!             })
67//!         }
68//!     }
69//! }
70//!
71//! fn main() -> Result<(), PaymentError> {
72//!     let gateway = MockPaymentGateway;
73//!     let processor = PaymentProcessor::new(&gateway);
74//!
75//!     let request = PaymentRequest {
76//!         order_id: "INV-001".to_string(),
77//!         amount: 100_000,
78//!         currency: "IDR".to_string(),
79//!         payment_instrument: PaymentInstrument::EWallet {
80//!             provider: "OVO".to_string(),
81//!         },
82//!         customer_id: Some("cust-123".to_string()),
83//!         description: Some("Order payment".to_string()),
84//!         metadata: None,
85//!     };
86//!
87//!     if let Err(e) = request.validate() {
88//!         eprintln!("Validation failed: {}", e);
89//!     }
90//!
91//!     let response = processor.create_payment(request);
92//!     match response {
93//!         Ok(res) => {
94//!             println!("Payment successful: {:#?}", res);
95//!         }
96//!         Err(err) => {
97//!             eprintln!("Payment failed: {}", err);
98//!         }
99//!     }
100//!
101//!     Ok(())
102//! }
103//! ```
104//!
105//! ---
106//!
107//! ## 📄 License
108//!
109//! Licensed under the [Apache-2.0 license](http://www.apache.org/licenses/LICENSE-2.0.txt)
110//!
111//! ---
112//!
113//! ## 👨 Author
114//!
115//! Jerry Maheswara <jerrymaheswara@gmail.com>
116//!
117//! ---
118//!
119//! ## ❤️ Built with Love in Rust
120//!
121//! This project is built with ❤️ using **Rust** — a systems programming language that is safe, fast, and concurrent.  
122//! Rust is the perfect choice for building reliable and efficient applications.
123//!
124//! ---
125//!
126//! ## 🤝 Contributing
127//!
128//! Pull requests, issues, and feedback are welcome!  
129//! If you find this crate useful, give it a ⭐ and share it with others in the Rustacean community.
130//!
131//! ---
132
133
134/// Data models used for representing payment requests, responses, refunds, and payment instruments.
135pub mod models;
136
137/// The `PaymentGateway` trait defines the interface for integrating with external payment providers.
138pub mod gateway;
139
140/// Error types representing various failure scenarios during payment processing.
141pub mod error;
142
143/// Payment status definitions representing the lifecycle of a transaction.
144pub mod status;
145
146/// Optional utility helpers.
147pub mod utils;
148
149/// The `PaymentProcessor` struct coordinates the interaction between your application and a payment gateway.
150pub mod processor;
payment_kit/lib.rs

payment_kit/
lib.rs
