Wallet adapter settings

Wallet adapter settings define how OpenPoly talks to operator wallet system.

Open Integrations → Wallet Settings (/settings/wallet-adapter). Reading settings requires wallet_adapter:read; saving and all adapter tests require wallet_adapter:write (or *).

Core decisions

• REST v1 base URL
• operator currency code
• operator-hosted callback paths
• outbound bearer token
• optional signature secret
• timeout expectation

REST v1 mode

Use for real operator-hosted wallet integration.

The dashboard saves balance_adapter_type = rest_v1. Staging simulator behavior is user-scoped through simulator-tagged users, not an operator-wide dashboard adapter mode.

Expected operator-hosted paths:

• /balance
• /debit
• /credit
• /debit-reversal

Opinion and Polyflight use these same four paths: one balance read and three mutation paths. Current Opinion trade/redemption flows do not call /credit-reversal; Polyflight also uses only debit, credit, and debit reversal.

Full contract: /docs/wallet-adapter/overview

Required backend behavior

• every mutation uses idempotency key
• ambiguous primary mutations stop for manual review
• compensation retries reuse the original idempotency key
• currency code must stay consistent with operator config
• mutation JSON bodies include external_user_id, but not direction; the endpoint path supplies direction
• non-null response echoes must match the dispatched user, idempotency key, amount and currency; mismatches are unknown outcomes, not proof of rejection

Secret handling

• configured secrets are encrypted server-side and never shown back
• dashboard responses show only has_bearer_token, has_signature_secret, and auth_mode
• store outbound auth secret in operator secret manager too
• store optional signing secret separately
• never paste live secrets into tickets or chat

Validation tests

Wallet Settings saves the configuration; it has no full-contract test form. Save first, then open Integrations → Integration UAT (/integrations/uat) for a connection check using the saved adapter. Run safe UAT checks calls only GET /balance for the entered external user ID and inspects selected-product subscriptions. This workflow needs wallet_adapter:read for setup, wallet_adapter:write for the test, and webhooks:read for subscription readiness; write scope does not imply read.

Full-contract checks are available through POST /api/operator/wallet-adapter/test or API Playground → Wallet Adapter by editing the JSON body. They require explicit confirmation and perform real mutations against the submitted/saved adapter, not automatically against a simulator.

• Opinion: initial balance, debit, debit reversal, credit, second debit, final balance.
• Polyflight: choose product: "polyflight", confirm the dedicated test user, and enter 1,000–10,000 IDR in 1,000-IDR steps. Normal, timeout-after-apply, definite rejection and duplicate scenarios have different sequences; normal includes loss acknowledgement and its duplicate.

See the test API contract before running a scenario. Use dedicated non-production wallet infrastructure, not an ordinary customer's ID. Reconcile requires_manual_review even when an expected-failure scenario reports success: true. Never rerun a whole test to repair an unknown money outcome.

Timeout guidance

REST v1 adapter default timeout is 10000 ms.

If operator wallet may exceed timeout, reduce its synchronous processing time. A timeout leaves the primary mutation ambiguous and requires manual review.

Common misconfigurations

• wrong currency code
• non-idempotent debit or credit handling
• signature secret mismatch
• treating simulator drills as proof that the real REST v1 wallet is production-ready