Panel — Integration Hub

Who calls these endpoints?Merchant panel

Base path: /api/panel/v1/wallet
Identity: Panel session (JWT) — Authorization: Bearer <panel access token>. The token comes from panel login; an s2s signing key does NOT open these endpoints.
Authorization: RBAC permission: wallet:config:manage · wallet:sponsor-policy:manage
Cross-surface: The endpoints on this page have NO equivalent in the s2s API; you cannot call them from your own panel. These capabilities exist only in the merchant panel, behind a panel session.

Where the wallet connects to the outside world. You see which providers are available, bind them to your program, and manage switches.

Provider catalogue

GET integrations/catalog        # filter by category, deploymentMode, licenceHolder
GET sponsor-policy/providers

The catalogue lists available providers by category:

Category	Used for
E-money	The licence the program runs on
Bank integration	Bank transfer top-up, withdrawal, IBAN transfer, bulk payouts
Biller	Bill inquiry and payment
ATM network	Cardless cash-out
Card issuer	Card issuing
Wallet provider	"Pay with wallet" at checkout

How the capability gate works

⚠️

If a category has no bound provider, that capability is closed — the request is rejected. The system never falls back to an "approximately right" provider or a simulator. This is deliberate: on a money path, silently falling back is worse than failing, because it presents a transaction that did not really happen as if it had.

So seeing an option on a screen does not mean the path works; a binding must exist.

Coming soon — categories awaiting a provider

There is no provider to bind in the bank integration, biller, ATM network and card issuer categories. When one is connected, the corresponding capabilities open automatically — no further development is required. Status: Roadmap.

Merchant wallet providers

GET  merchant-wallet-providers            # onlyAvailable filter
POST merchant-wallet-providers            # bind { providerCode, credentialRef?, displayName? }
PUT  merchant-wallet-providers/:providerCode

Determines which wallets your customers can pay with at checkout. Several providers can be active at once; the end user picks.

Your own wallet sits in this list under the same rules as any other provider — it has no privileged shortcut. If its catalogue row is deactivated, your own wallet drops off the list too.

Credential management

Bindings do not take credentials inline; they reference a credential reference. Secret values therefore never appear in the panel or in the binding record.

⚠️

When rotating credentials, bind the new reference first, verify traffic, then remove the old one. The reverse order produces a short outage.

Provider switching

GET  programs/:id/provider-switches
POST programs/:id/provider-switches
GET  programs/:id/provider-switches/:switchId/readiness
POST programs/:id/provider-switches/:switchId/drained
POST programs/:id/provider-switches/:switchId/abort

⚠️

You cannot move from one provider to another by plain-editing the provider field. An explicit switch record is required: open the switch → drain in-flight operations on the old provider → complete. This prevents operations being stranded half on the old provider and half on the new one.

The readiness endpoint shows which stage you are at and what is pending; abort rolls it back if something goes wrong.

Checklist

Every provider declared in the program's sponsor policy is actually bound
The policy was checked with validate
Credential references are current
Switches go through an explicit switch record
Closed capabilities are not offered to users in your product UI

Cards Reports