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
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
//! Payments — the money side of an [`Order`](crate::resources::orders::Order).
//!
//! The critical distinction in this module is **authorized vs captured**: see
//! [`PaymentsClient::capture`].
use serde::{Deserialize, Serialize};
use crate::client::RazorpayClient;
use crate::error::RazorpayError;
use crate::resources::common::{Notes, NotesUpdate, PaymentMethod};
use crate::resources::refunds::{CreateRefundParams, Refund};
use crate::util::pagination::{Collection, ListOptions};
/// Lifecycle state of a [`Payment`].
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum PaymentStatus {
/// Created but not yet acted on.
Created,
/// Funds are held but **not** settled to you — see [`PaymentsClient::capture`].
Authorized,
/// Funds captured; this is the only status that means you have been paid.
Captured,
/// Fully or partially refunded.
Refunded,
/// The payment failed.
Failed,
/// A status this crate does not model yet.
#[serde(other)]
Unknown,
}
/// How much of a payment has been refunded.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum RefundStatus {
/// No refund issued.
Null,
/// Some of the amount refunded.
Partial,
/// The whole amount refunded.
Full,
/// A status this crate does not model yet.
#[serde(other)]
Unknown,
}
/// A payment returned by the API.
#[derive(Debug, Clone, PartialEq, Deserialize)]
pub struct Payment {
/// Unique identifier, e.g. `pay_29QQoUBi66xm2f`.
pub id: String,
/// Always `"payment"`.
#[serde(default)]
pub entity: String,
/// Amount in the smallest currency unit (paise for INR).
pub amount: i64,
/// ISO 4217 currency code.
pub currency: String,
/// Current lifecycle state.
pub status: PaymentStatus,
/// The order this payment was made against, when it came through an order.
#[serde(default)]
pub order_id: Option<String>,
/// Invoice this payment settles, if any.
#[serde(default)]
pub invoice_id: Option<String>,
/// Whether this payment is on an international card.
#[serde(default)]
pub international: bool,
/// How the customer paid.
#[serde(default)]
pub method: Option<PaymentMethod>,
/// Amount refunded so far, in the smallest unit.
#[serde(default)]
pub amount_refunded: i64,
/// Whether the payment is partly or wholly refunded.
#[serde(default)]
pub refund_status: Option<RefundStatus>,
/// Whether the payment has been captured.
#[serde(default)]
pub captured: bool,
/// Free-text description shown to the customer.
#[serde(default)]
pub description: Option<String>,
/// Card id, when [`method`](Self::method) is [`PaymentMethod::Card`].
#[serde(default)]
pub card_id: Option<String>,
/// Bank code, for netbanking payments.
#[serde(default)]
pub bank: Option<String>,
/// Wallet name, for wallet payments.
#[serde(default)]
pub wallet: Option<String>,
/// VPA, for UPI payments.
#[serde(default)]
pub vpa: Option<String>,
/// Customer email, when collected.
#[serde(default)]
pub email: Option<String>,
/// Customer contact number, when collected.
#[serde(default)]
pub contact: Option<String>,
/// Customer id, when the payment is tied to a saved customer.
#[serde(default)]
pub customer_id: Option<String>,
/// Token id, for payments on a saved instrument.
#[serde(default)]
pub token_id: Option<String>,
/// Razorpay's fee for this payment, in the smallest unit.
#[serde(default)]
pub fee: Option<i64>,
/// Tax charged on the fee, in the smallest unit.
#[serde(default)]
pub tax: Option<i64>,
/// Gateway error code, when the payment failed.
#[serde(default)]
pub error_code: Option<String>,
/// Human-readable failure description.
#[serde(default)]
pub error_description: Option<String>,
/// Failure reason, e.g. `payment_failed`.
#[serde(default)]
pub error_reason: Option<String>,
/// Which side caused the failure, e.g. `customer`.
#[serde(default)]
pub error_source: Option<String>,
/// Which step failed, e.g. `payment_authentication`.
#[serde(default)]
pub error_step: Option<String>,
/// Your metadata.
#[serde(default)]
pub notes: Notes,
/// Creation time as a Unix timestamp in seconds.
pub created_at: i64,
}
impl Payment {
/// Whether this payment represents money you will actually receive.
///
/// An [`Authorized`](PaymentStatus::Authorized) payment is *not* settled —
/// this returns `false` for it.
pub fn is_captured(&self) -> bool {
matches!(self.status, PaymentStatus::Captured)
}
}
/// Body for [`PaymentsClient::capture`].
#[derive(Debug, Clone, PartialEq, Serialize)]
pub struct CaptureParams {
/// Amount to capture, in the smallest unit. Must equal the authorized amount.
pub amount: i64,
/// ISO 4217 currency code.
pub currency: String,
}
/// Payment endpoints. Obtain one from [`RazorpayClient::payments`].
pub struct PaymentsClient<'a> {
pub(crate) client: &'a RazorpayClient,
}
impl<'a> PaymentsClient<'a> {
/// Fetch one payment by id — `GET /v1/payments/{id}`.
pub async fn fetch(&self, id: &str) -> Result<Payment, RazorpayError> {
self.client.get::<(), _>(&format!("payments/{id}"), None).await
}
/// List payments — `GET /v1/payments`.
pub async fn all(&self, options: ListOptions) -> Result<Collection<Payment>, RazorpayError> {
self.client.get("payments", Some(&options)).await
}
/// Capture an authorized payment — `POST /v1/payments/{id}/capture`.
///
/// # An authorized payment is not money in your account
///
/// When a payment is [`Authorized`](PaymentStatus::Authorized), the funds are
/// only *held* on the customer's instrument. Razorpay **auto-refunds
/// uncaptured payments** after a configurable window — typically days. A store
/// that never calls this appears to work in testing and then silently refunds
/// every order.
///
/// You only need this if the order was created with
/// [`manual_capture`](crate::resources::orders::CreateOrderParams::manual_capture)
/// or your account defaults to manual capture; otherwise Razorpay captures for
/// you.
///
/// `amount` must match the authorized amount exactly, or Razorpay rejects it.
///
/// # Examples
///
/// ```no_run
/// # use razorpay_api::{RazorpayClient, RazorpayError};
/// # async fn demo(client: RazorpayClient) -> Result<(), RazorpayError> {
/// let payment = client.payments().fetch("pay_123").await?;
/// if !payment.is_captured() {
/// client.payments().capture("pay_123", payment.amount, &payment.currency).await?;
/// }
/// # Ok(())
/// # }
/// ```
pub async fn capture(
&self,
id: &str,
amount: i64,
currency: &str,
) -> Result<Payment, RazorpayError> {
let body = CaptureParams {
amount,
currency: currency.to_string(),
};
self.client
.post(&format!("payments/{id}/capture"), Some(&body))
.await
}
/// Replace a payment's notes — `PATCH /v1/payments/{id}`.
pub async fn edit(&self, id: &str, notes: Notes) -> Result<Payment, RazorpayError> {
self.client
.patch(&format!("payments/{id}"), Some(&NotesUpdate::new(notes)))
.await
}
/// Refund a payment — `POST /v1/payments/{id}/refund`.
///
/// Omitting the amount on [`CreateRefundParams`] refunds the payment in full.
///
/// # Examples
///
/// ```no_run
/// # use razorpay_api::{RazorpayClient, RazorpayError};
/// # use razorpay_api::resources::CreateRefundParams;
/// # async fn demo(client: RazorpayClient) -> Result<(), RazorpayError> {
/// // Full refund.
/// client.payments().refund("pay_123", CreateRefundParams::full()).await?;
///
/// // Partial refund of ₹100.
/// client.payments().refund("pay_123", CreateRefundParams::partial(10_000)).await?;
/// # Ok(())
/// # }
/// ```
pub async fn refund(
&self,
id: &str,
params: CreateRefundParams,
) -> Result<Refund, RazorpayError> {
self.client
.post(&format!("payments/{id}/refund"), Some(¶ms))
.await
}
/// List refunds issued against a payment — `GET /v1/payments/{id}/refunds`.
pub async fn refunds(
&self,
id: &str,
options: ListOptions,
) -> Result<Collection<Refund>, RazorpayError> {
self.client
.get(&format!("payments/{id}/refunds"), Some(&options))
.await
}
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn authorized_is_not_captured() {
let payment: Payment = serde_json::from_str(
r#"{"id":"pay_1","amount":100,"currency":"INR","status":"authorized","created_at":1}"#,
)
.unwrap();
assert!(!payment.is_captured());
}
#[test]
fn unknown_method_and_status_decode_to_fallback() {
let payment: Payment = serde_json::from_str(
r#"{"id":"pay_1","amount":1,"currency":"INR","status":"new_status",
"method":"crypto","created_at":1}"#,
)
.unwrap();
assert_eq!(payment.status, PaymentStatus::Unknown);
assert_eq!(payment.method, Some(PaymentMethod::Unknown));
}
#[test]
fn sparse_payment_decodes() {
// Failed payments omit most fields; decoding must not require them.
let payment: Payment = serde_json::from_str(
r#"{"id":"pay_1","amount":1,"currency":"INR","status":"failed","created_at":1}"#,
)
.unwrap();
assert_eq!(payment.amount_refunded, 0);
assert!(payment.notes.is_empty());
}
}