Brazilian Commerce Protocol (BCP) Official Specification

Overarching guidelines

The key words MUST, MUST NOT, REQUIRED, SHALL, SHALL NOT, SHOULD, SHOULD NOT, RECOMMENDED, MAY, and OPTIONAL in this document are to be interpreted as described in RFC 2119 and RFC 8174.

Schema notes:

• Date format: Always specified as RFC 3339 unless otherwise specified
• Amounts format: Minor units (cents)

Discovery, Governance, and Negotiation

BCP separates protocol version compatibility from capability negotiation. The business's profile at /.well-known/ucp describes capabilities for the protocol version it declares. Businesses that support older protocol versions SHOULD publish version-specific profiles and advertise them via the supported_versions field — a map from protocol version to profile URI, enabling platforms to discover the exact capabilities for a specific protocol version. Version lifecycle, including when to deprecate or remove older versions from supported_versions, is a business policy decision. The protocol does not prescribe a deprecation schedule. Capability negotiation follows a server-selects architecture where the business (server) determines the active capabilities from the intersection of both parties' declared capabilities. Both business and platform profiles can be cached by both parties, allowing efficient capability negotiation within the normal request/response flow between platform and business.

Namespace Governance

BCP uses reverse-domain naming to encode governance authority directly into capability identifiers. This eliminates the need for a central registry.

Naming Convention

All capability and service names MUST use the format:

{reverse-domain}.{service}.{capability}

Components:

• {reverse-domain} - Authority identifier derived from domain ownership
• {service} - Service/vertical category (e.g., shopping, common)
• {capability} - The specific capability name

Examples:

Name	Authority	Service	Capability
br.dev.bcp.shopping.checkout	bcp.dev.br	shopping	checkout
br.dev.bcp.shopping.fulfillment	bcp.dev.br	shopping	fulfillment
br.dev.bcp.common.identity_linking	bcp.dev.br	common	identity_linking
com.example.payments.installments	example.com	payments	installments

Authority Binding

Reverse-domain names serve two purposes: collision-safe identifiers (keys and references), and entities — capabilities, services, and payment handlers — that declare a fetched schema URL describing them. Authority binding applies to every entity with a remote schema: a declared schema URL's origin MUST match the namespace authority in its name.

A capability MUST declare a schema; services and payment handlers declare one where their transport or handler defines it. Each entity MAY also declare a spec URL (human-readable documentation).

This binding guarantees provenance, not trust: a valid binding proves only that the reverse-domain name is controlled by the party that owns the corresponding domain — an entity cannot be published under a namespace its author does not control. It does not assert that the entity is trustworthy, correct, or worth supporting. Whether to negotiate, trust, or implement it is always the client's decision; this binding only tells the client who is making the claim. Provenance is established from domain ownership and evaluated at negotiation time.

The spec URL is documentation, not part of the machine trust path, so its origin is not authority-bound: it MUST be https but MAY be served from any host (e.g. a docs subdomain or third-party docs host). Only the schema URL carries the authority binding defined below.

Derivation algorithm

The authority is derived from the schema URL host — which names the owning domain directly, with no ambiguity about where the domain ends — and validated as a label prefix of the entity's name. For the schema URL of an entity whose name is name, a platform MUST apply the following:

1. Parse the URL with a conformant (WHATWG) URL parser. It MUST parse, MUST use the https scheme, and MUST NOT contain userinfo (a user:pass@ component). Substring matching on the raw URL is NOT permitted — e.g. https://bcp.dev.br@evil.example/x.json has host evil.example, not bcp.dev.br.
2. The host MUST be a registered domain name of at least two labels. IP-literal hosts (https://203.0.113.10/...) and single-label hosts (https://localhost/...) are invalid authorities.
3. Take the URL's hostname (the host without any port), normalize it (lowercase; strip a trailing .; internationalized domains in A-label / punycode form), and reverse its labels to form the authority_prefix (host bcp.dev.br → br.dev.bcp).
4. The binding is valid if and only if name begins with authority_prefix followed by a . (a literal trailing dot). The trailing-dot boundary is required so that com.example (from host example.com) cannot satisfy a neighboring namespace like com.examplecorp.*, where it is a textual but not label-aligned prefix; it also guarantees a non-empty remainder after the prefix.

The remaining labels after the authority prefix are treated as opaque by this check; they are not inspected or split.

Capability name	schema host	authority_prefix	Result
br.dev.bcp.shopping.checkout	bcp.dev.br	br.dev.bcp	accept
br.dev.bcp.shopping.checkout	shopping.bcp.dev.br	br.dev.bcp.shopping	accept
com.example.payments.installments	example.com	com.example	accept
com.example.pay	evil.example	example.evil	reject
br.dev.bcp.shopping.checkout	evil.example	example.evil	reject
com.examplecorp.pay	example.com	com.example	reject
com.example.pay	cdn.example.com	com.example.cdn	reject

An entity's schema is served from a host whose reversed labels are a prefix of its name. A canonical apex host (example.com for com.example.*) always satisfies this; a subdomain satisfies it only when its labels line up with the namespace path (shopping.bcp.dev.br for br.dev.bcp.shopping.*). Unrelated subdomains such as a shared CDN do not satisfy it — host the canonical schema on a name-aligned origin.

The check uses the schema URL host directly and does not consult the Public Suffix List, so it treats a public suffix — a domain under which independent parties can register names, from co.uk to the list's private-section suffixes operated by services that let third parties register subdomains or buckets (github.io, object storage, app platforms) — as an ordinary authority. Co-tenants under such a suffix satisfy the same prefix, so declare entities only under a registrable domain (a public suffix plus one label) that you exclusively control.

Enforcement

A platform MUST validate each business-declared schema URL before fetching it. If the URL's origin does not match the entity's namespace authority (per Derivation algorithm), the platform MUST NOT fetch it and MUST reject the entity — treated as not present and never activated. A spec URL MUST be a valid https URL. A platform MUST NOT follow redirects (3xx) when fetching a schema URL, consistent with profile fetches.

The platform fetches and composes business-declared schemas to validate every request and response, so validating the binding ensures each composed schema is sourced from the party that owns the entity's namespace. A business SHOULD apply the same check to the platform profile and exclude any entity whose binding fails.

Binding validates the declared hostname for provenance; it is not a fetch-safety control and does not authorize dereferencing. Fetching the schema URL — like any URL fetched during discovery — is additionally subject to the protocol's URL fetch-safety requirements, which guard the resolved address (not just the hostname) against server-side request forgery toward special-use or cloud-metadata addresses and DNS rebinding. The hostname check and the resolved-address check are independent, and both apply.

Governance Model

Namespace Pattern	Authority	Governance
br.dev.bcp.*	bcp.dev.br	BCP governing body
com.{vendor}.*	{vendor}.com	Vendor organization
org.{org}.*	{org}.org	Organization

The br.dev.bcp.* namespace is reserved for capabilities sanctioned by the BCP governing body. Vendors MUST use their own reverse-domain namespace for custom capabilities.

Services

A service defines the API surface for a vertical (shopping, common, etc.). Services include operations, events, and transport bindings defined via standard formats:

• REST: OpenAPI 3.x (JSON format)
• MCP: OpenRPC (JSON format)
• A2A: Agent Card Specification
• EP(embedded): OpenRPC (JSON format)

Service Definition

Full service declaration for platform-level discovery. All transports require version, spec, and transport. REST, MCP, and embedded additionally require schema.

Name	Type	Required	Description
version	string	Yes	Entity version in YYYY-MM-DD format.
spec	string	Yes	URL to human-readable specification document.
schema	string	No	URL to JSON Schema defining this entity's structure and payloads.
id	string	No	Unique identifier for this entity instance. Used to disambiguate when multiple instances exist.
config	object	No	Entity-specific configuration. Structure defined by each entity's schema.
transport	string	Yes	Transport protocol for this service binding. Enum: rest, mcp, a2a, embedded
endpoint	string	No	Endpoint URL for this transport binding.

Transport definitions MUST be thin: they declare method names and reference base schemas only. See Requirements for details.

Endpoint Resolution

The endpoint field provides the base URL for API calls. OpenAPI paths are appended to this endpoint to form the complete URL.

Example:

{
  "version": "2026-07-14",
  "transport": "rest",
  "schema": "https://bcp.dev.br/2026-07-14/services/shopping/rest.openapi.json",
  "endpoint": "https://business.example.com/api/v2"
}

With OpenAPI path /checkout-sessions, the resolved URL is:

POST https://business.example.com/api/v2/checkout-sessions

Rules:

• endpoint MUST be a valid URL with scheme (https)
• endpoint SHOULD NOT have a trailing slash
• OpenAPI paths are relative and appended directly to endpoint
• Same resolution applies to MCP endpoints for JSON-RPC calls
• endpoint for A2A transport refers to the Agent Card URL for the agent

Capabilities

A capability is a feature within a service. It declares what functionality is supported and where to find documentation and schemas.

Capability Definition

Full capability declaration for platform-level discovery. Includes spec/schema URLs for agent fetching.

Name	Type	Required	Description
version	string	Yes	Entity version in YYYY-MM-DD format.
spec	string	Yes	URL to human-readable specification document.
schema	string	Yes	URL to JSON Schema defining this entity's structure and payloads.
id	string	No	Unique identifier for this entity instance. Used to disambiguate when multiple instances exist.
config	object	No	Entity-specific configuration. Structure defined by each entity's schema.
extends	OneOf[string, array]	No	Parent capability(s) this extends. Present for extensions, absent for root capabilities. Use array for multi-parent extensions.

Extensions

An extension is an optional module that augments another capability. Extensions use the extends field to declare their parent(s):

{
  "br.dev.bcp.shopping.fulfillment": [
    {
      "version": "2026-07-14",
      "spec": "https://bcp.dev.br/2026-07-14/specification/fulfillment",
      "schema": "https://bcp.dev.br/2026-07-14/schemas/shopping/fulfillment.json",
      "extends": "br.dev.bcp.shopping.checkout"
    }
  ]
}

Multi-Parent Extensions

Extensions MAY extend multiple parent capabilities by using an array:

{
  "br.dev.bcp.shopping.discount": [
    {
      "version": "2026-07-14",
      "spec": "https://bcp.dev.br/2026-07-14/specification/discount",
      "schema": "https://bcp.dev.br/2026-07-14/schemas/shopping/discount.json",
      "extends": ["br.dev.bcp.shopping.checkout", "br.dev.bcp.shopping.cart"]
    }
  ]
}

When an extension declares multiple parents:

• The extension MAY define different fields for each capability it extends (e.g., loyalty_earned for checkout, loyalty_preview for cart)
• See Intersection Algorithm for negotiation rules

Extensions can be:

• Official: br.dev.bcp.shopping.fulfillment extends br.dev.bcp.shopping.checkout
• Vendor: com.example.installments extends br.dev.bcp.shopping.checkout

Schema Composition

Extensions can add new fields and modify shared structures (e.g., discounts modify totals, fulfillment adds fulfillment to totals.type).

Requirements

• Transport definitions (OpenAPI/OpenRPC) MUST reference base schemas only. They MUST NOT enumerate fields or define payload shapes inline.
• Extensions MUST be self-describing. Each extension schema MUST declare the types it introduces and how it modifies base types using allOf composition.
• Platforms MUST resolve schemas client-side by fetching and composing base schemas with active extension schemas.

Extension Schema Pattern

Extension schemas define composed types using allOf. The $defs key MUST use the full parent capability name (reverse-domain format) to enable deterministic schema resolution:

{
  "$defs": {
    "discounts_object": { ... },
    "br.dev.bcp.shopping.checkout": {
      "title": "Checkout with Discount",
      "allOf": [
        {"$ref": "checkout.json"},
        {
          "type": "object",
          "properties": {
            "discounts": {
              "$ref": "#/$defs/discounts_object"
            }
          }
        }
      ]
    }
  }
}

Requirements:

• Extension schemas MUST have a $defs entry for each parent declared in extends
• The $defs key MUST match the parent's full capability name exactly

This convention ensures:

• Self-documenting: The schema declares exactly which parents it extends
• Deterministic resolution: The extends value maps directly to the $defs key
• Verifiable: Build-time checks can confirm each extends entry has a matching $defs key

Version Requirements

Extension schemas SHOULD declare a requires object (alongside name, title, description) to indicate the protocol and capability versions required for correct operation:

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://acme.com/ucp/schemas/loyalty.json",
  "name": "com.acme.shopping.loyalty",
  "title": "Acme Loyalty Points",
  "requires": {
    "protocol": { "min": "2026-01-23" },
    "capabilities": {
      "br.dev.bcp.shopping.checkout": { "min": "2026-06-01" }
    }
  },
  "$defs": {
    "br.dev.bcp.shopping.checkout": { ... }
  }
}

The schema author — not the profile publisher — declares version requirements. The profile publisher selects and advertises compatible versions in their profile.

Each constraint is an object with a required min (inclusive) and optional max (inclusive) version. When max is absent, there is no upper bound:

"requires": {
  "protocol": { "min": "2026-01-23", "max": "2026-09-01" },
  "capabilities": {
    "br.dev.bcp.shopping.checkout": { "min": "2026-06-01" }
  }
}

Keys in requires.capabilities MUST be a subset of the extension's $defs keys. If requires is present, platforms and businesses MUST verify the negotiated protocol version and capability versions satisfy the declared constraints during schema resolution. Incompatible extensions are excluded from the active capability set (see Resolution Flow). If requires is absent, the extension is assumed to be compatible with the versions declared by the profile.

Schema Resolution Convention

To validate payloads, implementations resolve extension schemas as follows:

1. Determine the root capability from the operation (e.g., checkout operations use br.dev.bcp.shopping.checkout)
2. For each active extension, resolve and apply its $defs[{root_capability}]

Example: A checkout response includes the discount extension.

• Root capability: br.dev.bcp.shopping.checkout
• Extension schema: discount.json
• Resolve: discount.json#/$defs/br.dev.bcp.shopping.checkout

Resolution Flow

Platforms MUST resolve schemas following this sequence:

1. Discovery: Fetch business profile from /.well-known/ucp
2. Negotiation: Compute capability intersection (see Intersection Algorithm)
3. Schema Fetch: Fetch base schema and all active extension schemas
4. Version Compatibility: For each fetched extension schema, if requires is present, verify the negotiated protocol version and capability versions satisfy the declared constraints. Exclude incompatible extensions and re-prune orphaned extensions (steps 3-4 of the Intersection Algorithm)
5. Compose: Merge schemas via allOf chains based on active extensions
6. Validate: Validate requests and responses against the composed schema

Profile Structure

Profile documents are machine-readable discovery documents. Businesses publish their profile at /.well-known/ucp; platforms publish their profile at the URI advertised in BCP-Agent.

A profile document is a JSON object with a required ucp member. The ucp member contains protocol metadata: protocol version, services, optional capabilities, and payment handlers.

For both business and platform profiles, ucp.version, ucp.services, and ucp.payment_handlers are required. The services and payment_handlers registries MUST be present even when empty. ucp.capabilities is optional and MAY be omitted, though useful commerce profiles normally advertise at least one capability.

Profiles MAY include public JSON Web Keys used for HTTP Message Signatures and signed webhooks. When a profile publishes signing keys, they MUST appear in the top-level keys[] array — the canonical BCP profile field that every BCP verifier reads. keys[] is a JWK Set per RFC 7517, so the same document is simultaneously a BCP profile and a valid JWK Set — which a signer can reuse as its Web Bot Auth key source. See Deployment Patterns for WBA Interop below.

Adding, rotating, or removing a key updates this single array. Removal is the security-critical case: a revoked or compromised key is not effectively revoked until it is absent from keys[].

BCP defines two well-known key types: EC (ECDSA P-256, P-384) and OKP (EdDSA Ed25519); the key-type, curve, and algorithm vocabularies are open and verifiers skip keys they do not recognize. See Message Signatures for key format, algorithms, lookup, and rotation.

Business Profile

Businesses publish their profile at /.well-known/ucp. An example:

{
  "ucp": {
    "version": "2026-07-14",
    "services": {
      "br.dev.bcp.shopping": [
        {
          "version": "2026-07-14",
          "spec": "https://bcp.dev.br/2026-07-14/specification/overview",
          "transport": "rest",
          "endpoint": "https://business.example.com/ucp/v1",
          "schema": "https://bcp.dev.br/2026-07-14/services/shopping/rest.openapi.json"
        },
        {
          "version": "2026-07-14",
          "spec": "https://bcp.dev.br/2026-07-14/specification/overview",
          "transport": "mcp",
          "endpoint": "https://business.example.com/ucp/mcp",
          "schema": "https://bcp.dev.br/2026-07-14/services/shopping/mcp.openrpc.json"
        },
        {
          "version": "2026-07-14",
          "spec": "https://bcp.dev.br/2026-07-14/specification/overview",
          "transport": "a2a",
          "endpoint": "https://business.example.com/.well-known/agent-card.json"
        },
        {
          "version": "2026-07-14",
          "spec": "https://bcp.dev.br/2026-07-14/specification/overview",
          "transport": "embedded",
          "schema": "https://bcp.dev.br/2026-07-14/services/shopping/embedded.openrpc.json"
        }
      ]
    },
    "capabilities": {
      "br.dev.bcp.shopping.checkout": [
        {
          "version": "2026-07-14",
          "spec": "https://bcp.dev.br/2026-07-14/specification/checkout",
          "schema": "https://bcp.dev.br/2026-07-14/schemas/shopping/checkout.json"
        }
      ],
      "br.dev.bcp.shopping.fulfillment": [
        {
          "version": "2026-07-14",
          "spec": "https://bcp.dev.br/2026-07-14/specification/fulfillment",
          "schema": "https://bcp.dev.br/2026-07-14/schemas/shopping/fulfillment.json",
          "extends": "br.dev.bcp.shopping.checkout"
        }
      ],
      "br.dev.bcp.shopping.discount": [
        {
          "version": "2026-07-14",
          "spec": "https://bcp.dev.br/2026-07-14/specification/discount",
          "schema": "https://bcp.dev.br/2026-07-14/schemas/shopping/discount.json",
          "extends": "br.dev.bcp.shopping.checkout"
        }
      ],
      "br.dev.bcp.common.identity_linking": [
        {
          "version": "2026-07-14",
          "spec": "https://bcp.dev.br/2026-07-14/specification/identity-linking",
          "schema": "https://bcp.dev.br/2026-07-14/schemas/common/identity_linking.json",
          "config": {
            "providers": {
              "com.example.idp": [
                { "type": "oauth2", "auth_url": "https://accounts.example.com/" }
              ]
            },
            "scopes": {
              "br.dev.bcp.shopping.order:read":   {},
              "br.dev.bcp.shopping.order:manage": {}
            }
          }
        }
      ]
    },
    "payment_handlers": {
      "com.example.processor_tokenizer": [
        {
          "id": "processor_tokenizer",
          "version": "2026-07-14",
          "spec": "https://example.com/specs/payments/processor_tokenizer",
          "schema": "https://example.com/specs/payments/merchant_tokenizer.json",
          "available_instruments": [
            {
              "type": "card",
              "constraints": {
                "brands": ["visa", "mastercard", "amex"]
              }
            }
          ],
          "config": {
            "type": "CARD",
            "tokenization_specification": {
              "type": "PUSH",
              "parameters": {
                "token_retrieval_url": "https://api.psp.example.com/v1/tokens"
              }
            }
          }
        }
      ]
    }
  },
  "keys": [
    {
      "kid": "poqkLGiymh_W0uP6PZFw-dvez3QJT5SolqXBCW38r0U",
      "kty": "OKP",
      "crv": "Ed25519",
      "x": "JrQLj5P_89iXES9-vFgrIy29clF9CC_oPPsw3c5D0bs",
      "use": "sig",
      "alg": "EdDSA"
    },
    {
      "kid": "business_2025",
      "kty": "EC",
      "crv": "P-256",
      "x": "qIVYZVLCrPZHGHjP17CTW0_-D9Lfw0EkjqF7xB4FivA",
      "y": "Mc4nN9LTDOBhfoUeg8Ye9WedFRhnZXZJA12Qp0zZ6F0",
      "use": "sig",
      "alg": "ES256"
    }
  ]
}

The business profile advertises the business's available transports, capabilities, payment handlers, and public verification keys. This example publishes signing keys in the canonical top-level keys[] array (an RFC 7517 JWK Set), so the same document is also a valid JWK Set — reusable as a Web Bot Auth key source. Every BCP verifier reads keys[], whether it resolved the key via BCP-Agent or via Signature-Agent.

A WBA-shape verifier reads keys[] from this profile only when the Signature-Agent header selects it with type=jwks_uri (or type=cimd) pointing at the profile URL. The default type=directory (when type is omitted) instead expects a signed directory document at /.well-known/http-message-signatures-directory, not a static profile, so it will not read keys[] from a static /.well-known/ucp. See Deployment Patterns for WBA Interop.

This example uses two keys. Whether a deployment needs one or two depends on the algorithms its counterparties accept — many need only one; see Signature Algorithms. The two keys here:

• An Ed25519 key (OKP) for HTTP transport identity, WBA-compatible. The kid is the JWK SHA-256 Thumbprint per RFC 7638.
• An ECDSA P-256 key (EC) for AP2 mandate signing (ap2.merchant_authorization).

A business that does not interact with AP2 or WBA may publish a single ES256 key in keys[] (the universal baseline). See Key Discovery for key lookup and resolution, Deployment Patterns for WBA Interop for hosting choices, and Message Signatures for signing mechanics.

Businesses that support older protocol versions SHOULD include a supported_versions object mapping each older version to a version-specific profile URI. See Protocol Version for details.

Platform Profile

Platform profiles are similar and include signing keys for capabilities requiring cryptographic verification. Capabilities MAY include a config object for capability-specific settings (e.g., callback URLs, feature flags). An example:

{
  "ucp": {
    "version": "2026-07-14",
    "services": {
      "br.dev.bcp.shopping": [
        {
          "version": "2026-07-14",
          "spec": "https://bcp.dev.br/2026-07-14/specification/overview",
          "transport": "rest",
          "schema": "https://bcp.dev.br/2026-07-14/services/shopping/rest.openapi.json",
          "endpoint": "https://platform.example.com/ucp/v1"
        }
      ]
    },
    "capabilities": {
      "br.dev.bcp.shopping.checkout": [
        {
          "version": "2026-07-14",
          "spec": "https://bcp.dev.br/2026-07-14/specification/checkout",
          "schema": "https://bcp.dev.br/2026-07-14/schemas/shopping/checkout.json"
        }
      ],
      "br.dev.bcp.shopping.fulfillment": [
        {
          "version": "2026-07-14",
          "spec": "https://bcp.dev.br/2026-07-14/specification/fulfillment",
          "schema": "https://bcp.dev.br/2026-07-14/schemas/shopping/fulfillment.json",
          "extends": "br.dev.bcp.shopping.checkout"
        }
      ],
      "br.dev.bcp.shopping.order": [
        {
          "version": "2026-07-14",
          "spec": "https://bcp.dev.br/2026-07-14/specification/order",
          "schema": "https://bcp.dev.br/2026-07-14/schemas/shopping/order.json",
          "config": {
            "webhook_url": "https://platform.example.com/webhooks/ucp/orders"
          }
        }
      ],
      "br.dev.bcp.common.identity_linking": [
        {
          "version": "2026-07-14",
          "spec": "https://bcp.dev.br/2026-07-14/specification/identity-linking",
          "schema": "https://bcp.dev.br/2026-07-14/schemas/common/identity_linking.json"
        }
      ]
    },
    "payment_handlers": {
      "com.google.pay": [
        {
          "id": "gpay_1234",
          "version": "2024-12-03",
          "spec": "https://developers.google.com/merchant/ucp/guides/gpay-payment-handler",
          "schema": "https://pay.google.com/gp/p/ucp/2026-01-11/schemas/gpay_config.json"
        }
      ],
      "dev.shopify.shop_pay": [
        {
          "id": "shop_pay_1234",
          "version": "2026-07-14",
          "spec": "https://shopify.dev/ucp/shop-pay-handler",
          "schema": "https://shopify.dev/ucp/schemas/shop-pay-config.json",
          "available_instruments": [
            {"type": "shop_pay"}
          ]
        }
      ],
      "com.example.processor_tokenizer": [
        {
          "id": "processor_tokenizer",
          "version": "2026-07-14",
          "spec": "https://example.com/specs/payments/processor_tokenizer-payment",
          "schema": "https://example.com/schemas/payments/delegate-payment.json",
          "available_instruments": [
            {"type": "card", "constraints": {"brands": ["visa", "mastercard"]}}
          ]
        }
      ]
    }
  },
  "keys": [
    {
      "kid": "platform_2025",
      "kty": "EC",
      "crv": "P-256",
      "x": "MKBCTNIcKUSDii11ySs3526iDZ8AiTo7Tu6KPAqv7D4",
      "y": "4Etl6SRW2YiLUrN5vfvVHuhp7x8PxltmWWlbbM4IFyM",
      "use": "sig",
      "alg": "ES256"
    }
  ]
}

Platform Advertisement on Request

Platforms MUST communicate their profile URI with each request to enable capability negotiation.

HTTP Transport: Platforms MUST use Dictionary Structured Field syntax (RFC 8941) in the BCP-Agent header:

POST /checkout HTTP/1.1
BCP-Agent: profile="https://agent.example/profiles/shopping-agent.json"
Content-Type: application/json

{"line_items": [...]}

MCP Transport: Platforms MUST include a meta object containing request metadata:

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "create_checkout",
    "arguments": {
      "meta": {
        "ucp-agent": {
          "profile": "https://agent.example/profiles/shopping-agent.json"
        }
      },
      "checkout": {
        "line_items": [...]
      }
    }
  },
  "id": 1
}

Negotiation Protocol

Platform Requirements

1. Profile Advertisement: Platforms MUST include their profile URI in every request using the transport-appropriate mechanism.
2. Discovery: Platforms MAY fetch the business profile from /.well-known/ucp before initiating requests. If fetched, platforms SHOULD cache the profile according to HTTP cache-control directives.
3. Namespace Validation: Before fetching, platforms MUST validate that each capability's schema URL origin matches its namespace authority (see Authority Binding) and MUST reject capabilities that fail this binding.
4. Schema Resolution: Platforms MUST fetch and compose schemas for negotiated capabilities before making requests.

Business Requirements

1. Profile Resolution: Upon receiving a request with a platform profile URI, businesses MUST fetch and validate the platform profile unless already cached. Because businesses negotiate by capability name and serve their own schemas, they do not normally dereference platform-declared schema URLs; they SHOULD nonetheless verify the namespace binding (see Authority Binding) as defense in depth.
2. Capability Intersection: Businesses MUST compute the intersection of platform and business capabilities.
3. Extension Validation: Extensions without their parent capability in the intersection MUST be excluded.
4. Response Requirements: Businesses MUST include the ucp field in every response containing:
   • version: The BCP version used to process the request
   • capabilities: Array of active capabilities for this response

Intersection Algorithm

The capability intersection algorithm determines which capabilities are active for a session:

1. Compute intersection: For each business capability, include it in the result if a platform capability with the same name exists.

2. Select version: For each capability in the intersection, compute the set of version strings present in both the business and platform arrays. If the set is non-empty, select the highest version (latest date). If the set is empty (no mutual version), exclude the capability from the intersection.

3. Prune orphaned extensions: Remove any capability where extends is set but none of its parent capabilities are in the intersection.

   • For single-parent extensions (extends: "string"): parent must be present
   • For multi-parent extensions (extends: ["a", "b"]): at least one parent must be present

4. Repeat pruning: Continue step 3 until no more capabilities are removed (handles transitive extension chains).

The result is the set of capabilities both parties support at mutually compatible versions, with extension dependencies satisfied.

Error Handling

BCP negotiation can fail in two ways:

1. Discovery failure: The business cannot fetch or parse the platform's profile.

2. Negotiation failure: The provided profile is valid but capability intersection is empty or versions are incompatible.

Discovery failures are transport errors — the required inputs could not be retrieved or were malformed. Negotiation failures are business outcomes — the handler executed on the provided inputs and reported the result in the BCP response:

• Discovery or version failure → transport error with optional continue_url
• Capability negotiation failure → BCP response with optional continue_url

Error Codes

Negotiation Errors:

Code	Description	REST	MCP
invalid_profile_url	Profile URL is malformed, missing, or unresolvable	400	-32001
profile_unreachable	Resolved URL but fetch failed (timeout, non-2xx)	424	-32001
profile_malformed	Fetched content is not valid JSON or violates schema	422	-32001
version_unsupported	Platform's protocol version not supported	422	-32001
capabilities_incompatible	No compatible capabilities in intersection	200	result

Signature Errors:

Code	Description	REST	MCP
signature_missing	Required signature header/field not present	401	-32000
signature_invalid	Signature verification failed	401	-32000
key_not_found	Key ID not found in signer's published key set	401	-32000
digest_mismatch	Body digest doesn't match Content-Digest header	400	-32600
algorithm_unsupported	Signature algorithm not supported	400	-32600

See Message Signatures for signature verification details.

Protocol Errors:

HTTP	Description	MCP
401	Authentication required or credentials invalid	-32000
403	Authenticated but insufficient permissions	-32000
409	Idempotency key reused with different payload	-32000
429	Too many requests	-32000
500	Unexpected server error	-32603
503	Server temporarily unable to handle requests	-32000

For MCP over HTTP, the HTTP status code is the primary signal; the JSON-RPC error.code provides a secondary signal. Both transports SHOULD include Retry-After header (REST) or error.data.retry_after (MCP) for 429 and 503 responses.

The Embedded Protocol uses the same JSON-RPC error codes for peer-to-peer communication between host and embedded context. Server-specific scenarios (rate limiting, idempotency) do not apply to the embedded transport. See Embedded Protocol — Response Handling for the full error handling specification.

The continue_url Field

When BCP negotiation fails, continue_url provides a fallback web experience. Businesses SHOULD provide the most contextually relevant URL:

• For checkout operations: link to the cart or checkout page
• For catalog operations: link to the product or search results
• As a fallback: link to the storefront homepage

This enables graceful degradation—agents can redirect buyers to complete their task through the standard web interface.

Transport Bindings

RESTMCP

Discovery Failure (424):

HTTP/1.1 424 Failed Dependency
Content-Type: application/json

{
  "code": "profile_unreachable",
  "content": "Unable to fetch agent profile: connection timeout",
  "continue_url": "https://merchant.com/cart"
}

Version Unsupported (422):

HTTP/1.1 422 Unprocessable Content
Content-Type: application/json

{
  "code": "version_unsupported",
  "content": "Protocol version 2026-01-12 is not supported. This business supports versions 2026-01-11 and 2026-01-23.",
  "continue_url": "https://merchant.com/cart"
}

Capabilities Incompatible (200):

HTTP/1.1 200 OK
Content-Type: application/json

{
  "ucp": {
    "version": "2026-07-14",
    "status": "error",
    "capabilities": {}
  },
  "messages": [
    {
      "type": "error",
      "code": "capabilities_incompatible",
      "content": "No compatible capabilities in the intersection",
      "severity": "unrecoverable"
    }
  ],
  "continue_url": "https://merchant.com"
}

Protocol Error — Rate Limit (429):

HTTP/1.1 429 Too Many Requests
Retry-After: 60

Protocol Error — Unauthorized (401):

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer realm="ucp"

Protocol errors use standard HTTP status codes and headers. Response bodies are optional.

Discovery Failure (JSON-RPC error):

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32001,
    "message": "BCP discovery failed",
    "data": {
      "code": "profile_unreachable",
      "content": "Unable to fetch agent profile: connection timeout",
      "continue_url": "https://merchant.com/cart"
    }
  }
}

Version Unsupported (JSON-RPC error):

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32001,
    "message": "Protocol version not supported",
    "data": {
      "code": "version_unsupported",
      "content": "Protocol version 2026-01-12 is not supported. This business supports versions 2026-01-11 and 2026-01-23.",
      "continue_url": "https://merchant.com/cart"
    }
  }
}

Capabilities Incompatible (JSON-RPC result):

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "structuredContent": {
      "ucp": {
        "version": "2026-07-14",
        "status": "error"
      },
      "messages": [
        {
          "type": "error",
          "code": "capabilities_incompatible",
          "content": "No compatible capabilities in the intersection",
          "severity": "unrecoverable"
        }
      ],
      "continue_url": "https://merchant.com"
    },
    "content": [
      {"type": "text", "text": "{\"ucp\":{…},…}"}
    ]
  }
}

Protocol Error — Rate Limit (JSON-RPC error):

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32000,
    "message": "Rate limit exceeded",
    "data": {
      "retry_after": 60
    }
  }
}

Protocol Error — Unauthorized (JSON-RPC error):

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32000,
    "message": "Unauthorized"
  }
}

When using Streamable HTTP transport, servers MUST return the corresponding HTTP status code (e.g., 429 for rate limit) alongside the JSON-RPC error. The HTTP status code is the primary signal for error type.

Capability Declaration in Responses

The capabilities registry in responses indicates active capabilities:

{
  "ucp": {
    "version": "2026-07-14",
    "capabilities": {
      "br.dev.bcp.shopping.checkout": [
        {"version": "2026-07-14"}
      ],
      "br.dev.bcp.shopping.fulfillment": [
        {"version": "2026-07-14"}
      ]
    },
    "payment_handlers": {
      "com.example.processor_tokenizer": [
        {"id": "processor_tokenizer", "version": "2026-07-14", "available_instruments": [{"type": "card"}]}
      ]
    }
  },
  "id": "checkout_123",
  "status": "incomplete",
  "currency": "USD",
  "line_items": [ ... ],
  "totals": [ ... ],
  "links": [ ... ]
}

Response Capability Selection

Businesses MUST include in ucp.capabilities only the capabilities that are:

1. In the negotiated intersection for this session, AND
2. Relevant to this response's operation type

Root Capability Relevance:

A root capability is relevant if it matches the operation type:

• create_checkout / update_checkout / complete_checkout → br.dev.bcp.shopping.checkout
• create_cart / update_cart → br.dev.bcp.shopping.cart
• Order webhooks → br.dev.bcp.shopping.order

Extension Relevance:

An extension is relevant if any of its extends values matches a relevant root capability.

Selection Examples:

Response Type	Includes	Does NOT Include
Checkout	checkout, discount, fulfillment	cart, order
Cart	cart, discount	checkout, fulfillment, order
Order	order	checkout, cart, discount

Identity & Authentication

BCP profiles serve dual purpose: they declare a party's capabilities for negotiation (see Profile Structure) and publish signing keys for identity verification — enabling both capability negotiation and cryptographic authentication from a single document.

Businesses publish their profile at /.well-known/ucp as the discovery entry point — platforms fetch it to determine protocol support, locate endpoints, and negotiate capabilities. Platforms advertise their profile URL per-request via the BCP-Agent header, enabling businesses to negotiate capabilities and verify identity. This design enables permissionless onboarding — any platform with a discoverable profile can interact with any business without prior registration.

Web Bot Auth interop. Signers opting into WBA-shape signatures additionally emit a Signature-Agent header advertising their keys. See Identity Resolution Algorithm for how verifiers resolve identity and Message Signatures — WBA Interop for the signature shape.

Authentication Mechanisms

Businesses SHOULD authenticate platforms to prevent impersonation and ensure message integrity. BCP is compatible with multiple authentication mechanisms:

• API Keys — Pre-shared secrets exchanged out-of-band
• OAuth 2.0 — Client credentials or other OAuth flows
• mTLS — Mutual TLS with client certificates
• HTTP Message Signatures — Cryptographic signatures per RFC 9421 (see Message Signatures for full specification)

HTTP Message Signatures enable permissionless onboarding — businesses can verify platforms by their advertised public keys without negotiating shared secrets. The other mechanisms require prior credential exchange and imply a pre-established relationship.

Business-to-platform webhooks MUST be signed. See Message Signatures — When Signatures Apply.

Identity Binding

Regardless of authentication mechanism, verifiers MUST ensure the authenticated identity is consistent with the BCP-Agent header:

• HTTP Message Signatures — The signer's profile (from BCP-Agent) is verified by signature validation; no additional check needed.
• API keys / OAuth / mTLS — Verifiers MUST confirm the authenticated principal is authorized to act on behalf of the profile identified in BCP-Agent. Reject requests where the authenticated identity and claimed profile conflict.

Key Discovery

Both parties publish public keys in their BCP profile. Platforms fetch the business profile at /.well-known/ucp; businesses fetch the platform profile from the BCP-Agent header (or Signature-Agent header when Web Bot Auth interop is in use). The same profile that provides capabilities also provides verification keys — this is BCP's key resolution mechanism for RFC 9421 HTTP Message Signatures.

See Profile Structure for the publishing contract (the canonical top-level keys[] JWK Set). Both resolution paths read the same list:

• Resolved via BCP-Agent (default BCP key lookup) — read keys[].
• Resolved via Signature-Agent (Web Bot Auth, optional) — read keys[]; the cimd/directory variants reach the JWK Set through their own documents.

For the full verifier algorithm — capability-based key resolution, profile fetching, and covered-component enforcement — see Identity Resolution Algorithm below. For key format (JWK), supported algorithms, key rotation procedures, and the Web Bot Auth interop signature shape, see Message Signatures.

Profile Requirements

Hosting

Both profiles must be reliably hosted. An unreliable or misconfigured profile endpoint may prevent the other party from processing requests.

1. Profiles MUST be served over HTTPS.
2. Profile endpoints MUST NOT use redirects (3xx).
3. Profile responses MUST include a Cache-Control header with public and max-age of at least 60 seconds. Profiles MUST NOT be served with private, no-store, or no-cache directives.

Profiles represent a party's stable identity and capabilities. Profile URLs are expected to remain consistent across requests and not contain per-transaction or per-session configuration — the caching policy above enforces this by requiring shared cache support with a minimum TTL.

Fetching

Businesses fetch platform profiles to perform capability negotiation and verify identity. BCP defines best practices that enable permissionless onboarding, but businesses retain full control over their access policies and MAY enforce additional rules based on established trust, observed behavior, or operational requirements.

Businesses SHOULD maintain a registry of pre-approved platforms — platforms whose profiles have been validated and whose trust is established through out-of-band mechanisms (API key, OAuth credential, mTLS certificate, or prior vetting). Known platforms can be served efficiently based on cached identity and capabilities, and are not subject to discovery budget constraints.

When a platform is not recognized, it triggers dynamic profile discovery. Businesses SHOULD establish a fixed discovery footprint so that resource consumption for resolving unrecognized platforms remains constant regardless of how many platforms request access. Strategies include:

• Fixed-size profile cache (e.g., LRU) — bounds memory regardless of the number of unique profile URLs encountered
• Global rate limit on discovery fetches — bounds outbound network without requiring per-origin state tracking
• Backoff on repeated failures — reduces retries to persistently unavailable or malicious profile endpoints
• Asynchronous discovery — defer profile resolution by responding with a 503 status code and Retry-After header, and resolve the profile in the background; when the platform retries, the validated profile is cached and capability negotiation proceeds synchronously

These rules apply to any URL dereferenced during identity resolution — the profile, and any jwks_uri or CIMD document a verifier follows:

1. Implementations MUST reject URLs not served over HTTPS.
2. Implementations MUST NOT follow redirects (3xx).
3. Implementations SHOULD enforce connect and response timeouts.
4. Implementations SHOULD cache profiles with a minimum TTL floor of 60 seconds, regardless of the origin's Cache-Control headers.
5. Implementations MAY refresh profiles asynchronously using stale-while-revalidate semantics.
6. On signature verification failure with an unknown kid, implementations SHOULD force-refresh the cached profile once — but MUST NOT do so more than once per TTL floor per origin.
7. Implementations MUST reject URLs that resolve to special-use IP addresses (RFC 6890 — loopback, link-local including the cloud-metadata address 169.254.169.254, private, and other reserved ranges), except a loopback target when the verifier itself runs on the same loopback interface (local development). Verifiers SHOULD validate the resolved address, not just the hostname (to resist DNS rebinding), and SHOULD NOT dereference a URL contained within a fetched document (e.g. a CIMD jwks_uri) that resolves to such an address.
8. Implementations SHOULD bound the response body size to prevent unbounded-response resource exhaustion. A BCP profile is an identity/capability manifest, not a data payload (documented profiles are under 5 KiB); since the schema sets no size limit, this bound is a deployment guard, and verifiers SHOULD set it no lower than 128 KiB so it does not reject conformant profiles.

If a profile cannot be fetched (timeout, DNS failure, 5xx) or fails validation (invalid schema, signing keys, signature mismatch), businesses MUST reject the request with an appropriate error and status code (see Error Handling).

Deployment Patterns for WBA Interop

A BCP profile carrying a top-level keys[] array is a valid RFC 7517 JWK Set, which a signer can optionally reuse as its Web Bot Auth key source. The Signature-Agent header's type parameter selects how a verifier resolves the advertised keys. The parameter and its jwks_uri/cimd/directory values are defined in §4.1 of draft-meunier-webbotauth-httpsig-directory-00. Each variant can stand alone or point back at the BCP profile:

• type=jwks_uri — the member value is a JWK Set URL, fetched directly. Point it at the BCP profile URL and the profile's keys[] serves as the JWK Set: one document is both profile and key source. Integrity derives from TLS to the profile origin, with no per-key self-signature. Set type=jwks_uri explicitly: omitting type defaults to directory (below), which expects a signed directory, not a static profile.

Signature-Agent: sig1="https://platform.example/.well-known/ucp";type=jwks_uri

• type=cimd — the member value is a Client ID Metadata Document (draft-ietf-oauth-client-id-metadata-document) whose jwks_uri MAY point back at the BCP profile. Use when a counterparty consumes CIMD-shaped agent identity.

Signature-Agent: sig1="https://platform.example/agent";type=cimd

• type=directory (default) — when type is omitted or set to directory, the member value is an origin (not a full URL): the verifier appends the registered well-known path (/.well-known/http-message-signatures-directory) to that origin and fetches a signed directory there. Its format, per-key self-signatures, and media type are defined by the directory draft §5.2.

Signature-Agent: sig1="https://platform.example"  # type omitted -> directory
Signature-Agent: sig1="https://platform.example";type=directory  # explicit

Identity Resolution Algorithm

BCP and Web Bot Auth define two key-resolution mechanisms. Which one a verifier uses is chosen by verifier capability and the headers present, not by the signature's tag — the tag is a hint, not a gate. Default BCP key lookup (BCP-Agent) is supported by every BCP verifier and works for any BCP signature; Web Bot Auth key lookup (Signature-Agent) is an optional, additive layer.

A request MAY carry multiple signatures per RFC 9421 §4.3. Verifiers attempt each signature independently; the request is authenticated when at least one signature verifies. The algorithm below processes a single signature.

1. Resolve the signing key. A verifier uses a resolution mechanism it supports whose header is present:
   • BCP-Agent — default BCP key lookup, supported by every BCP verifier. Resolve the BCP-Agent profile URL and read keys[]. This path applies to BCP signatures that are untagged (default BCP) or carry tag="web-bot-auth" (the dual-audience shape); the verifier resolves them via BCP-Agent, treats signature-agent as an ordinary covered component, and need not implement Web Bot Auth key discovery. (Verifying a dual-audience signature does still require supporting the key's algorithm — whichever the signer used, per Signature Algorithms — and RFC 9421 §2.1.2 Dictionary-member component selection to cover signature-agent;key="<label>".) Signatures with tags other than web-bot-auth are skipped unless BCP defines or explicitly accepts that tag.
   • Signature-Agent — Web Bot Auth key lookup, OPTIONAL (WBA-aware verifiers). For a signature carrying tag="web-bot-auth", a WBA-aware verifier MAY instead resolve via the Signature-Agent member, parsed per the Signature-Agent parsing rules. Such a signature MUST satisfy the WBA agent-signature requirements in draft-meunier-webbotauth-httpsig-protocol-00 §4.2 (see WBA Interop for the signer-side shape). The member value MUST be an HTTPS URL. Its type selects resolution: jwks_uri and cimd reach the keys through the signer's profile and are resolved by the steps below; the directory mechanism is defined by the directory draft (see Deployment Patterns). data: URI inline form is out of scope for BCP-WBA interop. Skip this signature if no mechanism the verifier supports can resolve its key — the required header is absent, no Signature-Agent member matches the signature label, the URL is non-HTTPS, or the tag is scoped to a purpose this verifier does not handle.
2. Fetch the document per §Fetching. If the fetch fails (DNS error, network failure, non-2xx response, parse failure), skip this signature.
3. Locate the key list. The profile's top-level keys[] (RFC 7517 JWK Set) when resolved via BCP-Agent or via Signature-Agent type=jwks_uri; for type=cimd, dereference the document's jwks_uri to obtain the JWK Set. Integrity derives from TLS to the resolved origin.
4. Match the signature's keyid to a kid in the resolved key list. When resolving, skip keys not usable for signature verification: any key marked use:"enc", or whose key_ops is present but does not include "verify" (RFC 7517 §4.2, §4.3). Keys that set use:"sig" or omit both members remain eligible. Skip this signature if no eligible key matches. For WBA-shape signatures (tag="web-bot-auth"), the verifier MUST also confirm keyid equals the RFC 7638 SHA-256 thumbprint of the matched JWK — the WBA architecture draft §4.2 requires this, binding the advertised key identity to its bytes. If it fails, skip this signature.
5. Enforce covered-component requirements, in every regime. Independent of tag and transport, the signature MUST cover the request target (@method, @authority, @path; @query when a query string is present), the body when present (content-digest, content-type), and each of these request headers when present: ucp-agent, signature-agent, idempotency-key (a closed set — a header added to BCP later is gate-required only if its defining section says so). If any such component is absent from the signature's covered set, skip this signature — a target, body, or header the signature does not cover is treated as unsigned. This prevents a signature satisfying only Web Bot Auth's minimal covered set (@authority, signature-agent) from authenticating a BCP request whose body, method, or path is unbound. (Whether a request must carry Idempotency-Key at all is a binding-level rule, separate from this coverage check.)
6. Verify the signature using the matched key. The signing algorithm is derived from the JWK's kty/crv. If the verifier does not support the matched key's kty, crv, or alg, skip this signature; it yields algorithm_unsupported if no other signature authenticates the request.

The request MUST be rejected (key_not_found, algorithm_unsupported, or related error) only when every signature has been skipped or fails verification.

Authenticated identity. When a signature verifies, the authenticated signer is identified by the URL that supplied the verifying key — the Signature-Agent URL for WBA-shape signatures, the BCP-Agent URL for default BCP signatures. Both URLs may be present in the same request; the identity attached to the request is determined by which signature verified, not by which headers were sent. When multiple signatures verify, each identifies the signer only as the URL that supplied its key — a key resolved via Signature-Agent proves control of that key source, not of the BCP-Agent profile (whose URL is merely a signed header value). Implementations MUST treat the request as a single authenticated identity only when those URLs are the same after normalization; otherwise they are distinct identities and policy decides whether either suffices.

This rule governs HTTP transport identity. Payload-layer assertions (e.g., AP2 mandate JWTs carried in the request body) have their own identity binding and key-resolution rules; see AP2 Mandates.

Payment Architecture

BCP adopts a decoupled architecture for payments to solve the "N-to-N" complexity problem between platforms, businesses, and payment credential providers. This design separates Payment Instruments (what is accepted) from Payment Handlers (the specifications for how instruments are processed), ensuring security and scalability.

Security and Trust Model

The payment architecture is built on a "Trust-by-Design" philosophy. It assumes that while the business and payment credential provider have a trusted legal relationship, the platform (Client) acts as an intermediary that SHOULD NOT touch raw financial credentials.

The Trust Triangle

1. Business ↔ Payment Credential Provider: A pre-existing legal and technical relationship. The business holds API keys and a contract with the payment credential provider.
2. Platform ↔ Payment Credential Provider: The platform interacts with the payment credential provider's interface (e.g., an iframe or API) to tokenize data but is not the "owner" of the funds.
3. Platform ↔ Business: The platform passes the result (a token or mandate) to the business to finalize the order.

Enhanced Security for Autonomous Commerce

For scenarios requiring cryptographic proof of user authorization (e.g., autonomous AI agents), BCP supports the AP2 Mandates Extension (br.dev.bcp.shopping.ap2_mandate). This optional extension provides non-repudiable authorization through verifiable digital credentials.

See Transaction Integrity and AP2 Mandates Extension for details on when and how to use this extension.

Credential Flow & PCI Scope

To minimize compliance overhead (PCI-DSS):

1. Unidirectional Flow: Credentials flow Platform → Business only. Businesses MUST NOT echo credentials back in responses.
2. Opaque Credentials: Platforms handle tokens (such as network tokens), encrypted payloads, or mandates, not raw PANs.
3. Handler ID Routing: The handler_id in the payload ensures the business knows exactly which payment credential provider key to use for decryption/charging, preventing key confusion attacks.

Roles & Responsibilities: Who Implements What?

A common source of confusion is the division of labor. The BCP payment model splits responsibilities as follows:

Role	Responsibility	Action
Payment Credential Provider	Defines the Spec	Creates the Handler Definition. They publish the "Blueprint" (JSON Schemas) that dictates how to tokenize a card and what config inputs are needed. Example: "Here is the schema for the 'com.psp-x.tokenization' handler."
Business	Configures the Handler	Selects the Handler they want to use and provides their specific Configuration (Public Keys, Merchant IDs) in the BCP Checkout Response. Example: "I accept Visa using 'com.psp-x.tokenization' with this Publishable Key."
Platform	Executes the Protocol	Reads the business's config and executes the logic defined by the payment credential provider's Spec to acquire a token. Example: "I see the Business uses a payment credential provider. I will call the provider's SDK with the Business's Key to get a token."

Payment in the Checkout Lifecycle

When payment is required, the payment process follows a standard 3-step lifecycle within BCP: Negotiation, Acquisition, and Completion.

1. Negotiation (Business → Platform): The business advertises available payment handlers in their BCP profile. This tells the platform how to pay (e.g., "Use this specific payment credential provider endpoint with this public key").
2. Acquisition (Platform ↔ Payment Credential Provider): The platform executes the handler's logic. This happens client-side or agent-side, directly with the payment credential provider (e.g., exchanging credentials for a network token). The business is not involved, ensuring raw data never touches the business's frontend API.
3. Completion (Platform → Business): The platform submits the opaque credential (token) to the business. The business uses it to capture funds via their backend integration with the payment credential provider.

Payment Handlers

Payment Handlers are specifications (not entities) that define how payment instruments are processed. They are the contract that binds the three participants together.

Important distinction:

• Payment Credential Provider = The participant (entity like Google Pay, Shop Pay)
• Payment Handler = The specification the provider authors (e.g., com.google.pay, dev.shopify.shop_pay)

Payment handlers allow for a variety of different payment instruments and token-types to be supported, including network tokens. They are standardized definitions typically authored by payment credential providers or the BCP governing body.

Dynamic Filtering: Businesses MUST filter the handlers list based on the context of the cart (e.g., removing "Buy Now Pay Later" for subscription items, or filtering regional methods based on shipping address).

Available Instrument Resolution: Within each active handler, both the platform and the business independently advertise available_instruments — the set of instrument types and constraints each party supports. The business is responsible for resolving these into an authoritative value in the checkout response. The platform's declaration (from its profile) signals what it can handle; the business intersects that with its own business_schema declaration and cart context, then returns the resolved result. Platforms MUST treat the available_instruments in the response as authoritative for that checkout. See the Payment Handler Guide for the full resolution semantics.

Instrument Cardinality: A checkout submission MUST contain exactly one payment instrument unless the br.dev.bcp.shopping.split_payments capability is active. Businesses MUST reject submissions that violate this constraint with a payment_failed error in messages[]. See Split Payments (not included in this BCP release) for the extension that relaxes this constraint.

Implementation Scenarios

The following scenarios illustrate how different payment handlers and instruments are negotiated and executed using concrete data examples.

Scenario A: Digital Wallet

In this scenario, the platform identifies a payment credential provider (e.g., com.google.pay, dev.shopify.shop_pay) and uses their API to acquire an encrypted payment token.

1. Business Advertisement (Response from Create Checkout)

{
  "version": "2026-07-14",
  "payment_handlers": {
      "com.google.pay": [
        {
          "id": "8c9202bd-63cc-4241-8d24-d57ce69ea31c",
          "version": "2026-07-14",
          "config": {
            "api_version": 2,
            "api_version_minor": 0,
            "environment": "TEST",
            "merchant_info": {
              "merchant_name": "Example Merchant",
              "merchant_id": "01234567890123456789",
              "merchant_origin": "checkout.merchant.com"
            },
            "allowed_payment_methods": [
              {
                "type": "CARD",
                "parameters": {
                  "allowed_auth_methods": ["PAN_ONLY"],
                  "allowed_card_networks": ["VISA", "MASTERCARD"]
                },
                "tokenization_specification": {
                  "type": "PAYMENT_GATEWAY",
                  "parameters": {
                    "gateway": "example",
                    "gatewayMerchantId": "exampleGatewayMerchantId"
                  }
                }
              }
            ]
          }
        }
      ],
      "dev.shopify.shop_pay": [
        {
          "id": "shop_pay_1234",
          "version": "2026-07-14",
          "available_instruments": [
            {"type": "shop_pay"}
          ],
          "config": {
            "shop_id": "shopify-559128571",
            "environment": "production"
          }
        }
      ]
    }
}

2. Token Execution (Platform Side)

The platform recognizes com.google.pay or dev.shopify.shop_pay. It passes the config into the respective handler API. The handler returns the encrypted token data.

3. Complete Checkout (Request to Business)

The Platform wraps the payment handler response into a payment instrument.

POST /checkout-sessions/{id}/complete

{
  "payment": {
    "instruments": [
      {
        "id": "pm_1234567890abc",
        "handler_id": "8c9202bd-63cc-4241-8d24-d57ce69ea31c",
        "type": "card",
        "selected": true,
        "display": {
          "brand": "visa",
          "last_digits": "4242"
        },
        "billing_address": {
          "street_address": "123 Main Street",
          "extended_address": "Suite 400",
          "address_locality": "Charleston",
          "address_region": "SC",
          "postal_code": "29401",
          "address_country": "US",
          "first_name": "Jane",
          "last_name": "Smith"
        },
        "credential": {
          "type": "PAYMENT_GATEWAY",
          "token": "{\"signature\":\"...\",\"protocolVersion\":\"ECv2\"...}"
        }
      }
    ]
  },
  "signals": {
    "br.dev.bcp.buyer_ip": "203.0.113.42",
    "br.dev.bcp.user_agent": "Mozilla/5.0 ..."
  }
}

Scenario B: Direct Tokenization with Challenge (SCA)

In this scenario, the platform uses a generic tokenizer to request a session token or network tokens. The bank requires Strong Customer Authentication (SCA/3DS), forcing the business to pause completion and request a challenge.

1. Business Advertisement

{
  "version": "2026-07-14",
  "payment_handlers": {
    "com.example.tokenizer": [
        {
          "id": "merchant_tokenizer",
          "version": "2026-07-14",
          "spec": "https://example.com/specs/tokenizer",
          "schema": "https://example.com/schemas/tokenizer.json",
          "available_instruments": [
            {
              "type": "card",
              "constraints": {
                "brands": ["visa", "mastercard"]
              }
            }
          ],
          "config": {
            "token_url": "https://api.psp.com/tokens",
            "public_key": "pk_123"
          }
        }
      ]
  }
}

2. Token Execution (Platform Side)

The platform calls https://api.psp.com/tokens which identity SHOULD have previous legal binding connection with them and receives tok_visa_123 (which could represent a vaulted card or network token).

3. Complete Checkout (Request to Business)

POST /checkout-sessions/{id}/complete

{
  "payment": {
    "instruments": [
      {
        "handler_id": "merchant_tokenizer",
        // ... more instrument required field
        "credential": { "token": "tok_visa_123" }
      }
    ]
  },
  "signals": {
    "br.dev.bcp.buyer_ip": "203.0.113.42",
    "br.dev.bcp.user_agent": "Mozilla/5.0 ..."
  }
}

4. Challenge Required (Response from Business)

The business attempts the charge, but the PSP returns a "Soft Decline" requiring 3DS.

HTTP/1.1 200 OK

{
  "status": "requires_escalation",
  "messages": [{
    "type": "error",
    "code": "requires_3ds",
    "content": "bank requires verification.",
    "severity": "requires_buyer_input"
  }],
  "continue_url": "https://psp.com/challenge/123"
}

The platform MUST now open continue_url in a WebView/Window for the user to complete the bank check, then retry the completion.

Scenario C: Autonomous Agent (AP2)

This scenario demonstrates the Recommended Flow for Agents. Instead of a session token, the agent generates cryptographic mandates.

1. Business Advertisement

{
  "version": "2026-07-14",
  "payment_handlers": {
    "br.dev.bcp.ap2_mandate_compatible_handlers": [
        {
          "id": "ap2_234352",
          "version": "2026-07-14",
          "spec": "https://example.com/specs/ap2-handler",
          "schema": "https://example.com/schemas/ap2-handler.json",
          "available_instruments": [
            {"type": "ap2_mandate"}
          ]
        }
      ]
  }
}

2. Agent Execution

The agent cryptographically signs objects using the user's private key on a non-agentic surface.

3. Complete Checkout

POST /checkout-sessions/{id}/complete

{
  "payment": {
    "instruments": [
      {
        "handler_id": "ap2_234352",
        // other required instruments fields
        "credential": {
          "type": "card",
          "token": "eyJhbGciOiJ..." // Token would contain payment_mandate, the signed proof of funds auth
        }
      }
    ]
  },
  "signals": {
    "br.dev.bcp.buyer_ip": "203.0.113.42",
    "com.example.risk_score": 0.95
  },
  "ap2": {
    "checkout_mandate": "eyJhbGciOiJ..." // Signed proof of checkout terms
  }
}

This provides the business with non-repudiable proof that the user authorized this specific transaction, enabling safe autonomous processing.

PCI-DSS Scope Management

Platform Scope

Most platform implementations can avoid PCI-DSS scope by:

• Using handlers that provide opaque credentials (encrypted data, token references, etc.)
• Never accessing or storing raw payment data (card numbers, CVV, etc.)
• Forwarding credentials without the ability to use them directly
• Using PSP tokenization payment handlers where raw credentials never pass through the platform

Business Scope

Businesses can minimize PCI scope by:

• Using payment credential provider-hosted tokenization (provider stores credentials, business receives token reference)
• Using wallet providers that provide encrypted credentials (Google Pay, Shop Pay)
• Never logging raw credentials
• Delegating credential processing to PCI-certified payment credential providers

Payment Credential Provider Scope

Payment credential providers (PSPs, wallets) are typically PCI-DSS Level 1 certified and handle:

• Raw credential collection
• Credential protection (tokenization, encryption, secure storage)
• Credential validation and processing
• PCI-compliant infrastructure

Security Best Practices

For Businesses:

1. Validate handler_id before processing (ensure handler is in advertised set)
2. Use separate PSP credentials for TEST vs PRODUCTION environments
3. Implement idempotency for payment processing (prevent double-charges)
4. Log payment events without logging credentials
5. Set appropriate credential timeouts
6. For autonomous commerce scenarios requiring cryptographic proof, consider supporting the br.dev.bcp.shopping.ap2_mandate extension (see AP2 Mandates Extension)

For Platforms:

1. Always use HTTPS for checkout API calls
2. Validate handler configurations before executing protocols
3. Implement timeout handling for credential acquisition
4. Clear credentials from memory after submission
5. Handle credential expiration gracefully (re-acquire if needed)
6. For autonomous agents, consider using the br.dev.bcp.shopping.ap2_mandate extension for cryptographic proof of authorization (see AP2 Mandates Extension)

For Payment Credential Providers:

1. Secure credentials for the specific business (encryption, tokenization, or other handler-specific methods)
2. Implement rate limiting on credential acquisition
3. Validate platform authorization before providing credentials
4. Set reasonable credential expiration (e.g., 15 minutes for tokens, time- limited encrypted payloads)
5. Ensure credentials cannot be used by platforms directly (only by the intended business)

Fraud Prevention Integration

BCP supports fraud prevention through Signals and the payment architecture:

• Platforms provide transaction environment signals (IP, user agent) on catalog, cart, and checkout requests
• Businesses can require additional fields in handler configurations (e.g., 3DS requirements)
• Payment credential providers can perform risk assessment during credential acquisition
• Businesses can reject high-risk transactions and request additional verification via signal feedback

Payment Architecture Extensions

The core payment architecture described above can be extended for specialized use cases:

• AP2 Mandates Extension (br.dev.bcp.shopping.ap2_mandate): Adds cryptographic proof of user authorization for autonomous commerce scenarios where non-repudiable evidence is required. See AP2 Mandates Extension.

• Custom Handler Types: Payment credential providers can define custom handlers to support new payment instruments. See Payment Handler Guide for details.

The extension model ensures the core architecture remains simple while supporting advanced security and compliance requirements when needed.

Transport Layer

BCP supports multiple transport protocols. Platforms and businesses effectively negotiate the transport via services on their profiles.

REST Transport (Core)

BCP supports HTTP/1.1 (or higher) using RESTful patterns.

• Content-Type: Requests and responses MUST use application/json.
• Methods: Implementations MUST use standard HTTP verbs (e.g., POST for creation, GET for retrieval).
• Status Codes: Implementations MUST use standard HTTP status codes (e.g., 200, 201, 400, 401, 500).

Model Context Protocol (MCP)

BCP supports MCP protocol, which operates over JSON-RPC.

Request Format

MCP requests use the tools/call method with the operation name in params.name and BCP payload in params.arguments:

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "create_checkout",
    "arguments": {
      "meta": {"ucp-agent": {"profile": "https://..."}},
      "checkout": {"line_items": [...]}
    }
  },
  "id": 1
}

Response Format

MCP tool responses use a dual-output pattern for backward compatibility. BCP MCP servers:

• MUST return the BCP response payload in structuredContent
• SHOULD declare outputSchema in tool definitions, referencing the appropriate BCP JSON Schema for the capability
• SHOULD also return serialized JSON in content[] for backward compatibility with clients not supporting structuredContent. Documentation examples abbreviate that serialized JSON string with … for readability.

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "structuredContent": {
      "ucp": {
        "version": "2026-07-14",
        "payment_handlers": {},
        "capabilities": {...}
      },
      "id": "checkout_abc123",
      "status": "incomplete"
      // ... other checkout fields
    },
    "content": [
      {"type": "text", "text": "{\"ucp\":{…},…}"}
    ]
  }
}

Agent-to-Agent Protocol (A2A)

A business MAY expose an A2A agent that supports BCP as an A2A Extension, allowing integration with platforms over structured BCP data types.

Embedded Protocol (EP)

A business MAY embed an interface onto an eligible host that would receive events as the user interacts with the interface and delegate key user actions.

Initiation comes through a continue_url that is returned by the business.

Standard Capabilities

BCP defines a set of standard capabilities:

Capability Name	ID (URI)	Description
Cart.	schemas/shopping/cart.json	Enables basket building before purchase intent is established.
Checkout	schemas/shopping/checkout.json	Facilitates the creation and management of checkout sessions, including cart management and tax calculation.
Identity Linking	-	Enables platforms to obtain authorization via OAuth 2.0 to perform actions on a user's behalf.
Order	schemas/shopping/order.json	Allows businesses to push asynchronous updates about an order's lifecycle (shipping, delivery, returns).

Definition & Extensions

Detailed definitions for endpoints, schemas, and valid extensions for each capability are provided in their respective specification files. Extensions are typically versioned and defined alongside their parent capability.

Security

Transport Security

All BCP communication MUST occur over HTTPS.

Data Privacy

Sensitive data (such as Payment Credentials or PII) MUST be handled according to PCI-DSS and GDPR guidelines. BCP encourages the use of tokenized payment data to minimize business and platform liability.

Signals

Businesses require environment data for authorization, rate limiting, and abuse prevention. Signal values MUST NOT be buyer-asserted claims — platforms provide signals based on direct observation (e.g., connection IP, user agent) or by relaying independently verifiable third-party attestations, such as cryptographically signed results from an external verifier that the business can validate against the provider's published key set.

All signal keys MUST use reverse-domain naming to ensure provenance and prevent collisions when multiple extensions contribute to the shared namespace. Well-known signals use the br.dev.bcp namespace (e.g., br.dev.bcp.buyer_ip); extension signals use their own namespace (e.g., com.example.device_id).

{
  "br.dev.bcp.buyer_ip": "203.0.113.42",
  "br.dev.bcp.user_agent": "Mozilla/5.0 ...",
  "com.example.attestation": {
    "provider_jwks": "https://example.com/.well-known/jwks.json",
    "kid": "example-key-2026-01",
    "payload": { "id": "att-7c3e9f", "pass": true, "...": "..." },
    "sig": "base64url..."
  }
}

Signal fields may contain personally identifiable information (PII). Platforms SHOULD include only signals relevant to the current transaction. Businesses SHOULD NOT persist signal data beyond the operational needs of the transaction (e.g., order finalization, fraud review).

Businesses MAY use messages with code signal to request additional data. The path field identifies the requested signal; the message type determines enforcement. An error blocks status progression until the signal is provided; an info is advisory and non-blocking.

[
  {
    "type": "error",
    "code": "signal",
    "path": "$.signals['br.dev.bcp.buyer_ip']",
    "content": "Buyer IP is required to proceed.",
    "severity": "recoverable"
  },
  {
    "type": "info",
    "code": "signal",
    "path": "$.signals['br.dev.bcp.user_agent']",
    "content": "Providing user agent may improve checkout outcomes."
  }
]

Attribution

Platforms refer users to businesses through many channels — paid ads, organic recommendations, influencer links, AI agents. In a browser-based flow, the referral context (campaigns, click identifiers, source/medium markers) flows through URL query parameters. The attribution field enables platforms to communicate the same parameters to businesses.

BCP does NOT prescribe attribution models, windows, or assignment logic. Platforms use their existing conventions (GA4 campaign parameters, click identifiers like gclid / fbclid / ttclid, etc.); businesses receive and process them according to their own analytics needs.

{
  "campaign_id": "18234567890",
  "campaign_source": "google",
  "campaign_medium": "cpc",
  "campaign_name": "spring_2026",
  "gclid": "EAIaIQobChMI..."
}

Attribution is informational and optionally provided by the platform. Businesses do not negotiate or advertise support; the field's presence or absence MUST NOT affect the response or negotiation.

The data can carry pseudonymous identifiers (click IDs, session keys) treated as personal data under applicable data protection laws. Platforms and businesses are each responsible for compliance in their respective jurisdictions: platforms determine what to emit and disclose; businesses apply their own data handling, retention, and consent policies. The buyer_consent extension provides a structured channel for buyers to communicate consent state.

Attribution appears on cart, checkout, and catalog requests as platform-provided attribution context; on order it appears as a business-emitted snapshot of the originating checkout's attribution.

Transaction Integrity and Non-Repudiation

For scenarios requiring cryptographic proof of authorization (e.g., autonomous agents, high-value transactions), BCP supports the AP2 Mandates Extension (br.dev.bcp.shopping.ap2_mandate). When this optional extension is negotiated:

• Businesses provide a cryptographic signature on checkout terms
• Platforms provide cryptographic mandates proving user authorization

This mechanism provides strong, end-to-end cryptographic assurances about transaction details and participant consent, significantly reducing risks of tampering and disputes.

See AP2 Mandates Extension for complete specification, implementation guide, and examples.

Versioning

Version Format

BCP uses date-based versioning in the format YYYY-MM-DD. This provides clear chronological ordering and unambiguous version comparison.

Version Discovery and Negotiation

BCP prioritizes strong backwards compatibility. Businesses implementing a version SHOULD handle requests from platforms using that version or older.

Both businesses and platforms declare a single version in their profiles:

Example

Business ProfilePlatform Profile

{
  "ucp": {
    "version": "2026-07-14",
    "services": { ... },
    "capabilities": { ... },
    "payment_handlers": { ... }
  }
}

{
  "ucp": {
    "version": "2026-07-14",
    "services": { ... },
    "capabilities": { ... },
    "payment_handlers": { ... }
  }
}

Version Negotiation

Version compatibility operates at two levels: the protocol version and capability versions. The protocol version (ucp.version) governs core protocol mechanisms — discovery, negotiation flow, transport bindings, and signature requirements. Capability versions govern the semantics of each feature independently, as defined in Independent Component Versioning.

Protocol Version

The version field declares the business's current protocol version. The profile at /.well-known/ucp describes the capabilities, services, and payment handlers available at that version.

Businesses that support older protocol versions SHOULD declare a supported_versions object mapping each older version to a profile URI. Each URI points to a complete, self-contained profile for that version — including its own capabilities, services, payment handlers, and signing keys. When supported_versions is omitted, only version is supported.

{
  "ucp": {
    "version": "2026-01-23",
    "supported_versions": {
      "2026-01-11": "https://business.example.com/.well-known/ucp/2026-01-11"
    },
    "services": {},
    "payment_handlers": {}
  }
}

Initial Service and Capability Discovery

Platforms discover a business's capabilities through the following flow:

1. Platform fetches /.well-known/ucp — this is the current version profile.
2. If the platform's protocol version matches version: use this profile directly. Proceed to capability negotiation.
3. If the platform's protocol version is a key in supported_versions: fetch the profile at the mapped URI. This profile describes the capabilities available at that protocol version. Proceed to capability negotiation.
4. Otherwise: the business does not support the platform's protocol version. Platforms SHOULD NOT send requests with an incompatible version; businesses MUST respond with a version_unsupported error.

Version-specific profiles are leaf documents — they describe exactly one protocol version and MUST NOT contain a supported_versions field.

Request-Time Validation

Businesses MUST validate the platform's protocol version on every request:

1. Platform declares the protocol version it uses via the version field in the profile referenced in the request.
2. Business validates:
   • If the platform's version matches the business's version or is a key in supported_versions: the request MAY proceed to capability negotiation using the matching version of the business profile.
   • Otherwise: Business MUST return a version_unsupported error.
3. If capability negotiation yields no mutually supported version for a capability required by the requested operation, the business MUST return a capabilities_incompatible error (see Error Handling).
4. Businesses MUST include the negotiated protocol version in every response.

Response with version confirmation:

{
  "ucp": {
    "version": "2026-07-14",
    "capabilities": { ... },
    "payment_handlers": { ... }
  },
  "id": "checkout_123",
  "status": "incomplete"
  // ... other checkout fields
}

Version unsupported error — no resource is created:

{
  "ucp": { "version": "2026-01-11", "status": "error" },
  "messages": [{
    "type": "error",
    "code": "version_unsupported",
    "content": "Version 2026-01-12 is not supported. This business implements version 2026-01-11.",
    "severity": "unrecoverable"
  }],
  "continue_url": "https://merchant.com/"
}

Pre-release Versions

The protocol version MUST be a dated release in YYYY-MM-DD format. Businesses MUST NOT advertise a non-date version string (e.g. "draft") in their profile version field or in supported_versions. Pre-release implementations are not stable and MUST NOT be surfaced through public discovery — doing so would expose the general ecosystem to undefined behavior and incompatible changes without notice.

Platforms and businesses MAY coordinate on pre-release implementations outside of public discovery. Such use carries no stability or compatibility guarantees — the underlying behavior may change at any time without notice.

Capability Versions

Capability versions are negotiated independently of the protocol version. Each capability in the profile is an array. Multiple entries for the same capability, each with a different version, advertise support for multiple versions of that capability. The capability intersection algorithm considers only capability versions supported by both parties.

Businesses MUST include only capabilities compatible with the negotiated protocol version in their response. A capability that depends on features introduced in a newer protocol version MUST NOT be included when processing at an older protocol version.

Backwards Compatibility

Backwards-Compatible Changes

The following changes MAY be introduced without a new version:

• Adding new non-required fields to responses
• Adding new non-required parameters to requests
• Adding new endpoints, methods, or operations to a transport
• Adding new error codes with existing error structures
• Adding new values to enums (unless explicitly documented as exhaustive)
• Changing the order of fields in responses
• Changing the length or format of opaque strings (IDs, tokens)

Breaking Changes

The following changes MUST NOT be introduced without a new version:

• Removing or renaming existing fields
• Changing field types or semantics
• Making non-required fields required
• Removing operations, methods, or endpoints
• Changing authentication or authorization requirements
• Modifying existing protocol flow or state machine
• Changing the meaning of existing error codes

Independent Component Versioning

• BCP protocol versions independently from capabilities.
• Each capability versions independently from other capabilities.
• Capabilities MUST follow the same backwards compatibility rules as the protocol.
• Businesses MUST validate capability version compatibility using the same logic as what's described above.
• Transports MAY define their own version handling mechanisms.

BCP Capabilities (br.dev.bcp.*)

BCP-authored capabilities version with protocol releases by default. Individual capabilities MAY version independently when breaking changes are required outside the protocol release cycle.

Vendor Capabilities (com.{vendor}.*)

Capabilities outside the br.dev.bcp.* namespace version fully independently. Vendors control their own release schedules and versioning strategy.

Glossary

For definitions of acronyms and terms used throughout the BCP specification, see the Glossary.