Customer Help

Using the API

How approved technical clients authenticate, read account data, submit supported requests, and receive webhook events.

Audience

For approved integrators and technical operators. API keys and webhook subscriptions are issued by MZ Bank administrators.

The integration API is designed for approved external clients that need machine access to MZ Bank account data and workflows.
The public base path is /api/v1/integrations/*.
API access is separate from Discord sign-in and the normal customer portal session.

API keys are bound to one active, verified MZ Bank customer profile.
An MZ Bank administrator creates the key and chooses the allowed scopes.
Webhook subscriptions are also created by an administrator and use a separate signing secret.

Send the API key as a bearer token in the Authorization header.
Each key is scope-limited. For example, accounts:read covers account views, while transfers:write allows transfer creation.
Keys can be rotated or revoked without changing the customer's normal website or bot access.

Clients can read visible accounts, balances, transaction history, statements, beneficiaries, notification preferences, applications, and business-family views when the correct scopes are present.
Account responses are subaccount-aware and include root-family identifiers where relevant.
Business-family responses include child subaccounts, beneficial owners, active access grants, and caller capabilities.

The API supports customer-operable requests such as transfers, subaccount creation, account applications, beneficiary management, notification-preference updates, withdrawal requests, and deposit requests.
Money-moving routes must still satisfy the same authorization, rate-limit, and ledger rules enforced by the bot and portal.
Write requests should use idempotency keys wherever the route requires them so safe retries do not create duplicate activity.

Business-family routes use the same ownership and delegated-access rules as the portal.
Subaccount-aware responses include both the leaf account ID and the root business-family account ID.
Delegated operators can only use the accounts and actions allowed by their current role and caps.

Webhook subscriptions can receive deposit, withdrawal, and transfer lifecycle events.
Transfer webhooks are emitted separately for the outbound and inbound account sides so subaccount and family-aware consumers can process each side correctly.
Every webhook is signed with x-mzb-signature-256, and consumers should verify the signature against the exact raw body.

Statement-list and statement-export routes provide the same published statement history the customer can access through the Statement Center.
Notification routes expose both saved preferences and recent delivery outcomes.
API activity should reconcile with portal state, statements, and webhook events for the same customer or business family.

Ask an MZ Bank administrator to issue a scoped test key with only the read and write capabilities your client actually needs.
Validate webhook handling against a disposable capture endpoint before sending events to a production callback URL.
If you need the exhaustive operator reference for endpoints, scopes, and troubleshooting, ask an administrator for the internal integrations documentation.