Configurando o Google Pay

A Malga é um PSP do Google Pay com gatewayId malga, no modelo PAYMENT_GATEWAY: o seu checkout recebe o pagamento criptografado do Google e o repassa, sem modificações, para a API da Malga, que o descriptografa e processa a cobrança. Esta página mostra, em ordem:

Como configurar a requisição da Google Pay API, incluindo gateway e gatewayMerchantId;
Quais allowedAuthMethods e allowedCardNetworks a Malga suporta;
Como extrair o payload criptografado e enviá-lo para a Malga;
Como habilitar o Google Pay para um lojista, com os termos e políticas do Google.

Pré-requisitos

Credenciais da Malga (X-Client-Id e X-Api-Key) e o merchantId do lojista na Malga. Veja Autenticação;
Google Pay habilitado para o lojista pela Malga, conforme Habilitando o Google Pay para um lojista;
Conhecimento básico da Google Pay API para Web ou para Android.

Configurando a requisição da Google Pay API

A integração com o Google Pay usa dois objetos da Google Pay API:

IsReadyToPayRequest: verifica se o comprador pode pagar com Google Pay e permite exibir o botão;
PaymentDataRequest: solicita o pagamento e informa ao Google que o token deve ser gerado para a Malga.

Valores para a Malga

Parâmetro	Valor
`tokenizationSpecification.type`	`PAYMENT_GATEWAY`
`tokenizationSpecification.parameters.gateway`	`malga`
`tokenizationSpecification.parameters.gatewayMerchantId`	O `merchantId` do lojista na Malga
`allowedAuthMethods`	`["PAN_ONLY", "CRYPTOGRAM_3DS"]`
`allowedCardNetworks`	`["AMEX", "DISCOVER", "ELO", "MASTERCARD", "VISA"]`
`environment` (`PaymentsClient`)	`TEST` com o Sandbox da Malga, `PRODUCTION` com a produção da Malga
`merchantInfo.merchantId`	O ID de comerciante do Google (Google Pay & Wallet Console)

tokenizationSpecification

{
  "type": "PAYMENT_GATEWAY",
  "parameters": {
    "gateway": "malga",
    "gatewayMerchantId": "<SEU_MERCHANT_ID_MALGA>"
  }
}

O gatewayMerchantId deve ser o mesmo merchantId que você utiliza para criar cobranças na Malga. Ele não é o ID de comerciante do Google (merchantInfo.merchantId), que vem do Google Pay & Wallet Console. A Malga recusa um token cujo gatewayMerchantId não corresponda ao merchantId da cobrança.

Métodos de autenticação e bandeiras suportados

allowedAuthMethods

A Malga suporta os dois métodos de autenticação do Google Pay. Informe ambos em allowedAuthMethods:

authMethod	Como a Malga processa
PAN_ONLY	O cartão é processado como uma cobrança de cartão comum. Para solicitar 3D Secure 2, peça à Malga a habilitação do 3DS2 em um provedor do lojista que o suporte e envie o objeto `threeDSecure2` sem `setupId` na mesma cobrança, como em 3D Secure 2 no provedor. Se você já autentica com o seu próprio servidor 3DS, envie o resultado em `threeDSecure2.mpi` (3DS com MPI externo).
CRYPTOGRAM_3DS	O pagamento chega como token de rede, com cryptogram e ECI. O provedor configurado para o lojista precisa suportar token de rede. Caso contrário, a cobrança é recusada com o código `payment_not_supported`.

Para evitar recusas payment_not_supported, confirme com a Malga se o provedor do lojista suporta token de rede antes de manter CRYPTOGRAM_3DS em allowedAuthMethods.

allowedCardNetworks

A Malga aceita as bandeiras AMEX, DISCOVER, ELO, MASTERCARD e VISA. O provedor configurado para o lojista também precisa aceitar a bandeira do cartão: se o provedor não a aceitar, a cobrança não é processada.

Informe apenas as bandeiras que o provedor do lojista aceita. O Google Pay exibe ao comprador somente os cartões das bandeiras que você listar.

País de liquidação: a Malga não restringe a liquidação a uma lista fixa de países. Os países e regiões de liquidação suportados dependem inteiramente do provedor (adquirente) configurado para o lojista na Malga. Confirme com a Malga em quais países o provedor do lojista liquida.

Exemplo completo

O exemplo abaixo monta o IsReadyToPayRequest e o PaymentDataRequest com os valores da Malga, seguindo o tutorial da Google Pay API para Web.

O exemplo usa environment: 'TEST' e dados fictícios, compatíveis com o Sandbox da Malga. Nada é cobrado de verdade e a produção não é afetada. Ao ir para produção, troque para PRODUCTION e use o ID de comerciante do Google e o merchantId de produção da Malga.

const baseRequest = {
  apiVersion: 2,
  apiVersionMinor: 0,
};

const tokenizationSpecification = {
  type: 'PAYMENT_GATEWAY',
  parameters: {
    gateway: 'malga',
    gatewayMerchantId: 'YOUR_MALGA_MERCHANT_ID',
  },
};

const baseCardPaymentMethod = {
  type: 'CARD',
  parameters: {
    allowedAuthMethods: ['PAN_ONLY', 'CRYPTOGRAM_3DS'],
    allowedCardNetworks: ['AMEX', 'DISCOVER', 'ELO', 'MASTERCARD', 'VISA'],
  },
};

const cardPaymentMethod = {
  ...baseCardPaymentMethod,
  tokenizationSpecification,
};

// Use 'PRODUCTION' com a produção da Malga.
const paymentsClient = new google.payments.api.PaymentsClient({
  environment: 'TEST',
});

// IsReadyToPayRequest: define se o botão Google Pay deve ser exibido.
const isReadyToPayRequest = {
  ...baseRequest,
  allowedPaymentMethods: [baseCardPaymentMethod],
};

paymentsClient
  .isReadyToPay(isReadyToPayRequest)
  .then((response) => {
    if (response.result) {
      // Exiba o botão Google Pay, por exemplo com paymentsClient.createButton(...)
    }
  })
  .catch(console.error);

// PaymentDataRequest: solicita o pagamento.
const paymentDataRequest = {
  ...baseRequest,
  allowedPaymentMethods: [cardPaymentMethod],
  transactionInfo: {
    totalPriceStatus: 'FINAL',
    totalPrice: '1.50',
    currencyCode: 'BRL',
    countryCode: 'BR',
  },
  merchantInfo: {
    merchantName: 'Minha Loja',
    // ID de comerciante do Google (Google Pay & Wallet Console).
    // Em TEST, o Google aceita um valor de teste.
    merchantId: 'YOUR_GOOGLE_MERCHANT_ID',
  },
};

Extraindo o payload e enviando para a Malga

Após o comprador confirmar o pagamento, o loadPaymentData devolve o paymentData. O payload criptografado está em paymentData.paymentMethodData.tokenizationData.token, que é uma string JSON.

paymentsClient
  .loadPaymentData(paymentDataRequest)
  .then((paymentData) => {
    // String JSON criptografada, gerada pelo Google para a Malga.
    const token = paymentData.paymentMethodData.tokenizationData.token;

    // Envie para o SEU servidor, sem alterar o conteúdo.
    return fetch('/seu-backend/google-pay/charge', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ token }),
    });
  })
  .catch(console.error);

Nunca chame POST /v1/charges direto do navegador: a requisição exige o X-Api-Key, que é uma chave secreta. Envie o token para o seu servidor e crie a cobrança de lá.

No seu servidor, converta a string em objeto com JSON.parse e envie o resultado em paymentSource.googlePayPaymentData na criação da cobrança:

const googlePayPaymentData = JSON.parse(token);

const response = await fetch('https://api.malga.io/v1/charges', {
  method: 'POST',
  headers: {
    'X-Client-Id': 'YOUR_CLIENT_ID',
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    merchantId: 'YOUR_MALGA_MERCHANT_ID',
    amount: 150,
    currency: 'BRL',
    statementDescriptor: 'Compra #123',
    capture: false,
    paymentMethod: {
      paymentType: 'google_pay',
      installments: 1,
    },
    paymentSource: {
      sourceType: 'wallet',
      googlePayPaymentData,
    },
  }),
});

Ou, em cURL:

curl --location --request POST 'https://api.malga.io/v1/charges' \
  --header 'X-Client-Id: YOUR_CLIENT_ID' \
  --header 'X-Api-Key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "merchantId": "YOUR_MALGA_MERCHANT_ID",
    "amount": 150,
    "currency": "BRL",
    "statementDescriptor": "Compra #123",
    "capture": false,
    "paymentMethod": {
      "paymentType": "google_pay",
      "installments": 1
    },
    "paymentSource": {
      "sourceType": "wallet",
      "googlePayPaymentData": {
        "protocolVersion": "ECv2",
        "signature": "<signature do token>",
        "intermediateSigningKey": {
          "signedKey": "<signedKey do token>",
          "signatures": ["<assinatura da signedKey>"]
        },
        "signedMessage": "<signedMessage do token>"
      }
    }
  }'

Para a resposta, o ciclo de vida da cobrança (captura, estorno e notificações) e um exemplo completo, veja o Guia de integração.

Não descriptografe, valide nem altere o token: a Malga recebe exatamente o que o Google devolveu. O objeto enviado em googlePayPaymentData tem o mesmo formato do JSON retornado em tokenizationData.token. A Malga aceita somente protocolVersion ECv2, e cada token pode ser usado em uma única cobrança.

Habilitando o Google Pay para um lojista

Registre-se no Google Pay & Wallet Console

Cadastre o seu negócio no Google Pay & Wallet Console e obtenha o ID de comerciante do Google de produção. Ele deve ser enviado em merchantInfo.merchantId.

Siga as diretrizes do Google

Siga as diretrizes de marca do Google Pay para Web ou Android e o checklist de integração para Web ou Android. Envie a sua integração para aprovação do Google antes de usar PRODUCTION.

Publique a sua integração

Solicite o acesso de produção e obtenha o seu ID de comerciante do Google (merchantInfo.merchantId) no Google Pay & Wallet Console, seguindo o guia do Google para Web: Publish your integration ou Android: Publish your integration.

Peça a habilitação à Malga

Solicite à Malga a habilitação do Google Pay para o seu merchantId e de um provedor compatível. Confirme se o provedor aceita as bandeiras que você vai exibir e, se usar CRYPTOGRAM_3DS, se ele suporta token de rede.

Aceite os termos do Google

Leia e aceite a Política de Uso Aceitável da Google Pay API e os Termos de Serviço da Google Pay API.

Teste no Sandbox e vá para produção

Use environment: 'TEST' com o Sandbox da Malga. Em produção, use environment: 'PRODUCTION' com a produção da Malga.

Termos e políticas

Ao usar o Google Pay, você concorda com os termos do Google:

Comece na Malga

Conexões

Guias

Serviços adicionais

Configurando o Google Pay

Pré-requisitos

Configurando a requisição da Google Pay API

Valores para a Malga

tokenizationSpecification

Métodos de autenticação e bandeiras suportados

allowedAuthMethods

allowedCardNetworks

Exemplo completo

Extraindo o payload e enviando para a Malga

Habilitando o Google Pay para um lojista

Termos e políticas

​Pré-requisitos

​Configurando a requisição da Google Pay API

​Valores para a Malga

​tokenizationSpecification

​Métodos de autenticação e bandeiras suportados

​allowedAuthMethods

​allowedCardNetworks

​Exemplo completo

​Extraindo o payload e enviando para a Malga

​Habilitando o Google Pay para um lojista

​Termos e políticas

Pré-requisitos

Configurando a requisição da Google Pay API

Valores para a Malga

tokenizationSpecification

Métodos de autenticação e bandeiras suportados

allowedAuthMethods

allowedCardNetworks

Exemplo completo

Extraindo o payload e enviando para a Malga

Habilitando o Google Pay para um lojista

Termos e políticas