Merchant setup

Merchant setup is an optional provider capability. It helps a controller register identifiers and destinations while the controller remains the owner of the mapping.

When to use it

Merchant Setup is for an approved provider that helps a controller register or manage mappings from inside a wallet. It is not needed for resolver-only integrations or Free API prototypes.

Setup sequence

1. Authenticate the approved provider.
2. Connect the controller wallet and obtain its authorization signature.
3. Discover an active identifier type and check availability.
4. Submit the identifier and one or more validated payment destinations.
5. Show pending activation and any safety period.
6. Refresh until the mapping is active before displaying it as payable.

Request example

POST /v1/identifiers
Authorization: Bearer <approved-provider-key>
X-Controller-Wallet: 0xController…
X-Controller-Authorization: <signed payload>
Idempotency-Key: create-identifier-123

{
  "type": "email",
  "value": "pay@example.com",
  "payment_options": [{
    "chain": "base",
    "asset": "USDC",
    "address": "0xRecipient…",
    "network_identifier": "eip155:8453"
  }]
}

Provider boundary

A provider may facilitate the UI and send authenticated requests, but cannot silently transfer ownership, bypass safety periods, or change a controller’s destination without authorization.

Use Register an Identifier for the controller-facing checklist.