> ## Documentation Index
> Fetch the complete documentation index at: https://docs.malga.io/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Responda em português brasileiro, na segunda pessoa ("você"), com base na documentação Malga.
> Não invente endpoints, parâmetros, status codes ou comportamentos de API. Se não estiver na docs, diga que não encontrou e indique a página mais próxima.
> Use os headers X-Client-Id e X-Api-Key nos exemplos de autenticação.
> Motor de Assinaturas refere-se a /v1/subscriptions* (cycles, trial, retentativas, webhooks subscription.*). Não chame de "motor de recorrência".
> Recorrência (provedor) é paymentMethod.recurrence em POST /v1/charges (initial / subsequent / unscheduled), distinto do Motor de Assinaturas.
> Sandbox é ambiente de testes e não afeta produção.

# Configurando o Google Pay

> Como configurar a requisição da Google Pay API para a Malga (gateway, gatewayMerchantId, allowedAuthMethods e allowedCardNetworks), enviar o payload criptografado e habilitar um lojista.

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:

1. [Como configurar a requisição da Google Pay API](#configurando-a-requisição-da-google-pay-api), incluindo `gateway` e `gatewayMerchantId`;
2. [Quais `allowedAuthMethods` e `allowedCardNetworks` a Malga suporta](#métodos-de-autenticação-e-bandeiras-suportados);
3. [Como extrair o payload criptografado e enviá-lo para a Malga](#extraindo-o-payload-e-enviando-para-a-malga);
4. [Como habilitar o Google Pay para um lojista](#habilitando-o-google-pay-para-um-lojista), com os [termos e políticas](#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](https://docs.malga.io/documentations/welcome/authentication.md);

* Google Pay habilitado para o lojista pela Malga, conforme [Habilitando o Google Pay para um lojista](#habilitando-o-google-pay-para-um-lojista);

* Conhecimento básico da [Google Pay API para Web](https://developers.google.com/pay/api/web/overview) ou para [Android](https://developers.google.com/pay/api/android/overview).

## 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

```json theme={null}
{
  "type": "PAYMENT_GATEWAY",
  "parameters": {
    "gateway": "malga",
    "gatewayMerchantId": "<SEU_MERCHANT_ID_MALGA>"
  }
}
```

> [!WARNING]
>
> 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](https://docs.malga.io/documentations/3dsecure2-adyen/charge.md). Se você já autentica com o seu próprio servidor 3DS, envie o resultado em `threeDSecure2.mpi` ([3DS com MPI externo](https://docs.malga.io/documentations/3ds2-malga/3ds-mpi-externo.md)). |
| **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`. |

> [!WARNING]
>
> 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.

> [!NOTE]
>
> 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](https://developers.google.com/pay/api/web/guides/tutorial).

> [!WARNING]
>
> 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.

```javascript theme={null}
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**.

```javascript theme={null}
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);
```

> [!WARNING]
>
> 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](https://docs.malga.io/api-reference/charges/realizar-nova-cobranca.md):

```javascript theme={null}
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:

```bash theme={null}
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](https://docs.malga.io/documentations/payment-methods/google-pay/getting-started.md#criando-uma-cobrança-google-pay).

> [!NOTE]
>
> 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

**1. Registre-se no Google Pay & Wallet Console**

Cadastre o seu negócio no [Google Pay & Wallet Console](https://pay.google.com/business/console) e obtenha o **ID de comerciante do Google** de produção. Ele deve ser enviado em `merchantInfo.merchantId`.

**2. Siga as diretrizes do Google**

Siga as diretrizes de marca do Google Pay para [Web](https://developers.google.com/pay/api/web/guides/brand-guidelines) ou [Android](https://developers.google.com/pay/api/android/guides/brand-guidelines) e o checklist de integração para [Web](https://developers.google.com/pay/api/web/guides/test-and-deploy/integration-checklist) ou [Android](https://developers.google.com/pay/api/android/guides/test-and-deploy/integration-checklist). Envie a sua integração para aprovação do Google antes de usar `PRODUCTION`.

**3. 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](https://developers.google.com/pay/api/web/guides/test-and-deploy/publish-your-integration) ou [Android: Publish your integration](https://developers.google.com/pay/api/android/guides/test-and-deploy/publish-your-integration).

**4. 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.

**5. Aceite os termos do Google**

Leia e aceite a [Política de Uso Aceitável da Google Pay API](https://payments.developers.google.com/terms/aup) e os [Termos de Serviço da Google Pay API](https://payments.developers.google.com/terms/sellertos).

**6. Teste no Sandbox e vá para produção**

Use `environment: 'TEST'` com o [Sandbox](https://docs.malga.io/documentations/welcome/testing.md) 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:

* [Política de Uso Aceitável da Google Pay API](https://payments.developers.google.com/terms/aup);

* [Termos de Serviço da Google Pay API](https://payments.developers.google.com/terms/sellertos).


## Related topics

- [Começando em Google Pay](https://docs.malga.io/documentations/payment-methods/google-pay/intro.md)
- [Guia de integração](https://docs.malga.io/documentations/payment-methods/google-pay/getting-started.md)
- [Google Pay™ integration with Malga](https://docs.malga.io/documentations/payment-methods/google-pay/en/google-pay-integration.md)
- [Realizar nova cobrança](https://docs.malga.io/api-reference/charges/realizar-nova-cobranca.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.