> ## 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. # Guia de integração O Google Pay opera no modelo **PAYMENT\_GATEWAY** do Google: a Malga é o gateway/PSP e suporta várias chaves privadas ativas ao mesmo tempo, para que a chave antiga e a nova convivam durante a rotação de chaves. A Malga registra a nova chave pública no Google Pay & Wallet Console e só retira a antiga quando ela deixa de ser usada. Não há necessidade de certificado ou chave por lojista. Para processar cobranças Google Pay você só precisa configurar corretamente o botão Google Pay no seu checkout, informando o `gateway` e o seu próprio `gatewayMerchantId`. > [!NOTE] > > Para o passo a passo completo da requisição da Google Pay API (`gateway`, > `gatewayMerchantId`, `allowedAuthMethods`, `allowedCardNetworks`), da extração > do payload e da habilitação do lojista, veja [Configurando o Google > Pay](https://docs.malga.io/documentations/payment-methods/google-pay/configurando-google-pay.md). ## Configurando o Google Pay no seu checkout Ao montar a configuração de tokenização do botão Google Pay (`tokenizationSpecification`), informe: ```json theme={null} { "type": "PAYMENT_GATEWAY", "parameters": { "gateway": "malga", "gatewayMerchantId": "" } } ``` > [!WARNING] > > O `gatewayMerchantId` deve ser o mesmo `merchantId` que você utiliza para > criar cobranças na Malga. ## Criando uma cobrança Google Pay * Para criar uma transação com Google Pay basta o cliente informar o meio de pagamento *google\_pay* na criação de uma cobrança e o token bruto retornado pelo `loadPaymentData` do Google Pay JS/Android; * Uma cobrança é feita no cartão através do provedor configurado no fluxo inteligente; * Após confirmação do pagamento, o provedor enviará uma notificação para a Malga informando que o pagamento foi realizado; * Posteriormente o cliente recebedor será notificado de que o pagamento foi efetuado e a cobrança finalizada com sucesso. Realize uma cobrança a partir do token Google Pay usando o [Serviço de Charges](https://docs.malga.io/api-reference/charges/realizar-nova-cobranca.md). > [accordion] Requisição para criar cobrança com Google Pay > > ```bash theme={null} > curl --location --request POST 'https://api.malga.io/v1/charges' \ > --header 'X-Client-Id: ' \ > --header 'X-Api-Key: ' \ > --header 'Content-Type: application/json' \ > --data-raw '{ > "merchantId": "7f8870a2-71c9-4ef0-a531-82000e00b7e1", > "amount": 150, > "currency": "BRL", > "statementDescriptor": "Compra #123", > "capture": false, > "paymentMethod": { > "paymentType": "google_pay", > "installments": 1 > }, > "paymentSource": { > "sourceType": "wallet", > "googlePayPaymentData": { > "protocolVersion": "ECv2", > "signature": "MEQCIH6Q4OwQ0jAceFEkGF0JID6sJNXxOEi4r+mA7biRxqBQAiAondqoUpU/bdsrAOpZIsrHQS9nwiiNwOrr24RyPeHA0Q==", > "intermediateSigningKey": { > "signedKey": "{\"keyExpiration\":\"1542323393147\",\"keyValue\":\"MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAE/1+3HBVSbdv+j7NaArdgMyoSAM43yRydzqdg1TxodSzA96Dj4Mc1EiKroxxunavVIvdxGnJeFViTzFvzFRxyCw==\"}", > "signatures": ["MEYCIQCO2EIi48s8VTH+ilMEpoXLFfkxAwHjfPSCVED/QDSHmQIhALLJmrUlNAY8hDQRV/y1iKZGsWpeNmIP+z+tCQHQxP0v"] > }, > "signedMessage": "{\"tag\":\"jpGz1F1Bcoi/fCNxI9n7Qrsw7i7KHrGtTf3NrRclt+U=\",\"ephemeralPublicKey\":\"BJatyFvFPPD21l8/uLP46Ta1hsKHndf8Z+tAgk+DEPQgYTkhHy19cF3h/bXs0tWTmZtnNm+vlVrKbRU9K8+7cZs=\",\"encryptedMessage\":\"mKOoXwi8OavZ\"}" > } > } > }' > > < HTTP/2 201 > < content-type: application/json; charset=utf-8 > { > "id": "10ad53ec-76bb-41d2-a0fe-7513f8f50a8f", > "merchantId": "7f8870a2-71c9-4ef0-a531-82000e00b7e1", > "clientId": "cc0b1e41-2936-45c5-947f-93995ffcdc00", > "createdAt": "2021-03-23T15:12:38.379Z", > "amount": 150, > "originalAmount": 150, > "currency": "BRL", > "statementDescriptor": "Compra #123", > "capture": false, > "status": "pre_authorized", > "paymentMethod": { > "paymentType": "google_pay", > "installments": 1 > }, > "paymentSource": { > "sourceType": "wallet", > "cardId": "148d5db0-f1c3-439f-902d-f1f268086e1d" > }, > "transactionRequests": [{ > "id": "5e506984-318a-4390-b87a-a3bd9b91d357", > "updatedAt": "2021-03-23T15:12:42.799Z", > "createdAt": "2021-03-23T15:12:38.392Z", > "idempotencyKey": "4271e96e-8c2f-4857-a122-279613bc4747", > "requestId": null, > "providerId": "72cc1ff1-5f6e-4eb2-9cc5-6a3a85525e4b", > "providerType": "CIELO", > "amount": 150, > "authorizationCode": "", > "authorizationNsu": "1616512362092", > "responseCode": "20000", > "requestStatus": "success", > "requestType": "pre_authorization", > "responseTs": null > }] > } > ``` > [!NOTE] > > O objeto enviado em `googlePayPaymentData` é o token bruto retornado pelo > Google, sem qualquer modificação — o mesmo shape retornado pelo > [`loadPaymentData`](https://developers.google.com/pay/api/web/reference/client#loadPaymentData) > do Google Pay JS API ou pelo SDK Android. No Web, o campo > `paymentData.paymentMethodData.tokenizationData.token` é uma string JSON: > converta com `JSON.parse` antes de enviar. Veja > [Extraindo o payload e enviando para a > Malga](https://docs.malga.io/documentations/payment-methods/google-pay/configurando-google-pay.md#extraindo-o-payload-e-enviando-para-a-malga). Quando criada na Malga, a cobrança Google Pay: * É registrada com status `authorized`, `pre_authorized` ou `failed` (ou `pending` enquanto um desafio 3D Secure está em andamento); * É possível realizar o estorno total ou parcial da cobrança; * É possível realizar a pré-autorização e captura da cobrança. ## PAN\_ONLY e CRYPTOGRAM\_3DS A Malga suporta o método de autenticação (`authMethod`) para o cartão salvo pelo comprador: | authMethod | Descrição | | - | - | | **PAN\_ONLY** | O cartão é enviado sem cryptogram, seguindo o fluxo normal de cobrança por cartão. | | **CRYPTOGRAM\_3DS** | O cartão é enviado com cryptogram e ECI, seguindo o fluxo de rede de token (liability shift do 3DS). | Veja os valores de `allowedAuthMethods` e `allowedCardNetworks` aceitos em [Métodos de autenticação e bandeiras suportados](https://docs.malga.io/documentations/payment-methods/google-pay/configurando-google-pay.md#métodos-de-autenticação-e-bandeiras-suportados). > [!WARNING] > > **Retentativa entre provedores (smart flow) e CRYPTOGRAM\_3DS**: o cryptogram de uma cobrança Google Pay não é reaproveitado > numa segunda tentativa em outro provedor caso a primeira falhe. Isso evita > reenviar a um adquirente diferente um cryptogram já consumido. Se a primeira > tentativa falhar de forma retentável, a retentativa seguinte falha de forma > previsível em vez de reutilizar o cryptogram original. ## Notificação de alteração de status | objeto | evento | descrição | | - | - | - | | *transaction* | *pending* | Evento enviado quando a cobrança é criada na Malga | | *transaction* | *pre\_authorized* | Evento enviado quando é pre-autorizado o pagamento, com reserva de saldo | | *transaction* | *authorized* | Evento enviado quando é autorizado o pagamento | | *transaction* | *failed* | Evento enviado quando a cobrança é negada pela instituição financeira antes de ter sido autorizada, sem estorno financeiro | | *transaction* | *canceled* | Evento enviado quando a cobrança é cancelada antes ter sido capturada, não produzindo um estorno financeiro | | *transaction* | *voided* | Evento enviado quando a cobrança é cancelada após ter sido autorizada, produzindo um estorno financeiro | | *transaction* | *charged\_back* | Evento enviado quando a cobrança é contestada por fraude | ## Pré-autorização e captura No fluxo de pagamentos por cartão é possível realizar uma autorização que reserva o saldo e fica pendente de uma captura posterior, ou você pode já autorizar o pagamento de maneira definitiva. O flag de `capture` serve para indicar se a transação deve ou não ser capturada. Na nossa API caso você envie o atributo `capture: false` iremos retornar a transação autorizada (saldo reservado no cartão) com status `pre_authorized` sendo necessário que você faça um request no [Serviço de Captura](https://docs.malga.io/api-reference/charges/capturar-cobranca-pre-autorizada.md) para forçar manualmente a captura da transação e liberar para liquidação na conta do provedor. Se a transação não for capturada em 7 dias o adquirente pode desfazer automaticamente a transação. Caso você envie o atributo `capture: true` iremos retornar a transação autorizada com status `authorized`, não sendo necessário mais nenhuma ação, a transação já fica liberada para liquidação no adquirente e não precisa chamar o Serviço de Captura. Em nosso dashboard, também é possível *capturar*. ## Estorno Total ou Parcial No fluxo de pagamento por Google Pay, é possível realizar um estorno no valor total ou parcial da cobrança. No caso de estorno parcial, o lojista opta por realizar um estorno com valor inferior ao valor da venda, sendo feito o reembolso do valor parcial estornado para o comprador, permanecendo a cobrança como autorizada para liquidação do valor restante para o lojista. Para realizar um estorno parcial, basta enviar na [requisição de void](https://docs.malga.io/api-reference/charges/estornar-cobranca-aprovada.md) um `amount` inferior ao valor original da transação, sendo este `amount` do estorno o valor a ser estornado. Uma vez aprovada a solicitação de estorno parcial junto ao emissor do cartão, o `amount` da transação é então atualizado para o valor residual da transação após o estorno (valor da cobrança - valor estornado). > [!WARNING] > > O atributo `originalAmount` do objeto `charge` se mantém como o valor > originalmente autorizado na transação, é o valor inicial da transação quando > aprovada. Já o atributo `amount` do objeto `charge` é alterado a cada > solicitação de estorno parcial, mantendo o saldo residual a receber pelo > lojista. ## Tratando erros na captura e estorno As modificações feitas em uma cobrança para fins de estorno total, estorno parcial, ou captura podem retornar com erro no provedor. A fim de garantir o correto tratamento dos casos de exceção retornado pelos provedores nestas operações, nossa API, ao receber erro na captura/estorno, retorna HTTP Status Code 201, sendo criado um novo transactionRequest com o status `failed`, porém não é modificado o status original da transação. **É recomendado que você verifique o status do objeto charge retornado, ou o status do primeiro objeto da lista de transactionRequests para se certificar que a operação foi realizada com sucesso.** ## Related topics - [Guia de integração](https://docs.malga.io/documentations/payment-methods/apple-pay/getting-started.md) - [Começando em ApplePay](https://docs.malga.io/documentations/payment-methods/apple-pay/intro.md) - [Começando em Google Pay](https://docs.malga.io/documentations/payment-methods/google-pay/intro.md) - [Tratamento de erros na integração](https://docs.malga.io/documentations/welcome/errors.md) This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.