SagaPay Rust SDK
Rust SDK for SagaPay - the world's first free, non-custodial blockchain payment gateway service provider. This library enables Rust developers to seamlessly integrate cryptocurrency payments without holding customer funds. With enterprise-grade security and zero transaction fees, SagaPay empowers merchants to accept crypto payments across multiple blockchains while maintaining full control of their digital assets.
Features
- Deposit address generation
- Withdrawal processing
- Transaction status checking
- Wallet balance fetching
- Webhook notifications (IPN) with signature checking and server-side verification
- Multi-chain support (ERC20, BEP20, TRC20, POLYGON, SOLANA)
- Custom UDF field support
- Non-custodial architecture
- Async support with tokio
Installation
Add this to your Cargo.toml:
[]
= "0.2.0"
= { = "1", = ["full"] }
The crate is published and imported as sagapay.
Requires Rust 1.85 or newer (edition 2024).
Quick Start
use ;
async
API Reference
Create Deposit
let deposit = client.create_deposit.await?;
Create Withdrawal
let withdrawal = client.create_withdrawal.await?;
Check Transaction Status
// By address
let status = client.check_transaction_status.await?;
// By transaction ID
let status = client.check_transaction_status.await?;
TransactionType is the lowercase form used by this query (deposit / withdrawal).
Deposit items carry confirmations, withdrawal items carry fee and processed_at.
Fetch Wallet Balance
// Token balance
let balance = client.fetch_wallet_balance.await?;
// Native coin balance - pass None to omit the contract address
let native = client.fetch_wallet_balance.await?;
The response's contract_address is "0" for native coins. Here token carries
only symbol, name and decimals, so token.network_type and
token.contract_address are None - check_transaction_status fills them in.
Verify an IPN
use ;
let result = client.verify_ipn.await?;
if result.verified
The API key and secret are read from the client Config and sent in the request
body - /verify-ipn is the one endpoint that takes no auth headers.
Handling Webhooks (IPN)
SagaPay sends webhook notifications to your specified ipnUrl when transaction statuses change. Use the WebhookHandler to parse and (optionally) authenticate them:
use ;
use HashMap;
// In your webhook endpoint handler:
async
If you also want a lower level entry point, handler.process_webhook(&body, signature)
takes the signature as an Option<&str>.
Signature
Signed notifications carry this header:
X-Sagapay-Signature: sha256=<hex HMAC-SHA256 of the exact raw request body>
The key is the platform-issued IPN secret, not your API secret (SagaPay stores
only a hash of the API secret, so it can never be the signing key). Verify
against the raw bytes you received - re-serializing the JSON changes the digest.
The handler accepts both the sha256=-prefixed form and a bare hex digest, and
compares in constant time.
Delivery guarantees
Notifications are delivered at least once, so the same payload can arrive
more than once. Treat the payload id as an idempotency key and make your
handler safe to run twice.
Webhook Payload Format
When SagaPay sends a webhook to your endpoint, it will include the following payload:
typeis uppercase (DEPOSITorWITHDRAWAL) and maps toIpnType. This is distinct from the lowercaseTransactionTypeused bycheck_transaction_status.statusisCOMPLETED- the only status currently notified.networkTypeis one ofERC20,BEP20,TRC20,POLYGON,SOLANA.udfandtxHashmay benull.
Error Handling
The SDK provides a comprehensive error handling system using the thiserror crate:
match client.create_deposit.await
ApiError::message is the human readable text from the response body, which the
API returns as { "error": "..." }.
License
This SDK is released under the MIT License.
Support
For questions or support, please contact support@sagapay.net or visit https://sagapay.net.