Especificação do gerenciador de pagamentos do Google Pay

Nome do manipulador:com.google.pay
Versão: 2026-01-11

1. Introdução

O manipulador com.google.pay permite que as empresas ofereçam o Google Pay como uma opção de pagamento acelerada em plataformas compatíveis com UCP. A API Google Pay permite uma finalização de compra rápida, aos usuários acesso às formas de pagamento armazenadas na Conta do Google.

Esse manipulador permite um modelo de integração sem interface em que as empresas fornecem a configuração do Google Pay (como redes de cartão permitidas e parâmetros de gateway), e as plataformas processam a interação do lado do cliente com a API Google Pay para gerar um token de pagamento seguro.

1.1 Principais benefícios

Configuração universal:as empresas configuram o Google Pay uma vez usando JSON padrão, permitindo que qualquer plataforma autorizada renderize a interface de pagamento sem código de front-end personalizado.
Front-end desacoplado:as plataformas lidam com a complexidade da integração da API JavaScript ou do SDK do Google Pay, enquanto as empresas consomem o token resultante.
Tokenização segura:usa a tokenização integrada do Google para transmitir credenciais criptografadas diretamente ao provedor de serviços de pagamento (PSP) da empresa.

2. Integração de negócios

2.1 Requisitos

Antes de anunciar o Google Pay pela UCP, as empresas precisam:

Receba um ID do comerciante do Google Pay:necessário para o processamento no ambiente PRODUCTION. Registre-se no Console do Google Pay e da Carteira.
Verifique o suporte do PSP:confira se o provedor de serviços de pagamento (PSP) está na lista de processadores e gateways compatíveis para a tokenização do Google Pay.

2.2 Configuração do manipulador

As empresas anunciam o suporte ao Google Pay incluindo o manipulador na matriz de manipuladores de pagamento. A configuração segue estritamente a estrutura necessária para inicializar a API Google Pay.

2.2.1 Esquema de configuração

O objeto de configuração define o ambiente, a identidade comercial e as formas de pagamento permitidas.

Forma de pagamento do Google Pay

Com base no PaymentMethod do Google Pay.

Especificação de tokenização

Com base na TokenizationSpecification do Google Pay.

2.2.2 Exemplo de declaração de manipulador

{
  "payment": {
    "handlers": [
      {
        "id": "8c9202bd-63cc-4241-8d24-d57ce69ea31c",
        "name": "com.google.pay",
        "version": "2026-01-11",
        "spec": "https://pay.google.com/gp/p/ucp/2026-01-11/",
        "config_schema": "https://pay.google.com/gp/p/ucp/2026-01-11/schemas/config.json",
        "instrument_schemas": [
          "https://pay.google.com/gp/p/ucp/2026-01-11/schemas/card_payment_instrument.json"
        ],
        "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"
                }
              }
            }
          ]
        }
      }
    ]
  }
}

2.3 Entidades

2.3.1 Esquema de instrumentos

O instrumento do Google Pay (card_payment_instrument) estende o instrumento de pagamento com cartão básico. Ele herda campos de exibição padrão (como brand e last_digits) para garantir a renderização consistente do recibo, refinando o campo credential para transportar o payload específico de tokenização do Google Pay.

Comportamento da plataforma:a plataforma é responsável por mapear a resposta do Google Pay PaymentMethodData nessa estrutura antes de enviá-la à empresa.

Nome	Tipo	Obrigatório	Descrição
id	string	Sim	Um identificador exclusivo do instrumento de pagamento, atribuído pela plataforma.
handler_id	string	Sim	Identificador do manipulador do Google Pay.
tipo	string	Sim	Constante = `card`. Indica que esse instrumento se comporta como um card (herda campos de exibição de card).
marca	string	Sim	A rede do cartão (por exemplo, `visa`, `mastercard`). Mapeado do `info.cardNetwork` do Google Pay.
last_digits	string	Sim	Os quatro últimos dígitos do cartão. Mapeado do `info.cardDetails` do Google Pay.
rich_text_description	string	Não	Uma descrição opcional em rich text do card (por exemplo, Visa que termina em 1234 e expira em 12/2025.
rich_card_art	string (uri)	Não	Um URI opcional para uma imagem avançada que representa o card (por exemplo, arte do card do emissor).
billing_address	Endereço postal	Não	O endereço de faturamento associado ao cartão.
credencial	Payload de credencial	Não	Os dados de tokenização seguros retornados pelo Google Pay.

Payload de credencial

Esse objeto serve como o credential do instrumento. Ele é mapeado diretamente para Dados de tokenização do Google Pay.

Endereço postal

Esse objeto serve como o campo address. Ele é mapeado diretamente para PostalAddress.

3. Integração de plataformas

3.1 Requisitos

Antes de processar pagamentos com.google.pay, as plataformas precisam:

Ser capaz de carregar a API Google Pay para Web (ou o equivalente para Android).
Siga as diretrizes da marca do Google Pay ao renderizar o botão de pagamento.

3.2 Protocolo de pagamento

As plataformas PRECISAM seguir este fluxo para processar o manipulador:

Etapa 1: descobrir e configurar

A plataforma inicializa o cliente para gerenciar o ciclo de vida da API.

Referência:PaymentsClient

Etapa 2: verificar a prontidão para pagar

A plataforma verifica se o usuário pode fazer um pagamento com as formas de pagamento especificadas antes de mostrar o botão.

Referência:isReadyToPay

Etapa 3: criar a solicitação de pagamento

A plataforma monta o objeto de solicitação de dados de pagamento, incluindo a configuração do comerciante, as formas de pagamento e os detalhes da transação (preço e moeda).

Referência:PaymentDataRequest

Etapa 4: invocar a interação do usuário

A plataforma aciona a exibição da página de pagamento quando o usuário interage com o botão de pagamento.

Referência:loadPaymentData

Etapa 5: concluir a finalização da compra

Após uma interação bem-sucedida do usuário, a API Google Pay retorna um objeto PaymentInstrument na chave payment_data. A plataforma mapeia essa resposta para o esquema card_payment_instrument e envia a solicitação de conclusão da finalização da compra.

POST /checkout-sessions/{checkout_id}/complete

{
  "payment_data": {
    "id": "pm_1234567890abc",
    "handler_id": "8c9202bd-63cc-4241-8d24-d57ce69ea31c",
    "type": "card",
    "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\"...}"
    }
  },
  "risk_signals": {
      ...
  }
}

4. Processamento comercial

Ao receber um instrumento de pagamento do Google Pay, as empresas PRECISAM:

Validar manipulador:confirme se handler_id corresponde ao manipulador do Google Pay.
Extrair token:recupere a string de token de payment_data.credential.token.
Processar pagamento:transmita a string de token e os detalhes da transação para o endpoint do PSP.
- Observação: a maioria dos PSPs tem um campo específico para um "Payload do Google Pay" ou um "Token de rede".
Resposta de retorno:responda com o estado finalizado do pagamento (sucesso/falha).

5. Considerações sobre segurança

5.1 Segurança de token

PAYMENT_GATEWAY::ao usar esse tipo de tokenização, o token é criptografado especificamente para a parte da tokenização. A parte de encaminhamento não pode descriptografar esse token e precisa encaminhá-lo à parte de tokenização sem alterações.
DIRETO:se você usar a tokenização DIRECT, a empresa vai receber dados criptografados do cartão que precisam ser descriptografados. Isso aumenta significativamente o escopo de conformidade do PCI DSS e geralmente não é recomendado, a menos que a empresa seja um provedor de serviços compatível com PCI de nível 1.

5.2 Isolamento de ambiente

Modo TESTE:no ambiente TEST, o Google Pay retorna tokens fictícios. Elas não podem ser cobradas.
Modo PRODUÇÃO:cartões reais são usados. As empresas precisam garantir que as credenciais do PSP em config.allowed_payment_methods correspondam ao ambiente.

Especificação do gerenciador de pagamentos do Google Pay Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.