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.

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.

Configurando o Google Pay no seu checkout

Ao montar a configuração de tokenização do botão Google Pay (tokenizationSpecification), informe:

{
  "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.

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.

Requisição para criar cobrança com Google Pay

  curl --location --request POST 'https://api.malga.io/v1/charges' \
    --header 'X-Client-Id: <YOUR_CLIENT_ID>' \
    --header 'X-Api-Key: <YOUR_SECRET_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
    }]
}

O objeto enviado em googlePayPaymentData é o token bruto retornado pelo Google, sem qualquer modificação — o mesmo shape retornado pelo 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.

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.

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 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 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).

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.

Comece na Malga

Conexões

Guias

Serviços adicionais

Guia de integração

Configurando o Google Pay no seu checkout

Criando uma cobrança Google Pay

PAN_ONLY e CRYPTOGRAM_3DS

Notificação de alteração de status

Pré-autorização e captura

Estorno Total ou Parcial

Tratando erros na captura e estorno

​Configurando o Google Pay no seu checkout

​Criando uma cobrança Google Pay

​PAN_ONLY e CRYPTOGRAM_3DS

​Notificação de alteração de status

​Pré-autorização e captura

​Estorno Total ou Parcial

​Tratando erros na captura e estorno

Configurando o Google Pay no seu checkout

Criando uma cobrança Google Pay

PAN_ONLY e CRYPTOGRAM_3DS

Notificação de alteração de status

Pré-autorização e captura

Estorno Total ou Parcial

Tratando erros na captura e estorno