Skip to main content

razorpay_api/
lib.rs

1//! An async, typed Rust client for the [Razorpay](https://razorpay.com) API.
2//!
3//! This crate is a typed wrapper over Razorpay's HTTP API: it turns
4//! `POST /v1/orders` into [`client.orders().create(params)`](RazorpayClient::orders)
5//! without losing type safety or error detail.
6//!
7//! # Quick start
8//!
9//! ```no_run
10//! use razorpay_api::{RazorpayClient, RazorpayError};
11//! use razorpay_api::resources::CreateOrderParams;
12//!
13//! # async fn demo() -> Result<(), RazorpayError> {
14//! // Construct once at startup and share it — the client pools connections.
15//! let client = RazorpayClient::new(
16//!     std::env::var("RAZORPAY_KEY_ID").unwrap(),
17//!     std::env::var("RAZORPAY_KEY_SECRET").unwrap(),
18//! );
19//!
20//! // Amounts are in the smallest currency unit — 50_000 paise is ₹500.
21//! let order = client
22//!     .orders()
23//!     .create(CreateOrderParams::new(50_000, "INR").receipt("rcpt#1"))
24//!     .await?;
25//!
26//! println!("open Checkout with {}", order.id);
27//! # Ok(())
28//! # }
29//! ```
30//!
31//! # The payment flow
32//!
33//! A complete integration has four steps, and **step 3 is not optional**:
34//!
35//! 1. **Create an order** server-side with [`orders().create()`](resources::orders::OrdersClient::create).
36//! 2. **Open Checkout** in the browser with that order id. The customer pays.
37//! 3. **Verify the signature** Checkout posts back, with
38//!    [`verify_payment_signature`](signature::verify_payment_signature). The browser
39//!    is attacker-controlled; without this, anyone can claim a payment succeeded.
40//! 4. **Handle the webhook** for asynchronous updates, verifying it with
41//!    [`WebhookEvent::parse_verified`](resources::webhooks::WebhookEvent::parse_verified).
42//!
43//! ```no_run
44//! use razorpay_api::signature::verify_payment_signature;
45//! # fn handle(order_id: &str, payment_id: &str, signature: &str, secret: &str)
46//! # -> Result<(), razorpay_api::RazorpayError> {
47//! // These three values arrive from the browser after Checkout completes.
48//! verify_payment_signature(order_id, payment_id, signature, secret)?;
49//! // Only now is it safe to mark the order as paid.
50//! # Ok(())
51//! # }
52//! ```
53//!
54//! # Money is always an integer
55//!
56//! Every amount in this crate is an [`i64`] in the currency's **smallest unit** —
57//! paise for INR, so ₹1 is `100`. Floating point is never used: `0.1 + 0.2 != 0.3`
58//! in binary floating point, and on money that is a reconciliation bug users cannot
59//! work around.
60//!
61//! # Forward compatibility
62//!
63//! Razorpay adds enum values and event types without a version bump. Every enum
64//! here carries an `Unknown` fallback and every optional field is `#[serde(default)]`,
65//! so a new status arriving in production degrades to `Unknown` instead of failing
66//! to decode and breaking a working integration.
67//!
68//! # Errors
69//!
70//! Every call returns [`RazorpayError`]. The variants are deliberately distinct for
71//! retry logic: [`Http`](RazorpayError::Http) means the request never landed and is
72//! usually retryable, while [`Decode`](RazorpayError::Decode) means Razorpay
73//! answered with something unexpected and never is. See [`RazorpayError::is_retryable`].
74//!
75//! # Available resources
76//!
77//! [Orders](resources::orders), [Payments](resources::payments),
78//! [Refunds](resources::refunds), [Customers](resources::customers),
79//! [Tokens](resources::tokens), [Cards](resources::cards), [Items](resources::items),
80//! [Plans](resources::plans), [Subscriptions](resources::subscriptions),
81//! [Invoices](resources::invoices), [Payment Links](resources::payment_links), and
82//! [Webhooks](resources::webhooks).
83
84#![warn(missing_docs)]
85#![warn(rustdoc::broken_intra_doc_links)]
86
87mod client;
88mod error;
89pub mod resources;
90mod util;
91
92/// HMAC-SHA256 verification for payments and webhooks.
93///
94/// See [`verify_payment_signature`](crate::signature::verify_payment_signature)
95/// for the Checkout callback and
96/// [`verify_webhook_signature`](crate::signature::verify_webhook_signature) for
97/// incoming webhooks.
98pub mod signature {
99    pub use crate::util::signature::{
100        compute_signature, verify_payment_signature, verify_signature, verify_webhook_signature,
101    };
102}
103
104pub use client::{AuthMethod, RazorpayClient};
105pub use error::{ApiError, RazorpayError};
106pub use util::pagination::{Collection, ListOptions};