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).
[]
= { = "1", = ["macros", "rt-multi-thread"] }
= "0.7"
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:
= { = "0.7", = 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 ;
async
The return page is not the source of truth. Reconcile status from the webhook,
or client.payments().retrieve_synced(&id).
Test or live
test_mode decides which environment a payment runs in: true runs it against
the processor's sandbox and keeps it out of live reporting, false runs it live,
and omitting it runs it live. Drive it from the environment your process is in —
.test_mode
— and a staging deploy can never take a real card, while production never has to
remember to switch anything back. It is read only at create; confirm and
update ignore it, since those can be called from the browser with a client
secret.
One caveat worth knowing: a processor with no sandbox credentials stored is
called with the only credentials it has, so a payment marked as a test still
charges for real. PaymentResponse::test_mode echoes back what actually
happened — check it before you act on succeeded.
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 webhooks;
// raw_body: &[u8] captured before JSON parsing; sig: the header value.
let event = verify?;
if event.event_type == "payment_succeeded"
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;
let sub = subscriptions.retrieve.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
.refunds
.create
.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 ;
let client = builder
.logger
.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 ;
let algorithm = fee_program
.rule
.otherwise
.build?;
// `None` targets the whole merchant; pass a shop ID to scope it.
client.fees.rules.upsert_program.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.
Buyer-side checkout
A hosted checkout page never holds a secret key. CheckoutSession binds the
two browser-safe credentials — the merchant's publishable key and the
payment's client secret — and sends each route exactly the one it expects:
use ;
let session = new;
let catalog = session.paysepro_methods.await?; // client secret, as a bearer
let payment = session.retrieve_payment.await?; // publishable key
There is no way to hand it a secret key: the constructor does not take one.
If a page holds only the client secret, PaymentLinkSession exposes exactly
the routes that credential authenticates — a call you cannot authenticate is
not on the type you built, rather than a runtime error.
Money
Amounts are minor units, and a minor unit is not always a hundredth:
use Money;
assert_eq!;
assert_eq!;
assert_eq!;
// A currency the SDK does not know returns `None` rather than guessing 2.
assert_eq!;
Settlement and operation-limit models expose Money accessors next to the
raw integers, so an amount never travels without the currency that gives it
meaning.
Settlement
For merchants hosting shops on behalf of third-party owners,
client.settlement() covers the monthly statements, the live current period,
per-line detail, backfills, payout recording, and the statement PDF. Every
read takes an explicit test_mode — test and live figures never blend:
let overview = client.settlement.overview.await?;
let pdf = client
.settlement
.download_statement_pdf
.await?;
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 = builder
.proxy // ignore the environment
.build;
let client = builder.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:
hyperdirectly, notreqwest. TheTransporttrait is the only backend seam; retries, backoff, and error mapping sit above it. - TLS:
rustlswith theringprovider 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 or5xxfor idempotent calls (GET, or a request with an idempotency key), so a create is never silently duplicated. HonorsRetry-After. - Forward-compatible: responses keep unknown fields in an
extramap, so a new API field never breaks deserialization. - Bounded memory: response bodies are capped at 10 MiB.
- Errors:
DelopayErrordistinguishesApi,Authentication(401),Timeout,Transport,InvalidSignature, andInvalidRequest.ApiandAuthenticationcarry the APIcode,type, andx-request-id.
License
MIT.