Rust SDK
bitmomo is the official Rust SDK. It needs Rust 1.88 or later and provides an async client on reqwest (rustls by default) that runs on any Tokio runtime. The webhook helpers also work without the HTTP client.
cargo add bitmomoConfigure a client
Section titled “Configure a client”use std::time::Duration;use bitmomo::Client;
let client = Client::builder(std::env::var("BITMOMO_API_KEY")?, "https://api.dev.bitmomo.app") .timeout(Duration::from_secs(10)) .build()?;Client::new(api_key, base_url) builds one with the defaults. A Client is cheap to clone; clones share one connection pool.
- The base URL is required. It must be an
https://origin with no path, query, fragment or credentials. Plainhttp://is accepted only forlocalhost. - The client never follows redirects, so your key is never sent to another host.
- Prefer the platform’s TLS stack? Turn off default features and enable
clientandnative-tls.
Create a payment
Section titled “Create a payment”use bitmomo::{new_idempotency_key, CreatePaymentParams, Decimal};
let params = CreatePaymentParams::new(Decimal::new("100.00")?, "USDT_TRC20") // Ghana cedis .order_id("order_1001") .idempotency_key(new_idempotency_key()); // store this with the order firstlet payment = client.create_payment(¶ms).await?;println!("{} {} {} {}", payment.id, payment.crypto_amount, payment.deposit_address, payment.qr_code_data);Methods
Section titled “Methods”| Method | Endpoint | Scope |
|---|---|---|
create_payment(&CreatePaymentParams) |
POST /gateway/payments |
payments:write |
get_payment(id) |
GET /gateway/payments/{id} |
payments:read |
list_payments(&ListPaymentsParams) |
GET /gateway/payments |
payments:read |
get_balances() |
GET /gateway/balances |
payments:read |
request_payout(&PayoutParams) |
POST /gateway/payouts |
payouts:write |
get_webhook_config() |
GET /gateway/webhooks/config |
webhooks:read |
update_webhook_config(&UpdateWebhookConfigParams) |
PUT /gateway/webhooks/config |
webhooks:write |
delete_webhook_config() |
DELETE /gateway/webhooks/config |
webhooks:write |
rotate_webhook_secret() |
POST /gateway/webhooks/config/rotate |
webhooks:write |
create_payment_link(&CreatePaymentLinkParams) |
POST /gateway/payment-links |
payments:write |
list_payment_links() |
GET /gateway/payment-links |
payments:read |
get_payment_link(id) |
GET /gateway/payment-links/{id} |
payments:read |
get_payment_status(id) |
GET /payments/{id}/status |
none (public) |
get_rates() |
GET /rates |
none (public) |
Every method is async and returns Result<_, bitmomo::Error>. Response types use the API’s field names; optional fields are Option. Statuses are a PaymentStatus enum, and unknown values from a newer API are kept in PaymentStatus::Other instead of failing.
request_payout requires an idempotency key (PayoutParams::new(amount, key)); create it with bitmomo::new_idempotency_key(), save it, and reuse it on retries. Without one, the SDK refuses to send the request.
Webhook helpers
Section titled “Webhook helpers”| Helper | Use |
|---|---|
bitmomo::webhooks::verify_event(raw_body, signature, &VerifyOptions) |
Full verification: signature, freshness and signed headers. Returns Ok(Envelope) or Err(RejectReason). |
bitmomo::webhooks::verify_signature(raw_body, signature, secret) |
Signature check only. Prefer verify_event. |
bitmomo::webhooks::DeliveryDedupeCache |
In-memory, thread-safe duplicate filter: seen(delivery_id) returns true for a repeat (default() keeps entries 24 hours). Use a database for anything that matters. |
use bitmomo::webhooks::{verify_event, VerifyOptions, WebhookSecret};
let opts = VerifyOptions::new(vec![WebhookSecret::new(1, std::env::var("BITMOMO_WEBHOOK_SECRET")?)]) .timestamp(headers.get("X-Webhook-Timestamp")) .key_version(headers.get("X-Webhook-Key-Version"));match verify_event(&raw_body, signature, &opts) { Ok(envelope) => { /* store the event durably under envelope.delivery_id, then reply 2xx */ } Err(reason) => { /* reply 400; reason prints as e.g. "stale-timestamp" */ }}Only need webhook verification? Depend on bitmomo = { version = "0.1", default-features = false } to leave out the HTTP client. In axum, take the body as axum::body::Bytes so you get the raw bytes. See Webhooks for the full flow.
Errors and retries
Section titled “Errors and retries”Every failure is a bitmomo::Error with status, code, message, request_id and retriable. status is 0 when no response arrived (NETWORK_ERROR, with the cause in source()) or the response broke the contract (SCHEMA_ERROR). Reads retry up to 3 times in total on 429 and 5xx (Client::builder(..).max_retries(n)), honouring Retry-After up to 60 seconds. Writes are never retried automatically; see Errors.
Money values
Section titled “Money values”Money is bitmomo::Decimal, an exact decimal string such as "100.00"; it never passes through f64. Convert it with your decimal crate, for example rust_decimal::Decimal::from_str(d.as_str()). On balances, use the *_exact fields; the f64 fields are for display only.
- Crate: crates.io/crates/bitmomo
- API documentation: docs.rs/bitmomo
- SDK changelog