bitmomo 0.1.0

BitMomo merchant SDK: accept crypto payments and verify webhooks in Rust
Documentation

BitMomo Rust SDK

Accept crypto payments in your Rust application and verify BitMomo webhooks. Async client on reqwest (rustls by default), exact decimal money, and a webhook verifier you can use without the HTTP client.

Test money only. BitMomo currently runs on test networks. Live API keys are disabled, so nothing you do with this SDK moves real money.

Guides and the API reference: https://docs.bitmomo.app

Install

cargo add bitmomo

Rust 1.88 or newer. Use it from any Tokio runtime.

Create a payment

use bitmomo::{Client, CreatePaymentParams, Decimal};

let client = Client::new(std::env::var("BITMOMO_API_KEY")?, "https://api.dev.bitmomo.app")?;
let params = CreatePaymentParams::new(Decimal::new("150.00")?, "USDT_TRC20")
    .order_id("order-1001")
    .idempotency_key("order-1001"); // reuse the same key if you retry
let payment = client.create_payment(&params).await?;
println!("{} {} {}", payment.deposit_address, payment.crypto_amount, payment.qr_code_data);

Show the customer qr_code_data (or deposit_address and crypto_amount). Then wait for the webhook, or poll with get_payment_status and get_payment.

Verify webhooks

Verify the raw request body. Keep both secrets during the 24 hours after you rotate.

use bitmomo::webhooks::{verify_event, DeliveryDedupeCache, VerifyOptions, WebhookSecret};

let opts = VerifyOptions::new(vec![WebhookSecret::new(1, secret)])
    .timestamp(headers.get("X-Webhook-Timestamp"))
    .key_version(headers.get("X-Webhook-Key-Version"));
match verify_event(&body, signature, &opts) {
    Ok(envelope) if dedupe.seen(&envelope.delivery_id) => { /* already handled: 200 */ }
    Ok(envelope) => { /* handle the event, then 200 */ }
    Err(reason) => { /* 400; reason says why, e.g. "stale-timestamp" */ }
}

Only need webhooks? Turn off the HTTP client:

bitmomo = { version = "0.1", default-features = false }

Deliveries arrive at least once. Store processed delivery IDs durably if a duplicate would cause a second effect.

Everything the client can do

Method API
create_payment POST /api/v1/gateway/payments
get_payment GET /api/v1/gateway/payments/{id}
get_payment_status GET /api/v1/payments/{id}/status
list_payments GET /api/v1/gateway/payments
request_payout POST /api/v1/gateway/payouts
get_rates GET /api/v1/rates
get_balances GET /api/v1/gateway/balances
get_webhook_config GET /api/v1/gateway/webhooks/config
update_webhook_config PUT /api/v1/gateway/webhooks/config
rotate_webhook_secret POST /api/v1/gateway/webhooks/config/rotate
delete_webhook_config DELETE /api/v1/gateway/webhooks/config
create_payment_link POST /api/v1/gateway/payment-links
list_payment_links GET /api/v1/gateway/payment-links
get_payment_link GET /api/v1/gateway/payment-links/{id}

Each API key carries scopes. A key without the right scope gets an error with status 403.

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 automatically on 429 and 5xx, twice by default (Client::builder(..).max_retries(n)), honouring Retry-After up to 60 seconds.
  • Writes are never retried for you. Retry with the same idempotency key; request_payout refuses to send without one.
  • Redirects are refused, so your API key is never sent to another host.
  • The base URL must be an HTTPS origin (plain HTTP only for localhost).

Money

Money is bitmomo::Decimal, an exact decimal string such as "150.00". It never passes through f64. Convert it with your decimal crate, for example rust_decimal::Decimal::from_str(d.as_str()). The f64 fields on Balances are for display only; use the *_exact fields for arithmetic.

License

MIT