Merchant integration

Merchant wallet

The merchant-wallet endpoint creates a primary wallet for a business and currency. The overview endpoint returns wallets and balances aggregated by branch, and verifies that the merchant path identifier matches authenticated business context unless the caller is authorized platform staff.

Payment links

The payment-link endpoint creates link data for a merchant, amount, currency, and description. Creating a link is not evidence of collection; funds are collected only when the payment reaches a completed state. Do not place sensitive data in description or metadata because the link can be represented in multiple logs.

QR payload

The QR endpoint returns a JSON string containing payload type, merchant identifier, wallet UUID, account number, and currency. Render the payload without altering its fields. Validate the currency before initiation, and do not rely only on visible text to protect against QR substitution.

Settlement

A merchant can request a manual settlement period using an idempotency key. Finance workflows should review the period, totals, and state before approval and execution. A settlement request is not a promise of a specific deposit time unless the merchant agreement states one.

Permissions

Separate read, payment-link, settlement, and refund capabilities. Never install an owner-level credential on a cashier device. Store the token in the merchant backend, apply branch policy there, and correlate each sensitive operation with a request ID.