Buyer integration guide
Build an agent that buys from OpenMerchant merchants. Discover products, choose a seller, connect the customer’s account when required, and complete payment using the seller’s supported methods.
1. Choose your integration and environment
If you want OpenMerchant to manage purchasing for your application, follow the buyer API integration guide for customer profiles, payment methods, and purchase intents. If your agent handles checkout directly, use the UCP or MPP discovery documents and follow the flow below.
For a protocol-native agent, fetch the live/test environment index. Live is the default. Use the sandbox profile when developing; follow the origin it advertises throughout the flow.
- Live aggregate UCP business profile
- Sandbox aggregate UCP business profile
- MPP service discovery
- Agent instructions and protocol references
curl https://sandbox.openmerchant.dev/.well-known/ucp2. Read the contract before calling the API
The UCP profile advertises the REST service endpoint, capabilities, signing keys, and payment handlers. Follow dev.openmerchant.api_reference for the exact OpenMerchant request and response schemas. The buyer/platform profile describes OpenMerchant acting as a buyer; it is not the seller catalog.
- Public v1 OpenAPI schema
- Live aggregate UCP OpenAPI schema
- Sandbox aggregate UCP OpenAPI schema
- MPP OpenAPI schema
Use the authentication and request headers documented for your selected operation. Public discovery does not grant permission to perform authenticated API actions.
3. Search, select a seller, and check readiness
Use Catalog Search and Lookup to resolve products and variants. Each product identifies its seller and canonical merchant profile. Availability and purchasable are separate signals: discovery can remain available when a seller cannot accept checkout. An aggregate profile describes supported service capabilities; it does not promise that every listing can be purchased.
Keep each checkout within one seller. Follow that seller’s profile and the checkout response for concrete payment configuration. For items requiring a quote, use the UCP quote specification before creating the checkout.
4. Link the customer when required
Identity linking uses OAuth Authorization Code with PKCE. The identity capability’s dev.openmerchant.authorization_servers entries identify merchant issuers and their authorization-server and protected-resource metadata URLs. Choose the server for the selected merchant. A runtime WWW-Authenticate: Bearer challenge and its resource_metadata link remain authoritative for the request.
Use your registered client and redirect URI, validate state and issuer, and retain the PKCE verifier for the token exchange. Never substitute the upstream merchant identity provider’s issuer for the OpenMerchant merchant issuer.
5. Complete payment using the advertised handler
Resolve the payment handler and supported instruments from the checkout response. Obtain a credential for that seller, amount, currency, and environment. Follow the operation’s idempotency requirements when retrying. MPP uses separate identity and payment challenges; agent instructions explain the 401 → 402 → receipt sequence.
Continue with the buyer API integration guide for the OpenMerchant-managed purchasing flow, or use the API reference to look up a specific operation.