delopay 0.3.0

Official Rust SDK for the DeloPay payments API
Documentation

delopay

Official server-side Rust SDK for the DeloPay payments API. Typed, async, hyper-based, with a constant-time webhook verifier.

Covers the full merchant API: payments, hosted checkout and payment links, webhook verification, refunds, customers, payouts, disputes with evidence, mandates, payment methods, events, subscriptions, ephemeral keys, poll, cards, forex, files and export, plus account configuration (merchant accounts, shops and business profiles, connectors, API keys, routing and surcharge rules, regions, fees, blocklist, 3DS authentication, Apple Pay verification, Stripe Connect onboarding) and reporting (analytics, search, projects, billing, users and roles).

Installation

You also need an async runtime (tokio).

[dependencies]
tokio = { version = "1", features = ["macros", "rt-multi-thread"] }
delopay = "0.3"

Webhook-only build (no HTTP client)

If a service only needs to verify incoming webhooks and read the wire models, disable the default client feature. That build has no hyper, tokio, or async runtime, pulls 26 crates instead of 64, and is pure Rust, so no C toolchain is required:

delopay = { version = "0.3", default-features = false }

webhooks::verify, WebhookEvent, DelopayError, and all the *Response models are available; Delopay, the request builders, and the resources module are not.

Create a payment with hosted checkout

use delopay::{Delopay, PaymentCreateRequest};

#[tokio::main]
async fn main() -> delopay::Result<()> {
    // `prd_...` = production, `snd_...` = sandbox (use Delopay::sandbox).
    let client = Delopay::new("prd_your_secret_key");

    let payment = client
        .payments()
        .create_idempotent(
            &PaymentCreateRequest::new(1999, "EUR") // 19.99 EUR, minor units
                .profile_id("pro_your_shop_id")
                .payment_link(true)
                .return_url("https://your-shop.example/return")
                .customer_email("ada@example.com"),
            "order_1001", // idempotency key, safe to retry
        )
        .await?;

    // Redirect the shopper to the hosted checkout:
    let url = client.hosted_checkout_url(&payment.merchant_id, &payment.payment_id);
    println!("go to {url}");
    Ok(())
}

The return page is not the source of truth. Reconcile status from the webhook, or client.payments().retrieve_synced(&id).

Verify a webhook

DeloPay signs each webhook with HMAC-SHA512 over the raw body; the hex digest arrives in the X-Webhook-Signature-512 header. Verify the raw bytes before parsing:

use delopay::webhooks;

// raw_body: &[u8] captured before JSON parsing; sig: the header value.
let event = webhooks::verify(raw_body, sig, "whsec_your_shop_secret")?;
if event.event_type == "payment_succeeded" {
    if let Some(payment) = event.content.as_payment() {
        // fulfil the order for payment.payment_id
    }
}

Subscriptions

Subscription endpoints are profile-scoped; the backend requires an x-profile-id header. Scope the resource once:

let subscriptions = client.subscriptions().with_profile_id("pro_your_shop_id");
let sub = subscriptions.retrieve("sub_123").await?;

Idempotency

A key makes a create safe to retry: the server replays the first response instead of charging twice. It also lets the SDK retry the POST itself on a 5xx or network error, which it will not do for an unkeyed one.

let refund = client
    .with_idempotency_key(format!("refund-{order_id}"))
    .refunds()
    .create(&RefundCreateRequest::new("pay_123"))
    .await?;

Scope it to one logical operation, as above — a client held across unrelated calls would make every later one return the first one's result.

Logging

use delopay::{Delopay, LogEvent};

let client = Delopay::builder("prd_your_secret_key")
    .logger(|event: LogEvent<'_>| tracing::debug!(?event, "delopay"))
    .build();

LogEvent covers Request, Response and Retry. Logged URLs carry no query string — only parameter names are exposed, never values — and headers, bodies and the API key are never handed to a logger. .debug(true) is a stderr shorthand for local use.

Fee rules

fees().rules() takes a rule program built with the typed builder rather than hand-written JSON:

use delopay::{FeeRuleConditions, FeeRuleInput, FeeSpecInput, fee_program};

let algorithm = fee_program()
    .rule(
        FeeRuleInput::new("crypto", FeeSpecInput::new().percentage(1.0))
            .when(FeeRuleConditions::new().payment_method("crypto")),
    )
    .otherwise(FeeSpecInput::new().percentage(3.0))
    .build()?;

// `None` targets the whole merchant; pass a shop ID to scope it.
client.fees().rules().upsert_program(&algorithm, None, "mer_1").await?;

Checkout branding

delopay::branding encodes and decodes the hosted checkout's branding configuration — the same representation the control center writes and the checkout reads — including a CSS sanitizer for merchant-supplied custom CSS. It is in the always-compiled core, so it is available in the webhook-only build too.

HTTP proxies

Behind a corporate egress proxy, the SDK reads the usual environment variables (HTTPS_PROXY, HTTP_PROXY, ALL_PROXY, filtered by NO_PROXY), or you can configure it on the builder:

let client = Delopay::builder("prd_your_secret_key")
    .proxy("http://corp-egress.internal:3128") // ignore the environment
    .build();

let client = Delopay::builder("prd_your_secret_key").no_proxy().build();

http:// proxies only, via HTTP CONNECT tunnelling: TLS is negotiated with the API through the tunnel, so the proxy never sees plaintext. A configured but unusable proxy fails every request instead of silently connecting direct, and proxy credentials never appear in Debug output.

Design notes

  • HTTP: hyper directly, not reqwest. The Transport trait is the only backend seam; retries, backoff, and error mapping sit above it.
  • TLS: rustls with the ring provider passed explicitly; the SDK never installs a process-global crypto provider. Portable across Linux, macOS, and Windows.
  • Retries: automatic on 429 (always) and on network errors or 5xx for idempotent calls (GET, or a request with an idempotency key), so a create is never silently duplicated. Honors Retry-After.
  • Forward-compatible: responses keep unknown fields in an extra map, so a new API field never breaks deserialization.
  • Bounded memory: response bodies are capped at 10 MiB.
  • Errors: DelopayError distinguishes Api, Authentication (401), Timeout, Transport, InvalidSignature, and InvalidRequest. Api and Authentication carry the API code, type, and x-request-id.

License

MIT.