Capacidade de check-out

• Nome do recurso: br.dev.bcp.shopping.checkout

Visão geral

Permite que plataformas facilitem sessões de checkout. A finalização da compra deve ser finalizado manualmente pelo usuário por meio de uma UI confiável, a menos que o AP2 exija extensão é suportada.

A empresa continua sendo o Merchant of Record (MoR), e eles não precisam se tornar Compatível com PCI DSS para aceitar pagamentos com cartão por meio deste recurso.

Visão geral do fluxo

Pagamentos

Os manipuladores de pagamento são descobertos no perfil BCP da empresa em /.well-known/ucp e checkout.ucp.payment_handlers. Os manipuladores definem as especificações de processamento para cobrança de instrumentos de pagamento (por exemplo, Google Pay, Shop Pay). Quando o comprador envia o pagamento, a plataforma preenche a matriz payment.instruments com os dados do instrumento coletados.

O objeto payment é opcional na criação do checkout e pode ser omitido para casos de uso que não exigem processamento de pagamento (por exemplo, geração de cotação, carrinho gestão).

Cumprimento

O atendimento é modelado como uma extensão no BCP para dar conta de diversos casos de uso.

O atendimento é opcional no objeto checkout. Isto é feito para permitir um plataforma para realizar checkout de produtos digitais sem a necessidade de fornecer detalhes de atendimento mais relevantes para bens físicos.

Ciclo de vida do status do checkout

O campo checkout status indica a fase atual da sessão e determina qual ação será necessária a seguir. A empresa define o status; o plataforma recebe mensagens indicando o que é necessário para progredir.```text +------------+ +---------------------+ | incomplete |<----------------------->| requires_escalation | +-----+------+ | (buyer handoff | | | via continue_url) | | all info collected +----------+----------+ v | +------------------+ | |ready_for_complete| | | | | | (platform can | | continue_url | call Complete | | | Checkout) | | +--------+---------+ | | | | Complete Checkout | v | +--------------------+ | |complete_in_progress| | +---------+----------+ | | | +-----------------------+-------------------+ v +-------------+ | completed | +-------------+

                           +-------------+
                           |  canceled   |
                           +-------------+
      (session invalid/expired - can occur from any state)

```### Valores de status

• incomplete: A sessão de checkout não contém informações obrigatórias ou questões que precisam de resolução. A plataforma deve inspecionar a matriz messages para contexto e deve tentar resolver através do Update Checkout.

• requires_escalation: A sessão de checkout requer informações que não pode ser fornecido via API ou é necessária a contribuição do comprador. A plataforma deve inspecione messages para entender o que é necessário (consulte Tratamento de erros abaixo). Se existir algum erro recoverable, resolva-o primeiro. Em seguida, entregue ao comprador via continue_url.

• ready_for_complete: A sessão de checkout contém todas as informações necessárias e a plataforma podem ser finalizadas programaticamente. Plataforma pode ligar Check-out completo.

• complete_in_progress: A empresa está processando o Checkout Completo pedido.

• completed: Pedido realizado com sucesso.

• canceled: A sessão de checkout é inválida ou expirou. A plataforma deve inicie uma nova sessão de checkout, se necessário.

Tratamento de erros

A matriz messages contém erros, avisos e mensagens informativas sobre o estado de checkout. ucp.status é o discriminador de forma — "success" significa que a resposta carrega a carga esperada, "error" significa que ele carrega informações de erro. Cada mensagem de erro carrega um type, code, severity, content e um path opcional que identifica o campo ou item de linha específico ao qual a mensagem se refere (consulte O campo path abaixo). O campo severity prescreve a ação recomendada da plataforma:

Gravidade	Significado	Ação da plataforma
recoverable	Plataforma pode resolver modificando inputs via API	Atualizar recurso e tentar novamente
requires_buyer_input	O negócio requer entrada não disponível via API	Transferência via continue_url
requires_buyer_review	É necessária revisão e autorização do comprador	Transferência via continue_url
unrecoverable	Não existe nenhum recurso para agir	Tente novamente com novos recursos ou entradas ou transfira via continue_url

Erros com gravidade requires_* contribuem para status: requires_escalation. Ambos resultam na transferência do comprador, mas representam diferentes estados de checkout.

• requires_buyer_input significa que a finalização da compra está incompleta — a empresa requer informações que sua API não oferece suporte à coleta programada.
• requires_buyer_review significa que a finalização da compra está completa — mas política, regras regulatórias ou de direitos exigem autorização do comprador antes do pedido colocação (por exemplo, aprovação de pedidos de alto valor, política de primeira compra).

Quando a empresa não consegue criar um novo recurso ou o recurso solicitado não existe mais, a resposta contém ucp.status: "error" com messages descrevendo a falha — nenhum recurso está incluído no corpo de resposta. Quando não existe nenhum recurso para agir, as mensagens DEVEM usar severity: "unrecoverable". Por exemplo, uma empresa pode rejeitar uma solicitação de criação de checkout em que todos itens não estão disponíveis:json { "ucp": { "version": "2026-01-11", "status": "error" }, "messages": [ { "type": "error", "code": "out_of_stock", "content": "All requested items are currently out of stock", "severity": "unrecoverable" } ], "continue_url": "https://merchant.com/" }Consulte REST (não incluído nesta versão do BCP) e MCP exemplos de ligação.

Algoritmo de processamento de erros

Quando o status for incomplete ou requires_escalation, as plataformas deverão processar erros como uma pilha priorizada. O exemplo abaixo ilustra um checkout com três tipos de erro: um erro recuperável (telefone inválido), uma entrada do comprador requisito (programação de entrega) e um requisito de revisão (pedido de alto valor). Os dois últimos exigem transferência e servem como sinais explícitos para a plataforma. As empresas DEVERÃO divulgar essas mensagens o mais cedo possível, e as plataformas DEVE priorizar a resolução de erros recuperáveis antes de iniciar a transferência.json [ { "type": "error", "code": "invalid_phone", "severity": "recoverable", "path": "$.buyer.phone_number", "content": "Phone number format is invalid" }, { "type": "error", "code": "schedule_delivery", "severity": "requires_buyer_input", "content": "Select delivery window for your purchase" }, { "type": "error", "code": "high_value_order", "severity": "requires_buyer_review", "content": "Orders over $500 require additional verification" } ]Exemplo de algoritmo de processamento de erros:```text GIVEN response with messages array

FILTER errors FROM messages WHERE type = "error"

PARTITION errors INTO recoverable WHERE severity = "recoverable" requires_buyer_input WHERE severity = "requires_buyer_input" requires_buyer_review WHERE severity = "requires_buyer_review" unrecoverable WHERE severity = "unrecoverable"

IF unrecoverable is not empty RETRY with new resource or inputs, or hand off via continue_url RETURN

IF recoverable is not empty FOR EACH error IN recoverable IF error.path is present IDENTIFY the field at error.path in the request payload ATTEMPT to fix that field (e.g., reformat phone at $.buyer.phone_number) ELSE ATTEMPT generic fix based on error.code CALL Update Checkout RETURN and re-evaluate response

IF requires_buyer_input is not empty handoff_context = "incomplete, additional input from buyer is required" ELSE IF requires_buyer_review is not empty handoff_context = "ready for final review by the buyer" ```#### Erros padrão

Erros padrão são códigos de erro padronizados que as plataformas devem lidar com UX específico e apropriado, em vez de tratamento genérico de erros.

Código	Descrição
out_of_stock	Item ou variante específica não está disponível
item_unavailable	O item não pode ser comprado (por exemplo, removido da lista)
address_undeliverable	Não é possível entregar no endereço fornecido
payment_failed	Falha no processamento do pagamento
eligibility_invalid	A reivindicação de elegibilidade não pôde ser verificada na conclusão

As empresas DEVERÃO marcar os erros padrão com severity: recoverable para sinalizar que as plataformas devem fornecer UX apropriada (mensagens de falta de estoque, avisos de validação de endereço, alterações na forma de pagamento) em vez de erros genéricos mensagens ou adiar a conclusão da compra.

Exemplo: out_of_stock requer UX inicial específico, enquanto payment_required pode ser tratado genericamente no momento da submissão.

O Campo path

O campo opcional path em uma mensagem ancora o erro em um componente da carga útil da resposta. As plataformas usam-no para associar erros mensagens com o campo de entrada ou item de linha que as causou - por exemplo, destacando um campo específico do comprador em um formulário ou sinalizando um campo específico linha do carrinho.

path DEVE ser um RFC 9535 Expressão JSONPath relativa à raiz do objeto de resposta BCP. Os nomes de propriedades DEVEM usar Snake_case correspondente ao esquema de solicitação. Quando path é omitido, a mensagem se aplica à resposta como um todo.

Referência de campo simples:json { "path": "$.buyer.email" }Elemento de matriz indexado:json { "path": "$.line_items[0].quantity" }Expressão de filtro (opcional, ao referenciar um item específico por ID):json { "path": "$.line_items[?(@.id=='line-item-uuid')].quantity" }As expressões de filtro têm sintaxe RFC 9535 válida e PODE ser usadas quando referenciar um item de linha específico por id é mais claro que seu índice. Os caminhos baseados em índice são igualmente válidos; a empresa retorna índices que são inequívocos na resposta.

Regra de especificidade: um caminho para um campo específico (por exemplo, $.line_items[0].quantity) tem precedência sobre um caminho para seu pai (por exemplo, $.line_items[0]). Quando vários erros se aplicam ao mesmo campo, cada mensagem DEVE conter o caminho mais específico aplicável.

Verificação de elegibilidade na conclusão

As plataformas fornecem context.eligibility — reclamações do comprador sobre benefícios elegíveis como associação de fidelidade, vantagens de instrumentos de pagamento e similares. Estes são reivindicações, não fatos verificados. As empresas PODEM agir de acordo com reivindicações reconhecidas durante sessão (ajuste de preços, concessão de acesso ao produto, aplicação de descontos), mas todas as reclamações aceitas DEVEM ser resolvidas antes do a transação pode ser concluída.

Reivindicações não reconhecidas ou inaplicáveis ​​NÃO DEVEM bloquear a finalização da compra. As empresas DEVERÃO notificar o comprador via messages com type: "warning" quando uma reclamação não for aceita, e PODE usar type: "info" para explicar os efeitos das reivindicações aceitas. Na conclusão, as reivindicações aceitas que permanecem não verificado DEVE resultar em type: "error" com code: "eligibility_invalid" (veja abaixo).

Códigos de mensagem de elegibilidade:

Tipo	Código	Quando
warning	eligibility_not_accepted	Alegação não reconhecida ou não aplicável
info	eligibility_accepted	Efeito de uma reclamação aceite
error	eligibility_invalid	A reivindicação aceita não pôde ser verificada na conclusão

Uma reivindicação é resolvida quando é verificada ou rescindida:

• Verificado: A Empresa confirma a reivindicação contra uma prova fornecida em tempo de conclusão. O BCP não prescreve como ocorre a verificação — prova pode vir da credencial de pagamento, um recurso de verificação de identidade, ou qualquer outro mecanismo negociado entre a Plataforma e o Negócio.
• Rescindido: A Plataforma remove a reclamação de context.eligibility antes da conclusão (por exemplo, o comprador altera a forma de pagamento, retira um reivindicação de adesão). Uma vez removido, o Business recalcula sem ele.

As empresas NÃO DEVEM concluir uma transação com elegibilidade não resolvida reivindicações. Reivindicações não verificadas podem resultar em preços incorretos ou acesso a produtos restritos.

Quando a verificação falha:

A falha na verificação DEVE afetar apenas o array messages. O A empresa DEVE retornar um erro em messages com code: "eligibility_invalid" e severity: "recoverable". Mensagens DEVERIA usar o campo path para identificar quais reivindicações específicas poderiam não ser verificado. A Plataforma PODE fornecer provas válidas e reenviar, reestruturar o checkout (por exemplo, remover itens inelegíveis, atualizar reivindicações) ou abandonar a tentativa.

Por exemplo, a Plataforma reivindica um benefício de cartão de loja por meio de context.eligibility. The Business aplica preços para membros durante a sessão. Na conclusão, a credencial de pagamento não corresponde ao instrumento reivindicado:json { "ucp": { "version": "2026-01-11", "status": "success", "payment_handlers": { ... } }, "id": "checkout_abc", "status": "ready_for_complete", "currency": "...", "line_items": [ ... ], "totals": [ ... ], "links": [ ... ], "messages": [ { "type": "error", "code": "eligibility_invalid", "severity": "recoverable", "content": "Payment credential does not match the claimed store card benefit.", "path": "$.context.eligibility[0]" } ] }A Plataforma pode resolver isso fazendo com que o comprador mude para o produto qualificado instrumento de pagamento, ou removendo a reclamação de context.eligibility para renegociar o checkout (obter preços atualizados, disponibilidade, etc.) e, em seguida, reenviando para conclusão.

Apresentação de aviso

O campo presentation nas mensagens de aviso controla a renderização contratar a plataforma DEVE seguir. Quando omitido, o padrão é "notice".

	notice (padrão)	disclosure
Exibir conteúdo	DEVE	DEVE
Proximidade de path	MAIO	DEVE
Dispensável	MAIO	NÃO DEVE
Renderização image_url	MAIO	DEVE
Renderização url	MAIO	DEVE
Escalar se não puder honrar	—	DEVE via continue_url

notice (padrão)

O contrato de renderização padrão para avisos. Plataformas DEVEM ser exibidas o conteúdo do aviso ao comprador. As plataformas PODEM renderizar avisos em um banner, bandeja ou brinde, e PODE permitir que o comprador os dispense.

disclosure

Avisos com presentation: "disclosure" carregam avisos - segurança avisos, declarações de alérgenos, conteúdo de conformidade, etc. DEVE seguir o contrato de renderização prescrito abaixo.

Requisitos da plataforma:

• DEVE exibir o aviso content ao comprador.
• DEVE exibir o aviso próximo ao componente referenciado por path, preservando a associação entre a divulgação e sua assunto. Quando path for omitido, a divulgação se aplica à resposta como um todo.
• NÃO DEVE ocultar, recolher ou ignorar automaticamente o aviso.
• DEVE renderizar image_url quando presente (por exemplo, símbolo de aviso, etiqueta de classe energética).
• DEVE renderizar url como um link de referência navegável, quando presente.

Avisos com presentation: "disclosure" DEVEM ser renderizados prioridade sobre os avisos.

Plataformas que não conseguem honrar o contrato de prestação de divulgação DEVEM escalar para a UI do comerciante via continue_url em vez de silenciosamente rebaixando para um aviso.

Requisitos de negócios:

• DEVE definir presentation: "disclosure" quando o conteúdo do aviso deve ser exibido ao lado de um componente específico e não deve ser oculto ou descartado automaticamente.
• DEVE utilizar o campo path para associar as divulgações ao componente relevante na resposta.
• DEVE fornecer um code que identifique a categoria de divulgação (por exemplo, prop65, allergens, energy_label).
• DEVE fornecer image_url quando a divulgação tiver um associado elemento visual (por exemplo, símbolo de advertência, etiqueta de classe energética).
• DEVE fornecer url quando um link de referência estiver disponível para o comprador para saber mais.

Divulgação e Reconhecimento

O campo presentation controla como o aviso é renderizado, não se o checkout pode prosseguir. Quando o reconhecimento afirmativo do comprador ou autorização também for necessária, a empresa PODE combinar o divulgação com os mecanismos de escalonamento descritos no Ciclo de vida do status do checkout para garantir o a opinião apropriada do comprador é obtida.

Jurisdição e aplicabilidade

É responsabilidade da empresa determinar quais divulgações se aplicam para uma determinada sessão e retornar apenas aqueles que são relevantes. Negócios DEVE usar dados fornecidos pelo comprador (context e outras informações) e atributos do produto para resolver requisitos específicos da jurisdição. As plataformas não afetam nem resolvem a aplicabilidade da divulgação — elas prestam o que recebem do negócio.

Exemplo

Uma resposta de checkout contendo um erro recuperável e uma divulgação aviso em um item de linha:json { "ucp": { "version": "2026-07-14", "status": "success", "payment_handlers": { ... } }, "id": "chk_abc123", "status": "incomplete", "currency": "USD", "line_items": [ { "id": "li_1", "item": { "id": "item_456", "title": "Artisan Nut Butter Collection", "price": 1299, "image_url": "https://merchant.com/nut-butter.jpg" }, "quantity": 1, "totals": [ { "type": "subtotal", "amount": 1299 }, { "type": "total", "amount": 1299 } ] } ], "totals": [ { "type": "subtotal", "amount": 1299 }, { "type": "total", "amount": 1299 } ], "messages": [ { "type": "error", "code": "field_required", "path": "$.buyer.email", "content": "Buyer email is required", "severity": "recoverable" }, { "type": "warning", "code": "allergens", "path": "$.line_items[0]", "content": "**Contains: tree nuts.** Produced in a facility that also processes peanuts, milk, and soy.", "content_type": "markdown", "presentation": "disclosure", "image_url": "https://merchant.com/allergen-tree-nuts.svg", "url": "https://merchant.com/allergen-info" } ], "links": [] }A plataforma resolve o erro recuperável programaticamente enquanto tornando a divulgação do alérgeno próxima à linha referenciada artigo.

Continuar URL

O campo continue_url permite a transferência de checkout da plataforma para a interface de negócios, permitindo que o comprador continue e finalize a sessão de checkout.

Disponibilidade

As empresas DEVEM fornecer continue_url ao retornar status = requires_escalation. Para todos os outros status não terminais (incomplete, ready_for_complete, complete_in_progress), as empresas DEVERÃO fornecer continue_url. Para estados terminais (completed, canceled), continue_url DEVE ser omitido.

Formato

O continue_url DEVE ser um URL HTTPS absoluto e DEVE preservar estado de checkout para transferência perfeita. As empresas PODEM implementar o estado preservação usando qualquer uma das abordagens:

Estado do lado do servidor (recomendado)

Um URL opaco apoiado pelo estado de checkout do lado do servidor:text https://business.example.com/checkout-sessions/{checkout_id}* Servidor mantém estado de checkout vinculado a checkout_id * Simples, seguro, recomendado para a maioria das implementações * Vida útil do URL normalmente vinculada a expires_at

Link permanente de check-out

Uma URL sem estado que codifica diretamente o estado de checkout, permitindo a reconstrução sem persistência do lado do servidor. As empresas DEVERÃO implementar suporte para este formato para facilitar a entrega do checkout e a entrada acelerada - por exemplo, um A plataforma pode preencher previamente o estado de checkout ao iniciar um fluxo de compra agora.

Observação: Links permanentes de checkout são uma construção específica do REST que estende o Ligação de transporte REST (não incluída nesta versão do BCP). Acessar um link permanente retorna um redireciona para a IU de checkout ou renderiza a página de checkout diretamente.

Escopos

O recurso Checkout define os seguintes escopos conhecidos para acesso autenticado pelo usuário:

Escopo	Descrição
br.dev.bcp.shopping.checkout:manage	Todas as operações de checkout em nome do usuário autenticado — criar, atualizar, concluir e cancelar sessões de checkout.

Declaração de escopo, derivação e regras para estender este conjunto com escopos personalizados são definidos em Vinculação de identidade — Escopos.

Diretrizes

(Além das diretrizes gerais)

Plataforma

• PODE contratar um agente para facilitar a sessão de checkout (por exemplo, adicionar itens para a sessão de checkout, selecione o endereço de atendimento). No entanto, o agente deve entregar a sessão de checkout a um confiável e UI determinística para o usuário revisar os detalhes do checkout e colocar o ordem.
• PODE enviar o usuário da UI confiável e determinística de volta ao agente a qualquer momento. Por exemplo, quando o usuário decide sair da tela de checkout para continuar adicionando itens ao carrinho.
• PODE fornecer contexto ao agente quando a plataforma indicar que a solicitação foi feito por um agente.
• DEVE usar continue_url quando o status de checkout for requires_escalation.
• PODE usar continue_url para transferir para a UI comercial em outras situações.
• Ao realizar a transferência, DEVE preferir os fornecidos pela empresa continue_url sobre links permanentes de checkout construídos pela plataforma.

Negócios

• DEVE enviar um e-mail de confirmação após a finalização da compra.
• DEVE fornecer mensagens de erro precisas.
• A lógica que trata as sessões de checkout DEVE ser determinística.
• DEVE fornecer continue_url ao retornar status = requires_escalation.
• DEVE incluir pelo menos uma mensagem com severity de requires_buyer_input ou requires_buyer_review no retorno status = requires_escalation.
• DEVE fornecer continue_url em todas as respostas de checkout não terminais.
• Após uma sessão de checkout atingir o estado “concluída”, ela é considerada imutável.

Definição do esquema de capacidade

Name	Type	Required	Description
ucp	any	Yes	UCP metadata for checkout responses.
id	string	Yes	Unique identifier of the checkout session.
line_items	Array[Line Item Response]	Yes	List of line items being checked out.
buyer	Buyer	No	Representation of the buyer.
context	Context	No	Provisional buyer signals for relevance and localization—not authoritative data. Businesses SHOULD use these values when verified inputs (e.g., shipping address) are absent, and MAY ignore or down-rank them if inconsistent with higher-confidence signals (authenticated account, risk detection) or regulatory constraints (export controls). Eligibility and policy enforcement MUST occur at checkout time using binding transaction data. Context SHOULD be non-identifying and can be disclosed progressively—coarse signals early, finer resolution as the session progresses. Higher-resolution data (shipping address, billing address) supersedes context.
signals	Signals	No	Environment data provided by the platform to support authorization and abuse prevention. Values MUST NOT be buyer-asserted claims — platforms provide signals based on direct observation or independently verifiable third-party attestations. All signal keys MUST use reverse-domain naming to ensure provenance and prevent collisions when multiple extensions contribute to the shared namespace.
attribution	Attribution	No	Platform-emitted referral and conversion-event context — campaign identifiers, click IDs, source/medium markers, etc. The same parameters platforms communicate via URL query parameters in browser-based flows.
status	string	Yes	Checkout state indicating the current phase and required action. See Checkout Status lifecycle documentation for state transition details. Enum: incomplete, requires_escalation, ready_for_complete, complete_in_progress, completed, canceled
currency	string	Yes	ISO 4217 currency code reflecting the merchant's market determination. Derived from address, context, and geo IP—buyers provide signals, merchants determine currency.
totals	Totals	Yes	Different cart totals.
messages	Array[Message]	No	List of messages with error and info about the checkout session state.
links	Array[Link]	Yes	Links to be displayed by the platform (Privacy Policy, TOS). Mandatory for legal compliance.
expires_at	string	No	RFC 3339 expiry timestamp. Default TTL is 6 hours from creation if not sent.
continue_url	string	No	URL for checkout handoff and session recovery. MUST be provided when status is requires_escalation. See specification for format and availability requirements.
payment	Payment	No	Payment configuration containing handlers.
order	Order Confirmation	No	Details about an order created for this checkout session.

Operações

O recurso Checkout define as seguintes operações lógicas.

Operação	Descrição
Criar check-out	Inicia uma nova sessão de checkout. Chamado assim que um usuário adiciona um item ao carrinho.
Fazer check-out	Recupera o estado atual de uma sessão de checkout.
Atualizar Check-out	Atualiza uma sessão de checkout.
Concluir Check-out	Finaliza o checkout e faz o pedido.
Cancelar check-out	Cancela uma sessão de checkout.

Criar check-outA ser invocado pela plataforma quando o usuário manifestar intenção de compra

(por exemplo, clique em Comprar) para iniciar a sessão de checkout com os detalhes do item.

Recomendação: para minimizar discrepâncias e simplificar a experiência do usuário, dados do produto (preço/título etc.) fornecidos pela empresa por meio dos feeds DEVE corresponder aos atributos reais retornados na resposta.

Quando o recurso Cart é negociado, a carga útil da solicitação deve aceitar um campo cart_id adicional para conversão do carrinho para finalização da compra. Veja Carrinho → Conversão do carrinho para checkout para o contrato de campo.

Campos de solicitação

Name	Type	Required	Description
line_items	Array[Line Item]	Yes	List of line items being checked out.
buyer	Buyer	No	Representation of the buyer.
context	Context	No	Provisional buyer signals for relevance and localization—not authoritative data. Businesses SHOULD use these values when verified inputs (e.g., shipping address) are absent, and MAY ignore or down-rank them if inconsistent with higher-confidence signals (authenticated account, risk detection) or regulatory constraints (export controls). Eligibility and policy enforcement MUST occur at checkout time using binding transaction data. Context SHOULD be non-identifying and can be disclosed progressively—coarse signals early, finer resolution as the session progresses. Higher-resolution data (shipping address, billing address) supersedes context.
signals	Signals	No	Environment data provided by the platform to support authorization and abuse prevention. Values MUST NOT be buyer-asserted claims — platforms provide signals based on direct observation or independently verifiable third-party attestations. All signal keys MUST use reverse-domain naming to ensure provenance and prevent collisions when multiple extensions contribute to the shared namespace.
attribution	Attribution	No	Platform-emitted referral and conversion-event context — campaign identifiers, click IDs, source/medium markers, etc. The same parameters platforms communicate via URL query parameters in browser-based flows.
payment	Payment	No	Payment configuration containing handlers.

Campos de resposta

Name	Type	Required	Description
ucp	any	Yes	UCP metadata for checkout responses.
id	string	Yes	Unique identifier of the checkout session.
line_items	Array[Line Item Response]	Yes	List of line items being checked out.
buyer	Buyer	No	Representation of the buyer.
context	Context	No	Provisional buyer signals for relevance and localization—not authoritative data. Businesses SHOULD use these values when verified inputs (e.g., shipping address) are absent, and MAY ignore or down-rank them if inconsistent with higher-confidence signals (authenticated account, risk detection) or regulatory constraints (export controls). Eligibility and policy enforcement MUST occur at checkout time using binding transaction data. Context SHOULD be non-identifying and can be disclosed progressively—coarse signals early, finer resolution as the session progresses. Higher-resolution data (shipping address, billing address) supersedes context.
signals	Signals	No	Environment data provided by the platform to support authorization and abuse prevention. Values MUST NOT be buyer-asserted claims — platforms provide signals based on direct observation or independently verifiable third-party attestations. All signal keys MUST use reverse-domain naming to ensure provenance and prevent collisions when multiple extensions contribute to the shared namespace.
attribution	Attribution	No	Platform-emitted referral and conversion-event context — campaign identifiers, click IDs, source/medium markers, etc. The same parameters platforms communicate via URL query parameters in browser-based flows.
status	string	Yes	Checkout state indicating the current phase and required action. See Checkout Status lifecycle documentation for state transition details. Enum: incomplete, requires_escalation, ready_for_complete, complete_in_progress, completed, canceled
currency	string	Yes	ISO 4217 currency code reflecting the merchant's market determination. Derived from address, context, and geo IP—buyers provide signals, merchants determine currency.
totals	Totals	Yes	Different cart totals.
messages	Array[Message]	No	List of messages with error and info about the checkout session state.
links	Array[Link]	Yes	Links to be displayed by the platform (Privacy Policy, TOS). Mandatory for legal compliance.
expires_at	string	No	RFC 3339 expiry timestamp. Default TTL is 6 hours from creation if not sent.
continue_url	string	No	URL for checkout handoff and session recovery. MUST be provided when status is requires_escalation. See specification for format and availability requirements.
payment	Payment	No	Payment configuration containing handlers.
order	Order Confirmation	No	Details about an order created for this checkout session.

Faça o check-out

Ele fornece o estado mais recente do recurso de checkout. Após cancelamento ou conclusão, cabe à empresa decidir o que devolver (ou seja, pode ser um longo estado vivido ou expirar após um TTL específico - resultando em um 'não encontrado' erro). Na plataforma não há aplicação específica para um TTL do check-out.

A plataforma honrará o TTL fornecido pela empresa via expires_at no momento da criação da sessão de checkout.

Campos de resposta

Name	Type	Required	Description
ucp	any	Yes	UCP metadata for checkout responses.
id	string	Yes	Unique identifier of the checkout session.
line_items	Array[Line Item Response]	Yes	List of line items being checked out.
buyer	Buyer	No	Representation of the buyer.
context	Context	No	Provisional buyer signals for relevance and localization—not authoritative data. Businesses SHOULD use these values when verified inputs (e.g., shipping address) are absent, and MAY ignore or down-rank them if inconsistent with higher-confidence signals (authenticated account, risk detection) or regulatory constraints (export controls). Eligibility and policy enforcement MUST occur at checkout time using binding transaction data. Context SHOULD be non-identifying and can be disclosed progressively—coarse signals early, finer resolution as the session progresses. Higher-resolution data (shipping address, billing address) supersedes context.
signals	Signals	No	Environment data provided by the platform to support authorization and abuse prevention. Values MUST NOT be buyer-asserted claims — platforms provide signals based on direct observation or independently verifiable third-party attestations. All signal keys MUST use reverse-domain naming to ensure provenance and prevent collisions when multiple extensions contribute to the shared namespace.
attribution	Attribution	No	Platform-emitted referral and conversion-event context — campaign identifiers, click IDs, source/medium markers, etc. The same parameters platforms communicate via URL query parameters in browser-based flows.
status	string	Yes	Checkout state indicating the current phase and required action. See Checkout Status lifecycle documentation for state transition details. Enum: incomplete, requires_escalation, ready_for_complete, complete_in_progress, completed, canceled
currency	string	Yes	ISO 4217 currency code reflecting the merchant's market determination. Derived from address, context, and geo IP—buyers provide signals, merchants determine currency.
totals	Totals	Yes	Different cart totals.
messages	Array[Message]	No	List of messages with error and info about the checkout session state.
links	Array[Link]	Yes	Links to be displayed by the platform (Privacy Policy, TOS). Mandatory for legal compliance.
expires_at	string	No	RFC 3339 expiry timestamp. Default TTL is 6 hours from creation if not sent.
continue_url	string	No	URL for checkout handoff and session recovery. MUST be provided when status is requires_escalation. See specification for format and availability requirements.
payment	Payment	No	Payment configuration containing handlers.
order	Order Confirmation	No	Details about an order created for this checkout session.

Atualizar verificação

Executa uma substituição completa do recurso de checkout. A plataforma é OBRIGATÓRIA a enviar todo o recurso de checkout contendo qualquer atualizações de dados em campos de dados somente gravação. O recurso fornecido na solicitação substituirá o estado da sessão de checkout existente no lado comercial.

Campos de solicitação

Name	Type	Required	Description
line_items	Array[Line Item]	Yes	List of line items being checked out.
buyer	Buyer	No	Representation of the buyer.
context	Context	No	Provisional buyer signals for relevance and localization—not authoritative data. Businesses SHOULD use these values when verified inputs (e.g., shipping address) are absent, and MAY ignore or down-rank them if inconsistent with higher-confidence signals (authenticated account, risk detection) or regulatory constraints (export controls). Eligibility and policy enforcement MUST occur at checkout time using binding transaction data. Context SHOULD be non-identifying and can be disclosed progressively—coarse signals early, finer resolution as the session progresses. Higher-resolution data (shipping address, billing address) supersedes context.
signals	Signals	No	Environment data provided by the platform to support authorization and abuse prevention. Values MUST NOT be buyer-asserted claims — platforms provide signals based on direct observation or independently verifiable third-party attestations. All signal keys MUST use reverse-domain naming to ensure provenance and prevent collisions when multiple extensions contribute to the shared namespace.
attribution	Attribution	No	Platform-emitted referral and conversion-event context — campaign identifiers, click IDs, source/medium markers, etc. The same parameters platforms communicate via URL query parameters in browser-based flows.
payment	Payment	No	Payment configuration containing handlers.

Campos de resposta

Name	Type	Required	Description
ucp	any	Yes	UCP metadata for checkout responses.
id	string	Yes	Unique identifier of the checkout session.
line_items	Array[Line Item Response]	Yes	List of line items being checked out.
buyer	Buyer	No	Representation of the buyer.
context	Context	No	Provisional buyer signals for relevance and localization—not authoritative data. Businesses SHOULD use these values when verified inputs (e.g., shipping address) are absent, and MAY ignore or down-rank them if inconsistent with higher-confidence signals (authenticated account, risk detection) or regulatory constraints (export controls). Eligibility and policy enforcement MUST occur at checkout time using binding transaction data. Context SHOULD be non-identifying and can be disclosed progressively—coarse signals early, finer resolution as the session progresses. Higher-resolution data (shipping address, billing address) supersedes context.
signals	Signals	No	Environment data provided by the platform to support authorization and abuse prevention. Values MUST NOT be buyer-asserted claims — platforms provide signals based on direct observation or independently verifiable third-party attestations. All signal keys MUST use reverse-domain naming to ensure provenance and prevent collisions when multiple extensions contribute to the shared namespace.
attribution	Attribution	No	Platform-emitted referral and conversion-event context — campaign identifiers, click IDs, source/medium markers, etc. The same parameters platforms communicate via URL query parameters in browser-based flows.
status	string	Yes	Checkout state indicating the current phase and required action. See Checkout Status lifecycle documentation for state transition details. Enum: incomplete, requires_escalation, ready_for_complete, complete_in_progress, completed, canceled
currency	string	Yes	ISO 4217 currency code reflecting the merchant's market determination. Derived from address, context, and geo IP—buyers provide signals, merchants determine currency.
totals	Totals	Yes	Different cart totals.
messages	Array[Message]	No	List of messages with error and info about the checkout session state.
links	Array[Link]	Yes	Links to be displayed by the platform (Privacy Policy, TOS). Mandatory for legal compliance.
expires_at	string	No	RFC 3339 expiry timestamp. Default TTL is 6 hours from creation if not sent.
continue_url	string	No	URL for checkout handoff and session recovery. MUST be provided when status is requires_escalation. See specification for format and availability requirements.
payment	Payment	No	Payment configuration containing handlers.
order	Order Confirmation	No	Details about an order created for this checkout session.

Finalização completa da compra

Esta é a chamada final de colocação de checkout. Para ser invocado quando o usuário tiver compromete-se a pagar e fazer um pedido dos itens escolhidos. A resposta deste call é o objeto checkout com o campo order preenchido. O retornado order fornece os identificadores necessários, como id e permalink_url, que pode ser usado para fazer referência ao estado completo do pedido feito. No momento da persistência do pedido serão utilizados os campos de Checkout PODE para construir a representação do pedido (ou seja, informações como line_items, fulfillment será utilizado para criar a representação inicial do pedido).

Após esta teleconferência, outros detalhes serão atualizados em eventos subsequentes à medida que o pedido e seus itens associados avançam pela cadeia de suprimentos.

Campos de solicitação

Name	Type	Required	Description
signals	Signals	No	Environment data provided by the platform to support authorization and abuse prevention. Values MUST NOT be buyer-asserted claims — platforms provide signals based on direct observation or independently verifiable third-party attestations. All signal keys MUST use reverse-domain naming to ensure provenance and prevent collisions when multiple extensions contribute to the shared namespace.
attribution	Attribution	No	Platform-emitted referral and conversion-event context — campaign identifiers, click IDs, source/medium markers, etc. The same parameters platforms communicate via URL query parameters in browser-based flows.
payment	Payment	Yes	Payment configuration containing handlers.

Campos de resposta

Name	Type	Required	Description
ucp	any	Yes	UCP metadata for checkout responses.
id	string	Yes	Unique identifier of the checkout session.
line_items	Array[Line Item Response]	Yes	List of line items being checked out.
buyer	Buyer	No	Representation of the buyer.
context	Context	No	Provisional buyer signals for relevance and localization—not authoritative data. Businesses SHOULD use these values when verified inputs (e.g., shipping address) are absent, and MAY ignore or down-rank them if inconsistent with higher-confidence signals (authenticated account, risk detection) or regulatory constraints (export controls). Eligibility and policy enforcement MUST occur at checkout time using binding transaction data. Context SHOULD be non-identifying and can be disclosed progressively—coarse signals early, finer resolution as the session progresses. Higher-resolution data (shipping address, billing address) supersedes context.
signals	Signals	No	Environment data provided by the platform to support authorization and abuse prevention. Values MUST NOT be buyer-asserted claims — platforms provide signals based on direct observation or independently verifiable third-party attestations. All signal keys MUST use reverse-domain naming to ensure provenance and prevent collisions when multiple extensions contribute to the shared namespace.
attribution	Attribution	No	Platform-emitted referral and conversion-event context — campaign identifiers, click IDs, source/medium markers, etc. The same parameters platforms communicate via URL query parameters in browser-based flows.
status	string	Yes	Checkout state indicating the current phase and required action. See Checkout Status lifecycle documentation for state transition details. Enum: incomplete, requires_escalation, ready_for_complete, complete_in_progress, completed, canceled
currency	string	Yes	ISO 4217 currency code reflecting the merchant's market determination. Derived from address, context, and geo IP—buyers provide signals, merchants determine currency.
totals	Totals	Yes	Different cart totals.
messages	Array[Message]	No	List of messages with error and info about the checkout session state.
links	Array[Link]	Yes	Links to be displayed by the platform (Privacy Policy, TOS). Mandatory for legal compliance.
expires_at	string	No	RFC 3339 expiry timestamp. Default TTL is 6 hours from creation if not sent.
continue_url	string	No	URL for checkout handoff and session recovery. MUST be provided when status is requires_escalation. See specification for format and availability requirements.
payment	Payment	No	Payment configuration containing handlers.
order	Order Confirmation	No	Details about an order created for this checkout session.

Cancelar finalização da compra

Esta operação será utilizada para cancelar uma sessão de checkout, caso esta possa ser cancelada. Se a sessão de checkout não puder ser cancelada (por exemplo, a sessão de checkout é já cancelado ou concluído), então as empresas DEVERÃO enviar de volta um erro indicando que a operação não é permitida. Qualquer sessão de checkout com status que não seja igual a completed ou canceled DEVE ser cancelável.

Campos de resposta

Name	Type	Required	Description
ucp	any	Yes	UCP metadata for checkout responses.
id	string	Yes	Unique identifier of the checkout session.
line_items	Array[Line Item Response]	Yes	List of line items being checked out.
buyer	Buyer	No	Representation of the buyer.
context	Context	No	Provisional buyer signals for relevance and localization—not authoritative data. Businesses SHOULD use these values when verified inputs (e.g., shipping address) are absent, and MAY ignore or down-rank them if inconsistent with higher-confidence signals (authenticated account, risk detection) or regulatory constraints (export controls). Eligibility and policy enforcement MUST occur at checkout time using binding transaction data. Context SHOULD be non-identifying and can be disclosed progressively—coarse signals early, finer resolution as the session progresses. Higher-resolution data (shipping address, billing address) supersedes context.
signals	Signals	No	Environment data provided by the platform to support authorization and abuse prevention. Values MUST NOT be buyer-asserted claims — platforms provide signals based on direct observation or independently verifiable third-party attestations. All signal keys MUST use reverse-domain naming to ensure provenance and prevent collisions when multiple extensions contribute to the shared namespace.
attribution	Attribution	No	Platform-emitted referral and conversion-event context — campaign identifiers, click IDs, source/medium markers, etc. The same parameters platforms communicate via URL query parameters in browser-based flows.
status	string	Yes	Checkout state indicating the current phase and required action. See Checkout Status lifecycle documentation for state transition details. Enum: incomplete, requires_escalation, ready_for_complete, complete_in_progress, completed, canceled
currency	string	Yes	ISO 4217 currency code reflecting the merchant's market determination. Derived from address, context, and geo IP—buyers provide signals, merchants determine currency.
totals	Totals	Yes	Different cart totals.
messages	Array[Message]	No	List of messages with error and info about the checkout session state.
links	Array[Link]	Yes	Links to be displayed by the platform (Privacy Policy, TOS). Mandatory for legal compliance.
expires_at	string	No	RFC 3339 expiry timestamp. Default TTL is 6 hours from creation if not sent.
continue_url	string	No	URL for checkout handoff and session recovery. MUST be provided when status is requires_escalation. See specification for format and availability requirements.
payment	Payment	No	Payment configuration containing handlers.
order	Order Confirmation	No	Details about an order created for this checkout session.

Ligações de transporte

As operações abstratas acima estão vinculadas a protocolos de transporte específicos como definido abaixo:

• REST Binding (não incluído nesta versão do BCP): mapeamento de API RESTful usando verbos HTTP padrão e cargas JSON.
• MCP Binding: Mapeamento do protocolo de contexto do modelo para interação de agente.
• A2A Binding: Mapeamento de protocolo agente para agente para interações de agente.
• Embedded Checkout Binding: JSON-RPC para ativar o checkout incorporado.

Entidades

Comprador

Name	Type	Required	Description
first_name	string	No	First name of the buyer.
last_name	string	No	Last name of the buyer.
email	string	No	Email of the buyer.
phone_number	string	No	E.164 standard.

ContextoOs sinais de contexto são dados provisórios e não oficiais. As empresas DEVEM usar

esses valores quando as entradas verificadas (por exemplo, endereço de entrega) estão ausentes e PODEM ignore ou rebaixe-os se for inconsistente com sinais de maior confiança (conta autenticada, detecção de risco) ou restrições regulatórias (exportação controles). A elegibilidade e a aplicação da política DEVEM ocorrer no momento da finalização da compra usando dados de transação vinculativos.

Name	Type	Required	Description
address_country	string	No	The country. Recommended to be in 2-letter ISO 3166-1 alpha-2 format, for example "US". For backward compatibility, a 3-letter ISO 3166-1 alpha-3 country code such as "SGP" or a full country name such as "Singapore" can also be used. Optional hint for market context (currency, availability, pricing)—higher-resolution data (e.g., shipping address) supersedes this value.
address_region	string	No	The region in which the locality is, and which is in the country. For example, California or another appropriate first-level Administrative division. Optional hint for progressive localization—higher-resolution data (e.g., shipping address) supersedes this value.
postal_code	string	No	The postal code. For example, 94043. Optional hint for regional refinement—higher-resolution data (e.g., shipping address) supersedes this value.
intent	string	No	Background context describing buyer's intent (e.g., 'looking for a gift under $50', 'need something durable for outdoor use'). Informs relevance, recommendations, and personalization.
language	string	No	Preferred language for content. Use IETF BCP 47 language tags (e.g., 'en', 'fr-CA', 'zh-Hans'). For REST, equivalent to Accept-Language header—platforms SHOULD fall back to Accept-Language when this field is absent; when provided, overrides Accept-Language. Businesses MAY return content in a different language if unavailable.
currency	string	No	Preferred currency (ISO 4217, e.g., 'EUR', 'USD'). Businesses determine presentment currency from context and authoritative signals; this hint MAY inform selection in multi-currency markets. Also serves as the denomination for price filter values — platforms SHOULD include this field when sending price filters. Response prices include explicit currency confirming the resolution.
eligibility	Array[Reverse Domain Name]	No	Buyer claims about eligible benefits such as loyalty membership, payment instrument perks, and similar. Recognized claims MAY inform the Business response (e.g., member-only product availability, adjusted pricing in catalog, provisional discounts at cart or checkout). Businesses MUST ignore unrecognized values without error. Values MUST use reverse-domain naming (e.g., 'com.example.loyalty_gold', 'org.school.student') and MUST be non-identifying.

Sinais

Dados ambientais fornecidos pela plataforma para apoiar a autorização e prevenção de abusos. Ao contrário de context (preferências declaradas pelo comprador) e buyer (identidade autodeclarada), os valores de sinal NÃO DEVEM ser declarações afirmadas pelo comprador - plataformas fornecem sinais baseados na observação direta ou na retransmissão atestados de terceiros verificáveis de forma independente. Veja Sinais para detalhes e privacidade requisitos.

Name	Type	Required	Description
br.dev.bcp.buyer_ip	string	No	Client's IP address (IPv4 or IPv6).
br.dev.bcp.user_agent	string	No	Client's HTTP User-Agent header or equivalent.

Atribuição

Contexto de referência e evento de conversão fornecido pela plataforma – IDs de campanha, identificadores de clique e marcadores de origem/mídia comunicados pela plataforma. Consulte Atribuição para obter detalhes e consentimento requisitos.

Platform-emitted referral and conversion-event context — campaign identifiers, click IDs, source/medium markers, etc. The same parameters platforms communicate via URL query parameters in browser-based flows.

Artigo

Solicitação de criação de item

Name	Type	Required	Description
id	string	Yes	The product identifier, often the SKU, required to resolve the product details associated with this line item. Should be recognized by both the Platform, and the Business.

Solicitação de atualização de item

Name	Type	Required	Description
id	string	Yes	The product identifier, often the SKU, required to resolve the product details associated with this line item. Should be recognized by both the Platform, and the Business.

Artigo

Name	Type	Required	Description
id	string	Yes	The product identifier, often the SKU, required to resolve the product details associated with this line item. Should be recognized by both the Platform, and the Business.
title	string	Yes	Product title.
price	Amount	Yes	Unit price in ISO 4217 minor units.
image_url	string	No	Product image URI.

Item de linha

Solicitação de criação de item de linha

Name	Type	Required	Description
item	Item	Yes
quantity	integer	Yes	Quantity of the item being purchased.

Solicitação de atualização de item de linha

Name	Type	Required	Description
id	string	No
item	Item	Yes
quantity	integer	Yes	Quantity of the item being purchased.
parent_id	string	No	Parent line item identifier for any nested structures.

Item de linha

Name	Type	Required	Description
id	string	Yes
item	Item	Yes
quantity	integer	Yes	Quantity of the item being purchased.
totals	Array[Total]	Yes	Line item totals breakdown.
parent_id	string	No	Parent line item identifier for any nested structures.

Ligação

Name	Type	Required	Description
type	string	Yes	Type of link. Well-known values: privacy_policy, terms_of_service, refund_policy, shipping_policy, faq. Consumers SHOULD handle unknown values gracefully by displaying them using the title field or omitting the link.
url	string	Yes	The actual URL pointing to the content to be displayed.
title	string	No	Optional display text for the link. When provided, use this instead of generating from type.

Tipos de links conhecidos

As empresas DEVERÃO fornecer todos os links relevantes para a transação. O a seguir estão os tipos conhecidos recomendados:

Tipo	Descrição
privacy_policy	Link para a política de privacidade da empresa
terms_of_service	Link para os termos de serviço da empresa
refund_policy	Link para a política de reembolso da empresa
shipping_policy	Link para a política de envio da empresa
faq	Link para as perguntas mais frequentes da empresa

As empresas PODEM definir tipos personalizados para necessidades específicas de domínio. Plataformas DEVE lidar com tipos desconhecidos normalmente, exibindo-os usando o title campo ou omitindo-os.

Mensagem

This object MUST be one of the following types: Message Error, Message Warning, Message Info.

Erro de mensagem

Name	Type	Required	Description
type	string	Yes	Constant = error. Message type discriminator.
code	Error Code	Yes	Error code identifying the type of error. Standard errors are defined in specification (see examples), and have standardized semantics; freeform codes are permitted.
path	string	No	RFC 9535 JSONPath to the component the message refers to (e.g., $.items[1]).
content_type	string	No	Content format, default = plain. Enum: plain, markdown
content	string	Yes	Human-readable message.
severity	string	Yes	Reflects the resource state and recommended action. 'recoverable': platform can resolve by modifying inputs and retrying via API. 'requires_buyer_input': merchant requires information their API doesn't support collecting programmatically (checkout incomplete). 'requires_buyer_review': buyer must authorize before order placement due to policy, regulatory, or entitlement rules. 'unrecoverable': no valid resource exists to act on, retry with new resource or inputs. Errors with 'requires_' severity contribute to 'status: requires_escalation'. Enum:* recoverable, requires_buyer_input, requires_buyer_review, unrecoverable

Código de erro

Error code identifying the type of error. Standard errors are defined in specification (see examples), and have standardized semantics; freeform codes are permitted.

Informações da mensagem

Name	Type	Required	Description
type	string	Yes	Constant = info. Message type discriminator.
path	string	No	RFC 9535 JSONPath to the component the message refers to.
code	Info Code	No	Info code identifying the type of informational message. Standard codes are defined in capability specs (see examples), and have standardized semantics; freeform codes are permitted.
content_type	string	No	Content format, default = plain. Enum: plain, markdown
content	string	Yes	Human-readable message.

Aviso de mensagem

Name	Type	Required	Description
type	string	Yes	Constant = warning. Message type discriminator.
path	string	No	JSONPath (RFC 9535) to related field (e.g., $.line_items[0]).
code	Warning Code	Yes	Warning code identifying the type of warning. Standard codes are defined in capability specs (see examples), and have standardized semantics; freeform codes are permitted.
content	string	Yes	Human-readable warning message that MUST be displayed.
content_type	string	No	Content format, default = plain. Enum: plain, markdown
presentation	string	No	Rendering contract for this warning. 'notice' (default): platform MUST display, MAY dismiss. 'disclosure': platform MUST display in proximity to the path-referenced component, MUST NOT hide or auto-dismiss. See specification for full contract.
image_url	string	No	URL to a required visual element (e.g., warning symbol, energy class label).
url	string	No	Reference URL for more information (e.g., regulatory site, registry entry, policy page).

Pagamento

Name	Type	Required	Description
instruments	Array[Payment Instrument Selected Payment Instrument]	No	The payment instruments available for this payment. Each instrument is associated with a specific handler via the handler_id field. Handlers can extend the base payment_instrument schema to add handler-specific fields.

Instrumento de pagamento selecionado

A payment instrument with selection state.

Name	Type	Required	Description
id	string	Yes	A unique identifier for this instrument instance, assigned by the platform.
handler_id	string	Yes	The unique identifier for the handler instance that produced this instrument. This corresponds to the 'id' field in the Payment Handler definition.
type	string	Yes	The broad category of the instrument (e.g., 'card', 'tokenized_card'). Specific schemas will constrain this to a constant value.
billing_address	object	No	The billing address associated with this payment method.
credential	object	No	The base definition for any payment credential. Handlers define specific credential types.
display	object	No	Display information for this payment instrument. Each payment instrument schema defines its specific display properties, as outlined by the payment handler.
selected	boolean	No	Whether this instrument is selected by the user.

Credencial de pagamento

Name	Type	Required	Description
type	string	Yes	The credential type discriminator. Specific schemas will constrain this to a constant value.

Endereço postal

Name	Type	Required	Description
extended_address	string	No	An address extension such as an apartment number, C/O or alternative name.
street_address	string	No	The street address.
address_locality	string	No	The locality in which the street address is, and which is in the region. For example, Mountain View.
address_region	string	No	The region in which the locality is, and which is in the country. Required for applicable countries (i.e. state in US, province in CA). For example, California or another appropriate first-level Administrative division.
address_country	string	No	The country. Recommended to be in 2-letter ISO 3166-1 alpha-2 format, for example "US". For backward compatibility, a 3-letter ISO 3166-1 alpha-3 country code such as "SGP" or a full country name such as "Singapore" can also be used.
postal_code	string	No	The postal code. For example, 94043.
first_name	string	No	Optional. First name of the contact associated with the address.
last_name	string	No	Optional. Last name of the contact associated with the address.
phone_number	string	No	Optional. Phone number of the contact associated with the address.

Resposta

Capability reference in responses. Only name/version required to confirm active capabilities.

Name	Type	Required	Description
version	string	Yes	Entity version in YYYY-MM-DD format.
spec	string	No	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.
extends	OneOf[string, array]	No	Parent capability(s) this extends. Present for extensions, absent for root capabilities. Use array for multi-parent extensions.

Total

Name	Type	Required	Description
type	string	Yes	Cost category. Well-known values: subtotal, items_discount, discount, fulfillment, tax, fee, total. Businesses MAY use additional values.
display_text	string	No	Text to display against the amount. Should reflect appropriate method (e.g., 'Shipping', 'Delivery').
amount	Signed Amount	Yes	Monetary amount in the currency's minor unit as defined by ISO 4217. Refer to the currency's exponent to determine minor-to-major ratio (e.g., 2 for USD, 0 for JPY, 3 for KWD). May be negative — the sign is intrinsic to the value (e.g., discounts are negative, charges are positive).

Contrato de RenderizaçãoAs empresas são a fonte oficial dos totais apresentados – seu conteúdo

e pedido - porque a apresentação correta está sujeita a regiões, produtos, e requisitos regulatórios que a empresa é obrigada a satisfazer (por exemplo, discriminação de impostos multijurisdicionais, divulgações de taxas obrigatórias).

As plataformas DEVEM renderizar todas as entradas de nível superior na ordem fornecida:python for entry in totals: render_line(entry.display_text, entry.amount)As plataformas PODEM renderizar sublinhados como detalhes suplementares:python for entry in totals: render_line(entry.display_text, entry.amount) if entry.lines: for sub in entry.lines: render_detail_line(sub.display_text, sub.amount)As plataformas NÃO DEVEM interpretar, filtrar, reordenar, agregar ou aplicar exibição lógica própria.

Invariantes de totals[]:

• Cada inscrição traz um type e um amount. Plataformas DEVEM usar display_text quando fornecido. Tipos conhecidos têm rótulos de exibição padrão como alternativa (ver tabela abaixo); tipos desconhecidos DEVEM incluir display_text.
• Os valores são números inteiros assinados — os valores negativos são subtrativos (por exemplo, descontos), os valores positivos são aditivos. O sinal É a direção.
• Exatamente um type: "subtotal" DEVE estar presente.
• Exatamente um type: "total" DEVE estar presente.

Verificação

As plataformas NÃO DEVEM substituir os seus próprios totais calculados pelos valores. As plataformas PODEM verificar os totais fornecidos:python assert sum(e.amount for e in totals if e.type != "total") == total_entry.amountCaso a soma computada não corresponda à entrada type: "total", a plataforma NÃO DEVE alterar a produção renderizada - os totais apresentados pelo negócio são autorizado para exibição. No entanto, as plataformas NÃO DEVEM concluir autonomamente um checkout com totais incompatíveis. As plataformas DEVEM rejeitar o checkout ou encaminhe e solicite a avaliação do comprador via continue_url.

Tipos bem conhecidos

Tipo	Assinar	Etiqueta padrão	Significado
subtotal	+	Subtotal	Soma dos preços dos itens de linha
discount	−	Desconto	Desconto em nível de pedido ou item de linha
items_discount	−	Descontos em itens	Acúmulo de descontos em itens de linha
fulfillment	+	Envio	Taxas de envio, entrega ou coleta
tax	+	Imposto	Encargos fiscais
fee	+	Taxa	Taxas e sobretaxas
total	=	Total	Total geral oficial (exatamente um)

Quando display_text é fornecido, as plataformas DEVEM utilizá-lo. Quando omitido em um tipo bem conhecido, as plataformas DEVEM usar o rótulo padrão acima. O sinal convenção para tipos bem conhecidos é imposta pelo esquema: tipos subtrativos (desconto, items_discount) DEVE ter valores negativos; tipos de aditivos (subtotal, cumprimento, imposto, taxa) DEVE ter valores não negativos.

O campo type é uma string aberta — as empresas PODEM usar valores além do conjunto bem conhecido. Tipos desconhecidos DEVEM incluir display_text (aplicado por esquema) e o sinal do valor é autodescritivo.

Tipos de repetição

Todos os tipos, exceto subtotal e total, PODEM aparecer várias vezes — por exemplo, linhas fiscais multijurisdicionais ou taxas discriminadas.

Sublinhas (lines)

Cada entrada de nível superior PODE incluir uma matriz lines. Sublinhas compartilham o mesmo forma base como entradas de nível superior - display_text e amount - fornecendo um detalhamento discriminado sob o pai.

Invariante: sum(lines[].amount) DEVE ser igual ao amount da entrada pai.

A empresa controla o que DEVE ser renderizado (entradas de nível superior) versus o que PODE ser opcionalmente revestido (sublinhas). As plataformas DEVEM renderizar sublinhados quando fornecido.

Exemplos

Imposto dividido, discriminado em nível superior:json [ { "type": "subtotal", "display_text": "Subtotal", "amount": 5750 }, { "type": "fulfillment", "display_text": "Shipping", "amount": 899 }, { "type": "tax", "display_text": "Federal Tax", "amount": 332 }, { "type": "tax", "display_text": "State Tax", "amount": 465 }, { "type": "total", "display_text": "Total", "amount": 7446 } ]Taxas recolhidas com detalhamento opcional:json [ { "type": "subtotal", "display_text": "Subtotal", "amount": 4999 }, { "type": "fee", "display_text": "Fees", "amount": 549, "lines": [ { "display_text": "Service Fee", "amount": 399 }, { "display_text": "Recycling Fee", "amount": 150 } ] }, { "type": "tax", "display_text": "Tax", "amount": 444 }, { "type": "total", "display_text": "Total", "amount": 5992 } ]Desconto e crédito em conta — valores negativos:json [ { "type": "subtotal", "display_text": "Subtotal", "amount": 10000 }, { "type": "discount", "display_text": "Summer Sale", "amount": -1500 }, { "type": "tax", "display_text": "Tax", "amount": 680 }, { "type": "account_credit", "display_text": "Account Credit", "amount": -2500 }, { "type": "total", "display_text": "Amount Due", "amount": 6680 } ]### Verificação de resposta BCP {: #ucp-response-checkout-schema }

UCP metadata for checkout responses.

Name	Type	Required	Description
version	string	Yes	UCP version in YYYY-MM-DD format.
status	string	No	Application-level status of the UCP operation. Enum: success, error
services	object	No	Service registry keyed by reverse-domain name.
capabilities	object	No	Capability registry keyed by reverse-domain name.
payment_handlers	object	Yes	Payment handler registry keyed by reverse-domain name.
services	any	No
capabilities	any	No
payment_handlers	any	Yes

Confirmação do pedido

Name	Type	Required	Description
id	string	Yes	Unique order identifier.
label	string	No	Human-readable label for identifying the order. MUST only be provided by the business.
permalink_url	string	Yes	Permalink to access the order on merchant site.

Resposta de erro

Name	Type	Required	Description
ucp	any	Yes	UCP protocol metadata. Status MUST be 'error' for error response.
messages	Array[Message]	Yes	Array of messages describing why the operation failed.
continue_url	string	No	URL for buyer handoff or session recovery.