Integrations

An integration defines the trust boundary between your product and Magnum checkout.

Create

POST /v1/integrations requires integrations:write. Only the following fields are accepted; unknown properties are rejected.

{
  "name": "Store checkout",
  "environment": "sandbox",
  "allowedOrigins": ["https://store.example"],
  "allowedNetworks": ["ethereum", "base", "arbitrum"],
  "appearance": {
    "theme": "dark",
    "accent": "#00F2C2",
    "locale": "en",
    "radius": 22,
    "compact": false
  }
}

Restrictions

Use 1–20 exact origins. Do not use paths, wildcards, credentials in URLs, or unnecessary third-party origins. HTTP is accepted only for localhost and 127.0.0.1 outside production.

Networks must belong to the Magnum catalog. A session can choose only a network on that list. The backend repeats this validation when creating a payment, even if the browser is modified.

environment cannot be changed by checkout. Names are limited to 80 characters. Integrations do not accept wallet, destinations, lockWallet, or equivalent parameters.

List

GET /v1/integrations requires integrations:read and lists up to 100 records belonging to the authenticated workspace, ordered by creation time. The dashboard supports editing and deactivation through PATCH /v1/console/workspaces/:workspaceId/integrations/:id. A verified owner/admin can update permitted appearance, origins, networks and active. Secret-key integration routes do not grant access to another business or bypass the live-payment gate.

Receiving policy

A business configures fixed receiving addresses by network and asset in its authenticated settings, using GET and PUT /v1/console/workspaces/:workspaceId/settlement. These addresses are not accepted from public checkout or integration creation. A future live session must resolve a matching authorized destination on the server; the payer cannot replace it. The global 4P credential belongs to the Magnum operator, and live processing remains closed pending explicit provider approval of the commercial model.