Embedded Components

Resolve embedded components let a partner display a narrowly scoped Resolve experience for one of its sub-merchants without exposing the partner's OAuth credentials in the browser. Your backend mints a short-lived embed token; the published component uses that token only for its approved merchant API routes.

You need:

• a Resolve partner merchant account and at least one active sub-merchant
• OAuth enabled for the partner in Merchant Dashboard
• a standard REST API OAuth access key whose scopes include the permissions required by the component
• the client_id and client_secret stored only in your server-side secret manager
• the published component package and the merchant API version that its release supports

Do not use an MCP access key for this flow. The partner OAuth credentials and the embed token are different credentials with different purposes.

1. Your backend exchanges the partner OAuth access key for a partner bearer token.
2. Your backend calls POST /api/embed-sessions for a specified sub-merchant and component.
3. Resolve validates the partner, sub-merchant relationship, OAuth/API access, and the partner permissions required for that component.
4. Resolve returns a short-lived embed token scoped to that sub-merchant and component.
5. Your application provides the embed token to the published component in memory.
6. The component calls only its allowed merchant API routes using the embed token.

Resolve persists the session behind the token. A token is rejected if the session expires or is revoked, the issuing OAuth access key is no longer active, or the sub-merchant is no longer associated with the partner.

In Merchant Dashboard, open Settings > Integrations > Direct API for the partner merchant.

1. Enable OAuth.
2. Create a standard REST API access key with the scopes appropriate for the component.
3. Copy the client_id and client_secret when shown, then place them in your backend secret manager.

Use the OAuth access-token guide to exchange these credentials for a bearer token. Never ship the client_secret to the browser, a mobile application, component configuration, source control, or logs.

Call POST https://app.resolvepay.com/api/embed-sessions from your backend. Send the partner OAuth bearer token and the partner API version header:

POST /api/embed-sessions
Authorization: Bearer <partner_oauth_access_token>
Content-Type: application/json
resolve-api-version: partner-v1

{
  "partner_merchant_ref": "child-merchant-external-id",
  "component": "payments"
}

partner_merchant_ref can be the Resolve ID or external ID of a sub-merchant that currently belongs to your partner account.

component is a Resolve-managed identifier. Use the identifier documented by the embedded-components package version you are installing. Component identifiers and the routes they authorize are versioned with the published package.

A successful response is similar to:

{
  "session_id": "es_123",
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expires_at": "2026-08-27T15:30:00.000Z",
  "merchant_id": "merchant_123",
  "component": "payments",
  "capabilities": ["payments:read"]
}

Use expires_at as the source of truth. When the component needs a new token, have your backend mint another session. A 503 response means embed sessions are not configured for that Resolve environment.

Pass the returned token to the published component using its documented token option. Keep it in memory only.

• Do not place the token in a URL, local storage, session storage, cookies, analytics events, error reports, fixtures, or logs.
• Do not expose the partner OAuth access token or OAuth client credentials to the component.
• Do not let browser input choose the sub-merchant independently of your server-side authorization. Your backend should determine which sub-merchant session to mint for the signed-in partner user.
• Treat a component authentication error as a signal to request a fresh embed token from your backend.

The component identifier used to mint the session is a server authorization choice; it does not need to match an npm export name. Follow the documentation for the exact component package release you install.

Embed tokens are intentionally short-lived and are not a general-purpose API credential. Resolve rejects a token when any of the following occurs:

• the token or persisted embed session expires
• the persisted session is revoked or inactive
• the source OAuth access key is revoked, disabled, deleted, or expires
• the target sub-merchant is detached from or reassigned outside the issuing partner
• the requested route or HTTP method is not allowed for the component

The route allowlist is deliberate: possessing a permission does not automatically grant access to every API route that shares that permission. A new merchant API endpoint is unavailable to an embedded component until Resolve explicitly approves it for that component.

See the Embed Sessions endpoint for the full request and response contract.