razorpay-api
An async, typed Rust client for the Razorpay payments API.
This crate is a typed wrapper over Razorpay's HTTP API: it turns POST /v1/orders
into client.orders().create(params).await? without losing type safety or error
detail.
[]
= "0.1"
= { = "1", = ["rt-multi-thread", "macros"] }
The package is razorpay-api; the import path is razorpay_api (Cargo converts
hyphens to underscores).
Quick start
use ;
use CreateOrderParams;
async
The payment flow
A complete integration is four steps, and step 3 is not optional:
- Create an order server-side with
client.orders().create(). - Open Checkout in the browser with that order id. The customer pays.
- Verify the signature Checkout posts back. The browser is attacker-controlled — without this, anyone can POST a fabricated "payment succeeded" and receive goods for free.
- Handle webhooks for asynchronous updates.
use verify_payment_signature;
// These three arrive from the browser after Checkout completes.
verify_payment_signature?;
// Only now is it safe to mark the order as paid.
Webhooks: pass the raw body
The signature is computed over the exact bytes Razorpay sent. Deserializing and re-serializing changes key order and whitespace, producing a different digest that never matches. This is the single most common webhook integration bug.
use WebhookEvent;
// `raw_body` must be the unparsed request body, read as a string first.
let event = parse_verified?;
match event
parse_verified verifies before parsing and cannot be used in the wrong order.
Money is always an integer
Every amount is an i64 in the currency's smallest unit — paise for INR, so ₹1
is 100. Floating point is never used: 0.1 + 0.2 != 0.3 in binary floating point,
and on money that is a reconciliation bug you cannot work around.
Authorized is not captured
An Authorized payment is not money in your account — the funds are only held.
Razorpay auto-refunds uncaptured payments after a window, so a store that never
calls capture appears to work in testing and silently refunds every order days
later.
let payment = client.payments.fetch.await?;
if !payment.is_captured
You only need this if the order used manual_capture() or your account defaults to
manual capture; otherwise Razorpay captures for you.
Resources
| Resource | Accessor | Operations |
|---|---|---|
| Orders | client.orders() |
create, fetch, all, edit, fetch_payments |
| Payments | client.payments() |
fetch, all, capture, edit, refund, refunds |
| Refunds | client.refunds() |
fetch, all, edit |
| Customers | client.customers() |
create, fetch, all, edit, tokens, fetch_token, delete_token |
| Cards | client.cards() |
fetch |
| Items | client.items() |
create, fetch, all, edit, delete |
| Plans | client.plans() |
create, fetch, all |
| Subscriptions | client.subscriptions() |
create, fetch, all, cancel, pause, resume, edit, invoices |
| Invoices | client.invoices() |
create, fetch, all, issue, cancel, edit, delete, notify_by |
| Payment links | client.payment_links() |
create, fetch, all, cancel, notify_by |
Every list endpoint takes ListOptions and returns Collection<T>:
use ListOptions;
let page = client.orders.all.await?;
for order in &page
Errors
Every call returns Result<T, RazorpayError>. The variants are deliberately
distinct so retry logic can be written correctly:
| Variant | Meaning | Retryable |
|---|---|---|
Http |
Request never landed (DNS, TLS, timeout) | Usually |
Api |
Razorpay returned a structured error | Only on 5xx / 429 |
UnexpectedStatus |
Non-2xx with no error envelope | Only on 5xx |
Decode |
Response was not the expected shape | Never |
SignatureMismatch |
Signature did not verify | Never — treat as forgery |
InvalidUrl |
Path could not be joined onto the base URL | Never |
RazorpayError::is_retryable() encodes that table. Note it reports whether the
server might answer differently, not whether the call is safe to repeat —
retrying a POST /orders that succeeded but timed out creates a duplicate order.
The Api variant carries a boxed ApiError preserving all six fields Razorpay
documents (code, description, field, source, step, reason) plus the HTTP
status. Match on code, not on description, which Razorpay may reword:
match client.orders.create.await
Boxing keeps RazorpayError at 32 bytes, so the common success path does not carry
the weight of the error type.
Forward compatibility
Razorpay adds enum values and event types without a version bump. Every enum here
carries an Unknown fallback and optional fields are defaulted, so a new status
arriving in production degrades to Unknown rather than breaking a working
integration with a decode error.
Examples
Runnable examples in examples/:
Interactive demo dashboard
The demo-ui feature adds a small Axum web dashboard with
one card per API operation across every resource — orders, payments, refunds,
customers, cards, items, plans, subscriptions, invoices, and payment links (51
operations in total). Each card sends the real request through this crate and
shows the raw JSON response.
# open http://127.0.0.1:4000
On load, the page seeds real test-mode data — a customer, item, order, plan, subscription, invoice, and payment link — and prefills every card that needs one of those ids, so most cards work with a single click on "Send" instead of making you hunt for an id from an earlier response first. A "Re-seed" button reruns this if you want fresh ids.
The page also has a Live checkout panel that opens Razorpay's real Checkout
popup against the seeded order — this is the actual browser flow a real
integration follows, not a simulation. Pay with the
test card
4111 1111 1111 1111 (any future expiry, any CVV) and Checkout hands back a
payment id and signature. The page sends both to the server, which verifies the
signature with this crate's verify_payment_signature before trusting anything
the browser said — the same check a real integration is required to make — and
only then fetches and displays the payment. Once verified, the payment id
auto-fills the fetch/capture/edit/refund cards under Payments, which until
then are blank (Razorpay has no server-side "just create a paid payment"
endpoint, even in test mode, so completing a real Checkout is the only way to get
one). Card, token, and standalone refund ids still need to be pasted in manually,
since they come from that same real payment's card_id / saved-token / refund
response rather than anything this page can produce on its own.
It talks to Razorpay's real test-mode API — use test keys, not live ones. The
feature pulls in axum and tokio's full runtime, so it is off by default and
does not affect normal builds of the crate.
Testing
Tests run offline against a wiremock server with
fixtures copied from Razorpay's docs — no API keys, no network, deterministic. The
base_url is overridable via with_base_url, which is what makes that possible.
TLS
Uses rustls with default-features = false, so there is no OpenSSL dependency and
no build failures in Docker, Alpine, or cross-compilation.
Not yet implemented
Settlements, Transfers/Route, Virtual Accounts, QR codes, Disputes, Documents, and OAuth token exchange. Documents needs multipart upload and OAuth targets a different host with a different auth flow, so neither fits the current request path.
There is no blocking API and no built-in retry. For blocking use, wrap a call in
tokio::runtime::Runtime::block_on. Retry is omitted deliberately: safe retry of
writes needs idempotency keys, and getting it wrong charges customers twice.
License
MIT OR Apache-2.0.