WalletD for developers
A wallet operating system behind one REST API. Start here whether you are integrating it, reviewing it, operating it, or deciding to buy it.
WalletD is a wallet operating system. You get a double-entry money core (balances, top-ups, transfers, payments with holds, refunds, rewards, subscriptions, credit lines) behind one REST API, so your product can hold and move money without becoming a ledger company.
Authored English guides are also published as raw markdown at the same path plus .md,
indexed in llms.txt, and concatenated into
llms-full.txt for coding agents.
Read this first
Three facts decide most of your integration, so they come before any code.
Money is integer minor units. 2500 is $25.00. There are no floats
anywhere in the API, in either direction. A currency's exponent tells you where
the decimal point goes; you do the formatting, and only for display.
Every money-moving call needs an Idempotency-Key. Not optional, not
best-effort: POST /v1/transfers without one is rejected. Replaying a key
returns the original response byte for byte instead of moving money twice. This
is what makes a timeout safe to retry.
Money only enters through a verified gateway confirmation. Creating a top-up intent does not credit anything. A wallet's balance rises when the payment processor tells WalletD the money arrived, over a signature-verified webhook or a reconciliation query. A client-side "payment succeeded" callback is a UI event, never a credit.
The shape of an integration
Your backend holds an API key and acts for the whole tenant. Your app holds a short-lived user token and can only act for that one user. Both talk to the same API; the credential decides what is allowed, and WalletD verifies it itself rather than trusting a header from the edge.
Start here
Quickstart
Five calls in ten minutes: create a user, fund the wallet, read the balance, send money, read the history.
Authentication
API keys, wallet user tokens, IdP tokens, and the scope table.
Environments and base URLs
Sandbox versus live keys, what differs between them, and which URL is yours.
Testing and sandbox
Test cards, and how to provoke every failure on purpose.
Understand the model
The money model
Minor units, balance versus available versus held, and double entry.
Idempotency
Why every money-moving call needs a key, how to choose one, and how to retry.
Errors
RFC 7807 problem responses, the full code table, and what is retryable.
Limits and quotas
Tier limits, credit lines, rate budgets and bulkheads, and where each is enforced.
Build a money path
Top-ups
Money in, through a gateway intent and a verified confirmation.
Transfers
Wallet to wallet, with aliases, fees and velocity limits.
Payments and refunds
Instant payments, authorize and capture with holds, and refunds.
Subscriptions
Recurring charges and the dunning state machine.
Rewards
Cashback, points accrual, conversion rules and caps.
Payouts
Merchant settlement, payout runs and statements.
Ecosystem
Clients, offerings, discovery and client-funded rewards.
Commerce
Catalog, orders and the merchant storefront.
Integrate and operate
Webhooks
Receiving events, signature verification, retries and the event catalogue.
API reference
Every operation of the Wallet, Auth and Ledger APIs, generated from the contracts.
SDKs and tools
The Go SDK, the OpenAPI documents, and a Postman or Bruno collection.
Coding agents
Markdown endpoints, llms.txt, and what agents get wrong about this API.
Evaluate the platform
For a reviewer, an operations lead, or whoever signs the contract: these four pages say how the platform is built, how it is secured, what its limits are, and what happens when something breaks.
Architecture overview
The services, what is authoritative for money, and what a partner deployment contains.
Security for integrators
Credential lifecycle, scopes, signing, retention, and what is not offered today.
Going live
The checklist: live keys, webhook receivers, reconciliation, monitoring and sign-off.
Support, SLAs and status
Severity model, response targets, escalation, and the status page.
Languages in this guide
Every money-moving operation is shown in curl, Go, Python, PHP, JavaScript and Java. The curl example is the contract; the rest are the same request in each language's idiom. Pick a language once and the tabs follow you across the site.