Merchant setup

Merchant setup is an optional provider capability. It helps a controller (business or individual user) 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. Controllers can alternatively self-serve on the Business / Users dashboard (capped at 2 identifiers).

Provider-owned identifier limits

When registering through your provider API, you define how many identifiers each controller may hold and how upgrades work. Enforce that in your product UI and backend. The official dashboard’s 2-identifier cap applies only to dashboard registrations, not to your Merchant Setup API traffic.

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. Enforce your per-controller identifier limit before create.
5. Submit the identifier and one or more validated payment destinations.
6. Show pending activation and any safety period.
7. 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.