OOLIN Service Architecture

The OOLIN Wallet API provides fund receipt, balances, transfers, withdrawals, and transaction records for customer accounts. Your backend uses these capabilities to build a customer wallet or merchant payment service. Your service manages customer logins, orders, and merchant information, then connects them to Wallet API accounts and transactions.

Your application and the Wallet API

Customer app or merchant service
  → your backend: login, authorization, orders, and request signing
  → OOLIN Wallet API: accounts, deposits, transfers, withdrawals, balances, and ledger
  → your backend: retrieve transaction results and update business state
  → customer interface: balances, payment results, and settlement progress

The app calls your authenticated backend. Your backend verifies the customer and their permission for the action, then signs the Wallet API request using the API Key and HMAC key. Keep these credentials on the server; do not provide them to a browser or mobile app.

HMAC authentication verifies the API request and its integrity. Your backend separately decides whether the customer is allowed to withdraw from a particular account. API authentication and customer authorization are different responsibilities.

Roles and responsibilities

Concern	Your backend	OOLIN Wallet API
Customer and merchant identity	Manage logins/business identifiers and connect them to uid	Provide accounts associated with uid
Account provisioning	Select or request an account and persist its mapping	Create/query accounts and provide account state
Deposits	Display destinations and update business state after completion	Allocate addresses and provide deposit state and balances
Payments and withdrawals	Verify permissions and financial intent, then submit requests	Process fund movements and provide transaction detail
Recovery	Persist business/request IDs and retrieve existing results	Query by transaction ID or client_request_id
Reconciliation	Compare orders and settlements with transactions and ledger entries	Provide balances, ledger entries, and reconciliation views

Capabilities and resources

Capability	API resources
Provision customer wallets	POST /accounts, GET /users/{uid}/accounts
Select assets and networks	/asset-types, /networks, /assets
Allocate deposit destinations	/accounts/{account_id}/deposit-addresses
Find and confirm deposits	/deposits, /deposits/{deposit_id}
Display spendable funds	/accounts/{account_id}/balances
Pay another account	POST /withdrawals/internal
Settle to an external address	POST /withdrawals/quote, POST /withdrawals
Inspect results and balance movements	/withdrawals/{withdrawal_id}, /accounts/{account_id}/ledger

Wallet features and payment scenarios

A customer wallet combines account provisioning, deposit destinations, deposit confirmation, balance/ledger queries, and external withdrawals. Customers receive and hold funds, check spendable balances, and withdraw to their chosen external addresses.

Use internal transfers to send funds to another OOLIN account. Digital Payment applies this capability to payments from a customer USER account to a merchant BUSINESS account, then connects merchant withdrawals to settlement. It uses the same Wallet API resources; there is no separate /payments API.

Scenario	Main flow	Your business mapping
Customer wallet	Account → external deposit → balances/history → external withdrawal	Customer/account, deposit records, and withdrawal applications
Account transfer	Source account → internal transfer → recipient account	Source/recipient accounts and transfer purpose
Digital Payment	Customer funding → merchant payment → merchant settlement	Orders/payment transactions and merchants/settlement transactions

Acceptance and business completion

External deposits require confirmations and processing time. External withdrawals proceed to on-chain execution after acceptance. A transaction ID returned by creation identifies the result to retrieve. Decide when to display success using the completion rule for that transaction type.

For example, when a customer requests an external withdrawal, link its withdrawal_id to your withdrawal application and keep it pending. Complete the withdrawal when both status and user_status are COMPLETED and tx_hash is valid. Merchant settlement uses the same withdrawal completion rule.

If the create response is lost, retrieve the existing transaction using the stored client_request_id. Connecting your order ID, client_request_id, and Wallet transaction ID lets you continue the same operation after a restart. See Idempotency and Duplicate Prevention for recovery.

Choose an integration flow

Follow the Wallet tutorials for customer deposits, balances, and external withdrawals. Follow the Digital Payment tutorials for customer-to-merchant payments and settlement. Continue with Users, Accounts, and Wallets to understand account relationships in both flows.