Google Pay™ integration with Malga

Google Pay™ lets users pay with the cards stored in their Google Account. Malga is a Google Pay PSP with gatewayId malga, using the PAYMENT_GATEWAY tokenization model. Malga supports multiple active private keys at the same time, so the old and new keys coexist during a key rotation: Malga registers the new public key in the Google Pay & Wallet Console and retires the old one only when it is no longer in use. Merchants don’t need their own certificate or key. Google Pay can be offered in two ways:

Direct gateway integration: the merchant renders the Google Pay button on its own checkout, receives the encrypted payload from Google and forwards it, unmodified, to the Malga API, which decrypts it and processes the charge.
Hosted Checkout: Malga hosts the checkout page, renders the Google Pay button and creates the charge. The merchant only enables Google Pay in the checkout session.

This document covers:

Prerequisites
Configuring the Google Pay API request, including gateway and gatewayMerchantId
Supported authentication methods and card networks
3D Secure for PAN_ONLY
Full example
Extracting the payload and sending it to Malga
Charge lifecycle
Enabling Google Pay for a merchant (direct integration)
Enabling Google Pay on Hosted Checkout
Terms and policies

Prerequisites

Malga credentials (X-Client-Id and X-Api-Key) and the merchant’s merchantId at Malga. See Authentication.
Google Pay enabled for the merchant by Malga, as described in Enabling Google Pay for a merchant.
For the direct integration, basic knowledge of the Google Pay API developer documentation for Web or for Android.

Configuring the Google Pay API request

The Google Pay integration uses two Google Pay API objects:

IsReadyToPayRequest: checks whether the buyer can pay with Google Pay and lets you show the button.
PaymentDataRequest: requests the payment and tells Google that the token must be generated for Malga.

Values for Malga

Parameter	Value
`tokenizationSpecification.type`	`PAYMENT_GATEWAY`
`tokenizationSpecification.parameters.gateway`	`malga`
`tokenizationSpecification.parameters.gatewayMerchantId`	The merchant’s `merchantId` at Malga
`allowedAuthMethods`	`["PAN_ONLY", "CRYPTOGRAM_3DS"]`
`allowedCardNetworks`	`["AMEX", "DISCOVER", "ELO", "MASTERCARD", "VISA"]`
`environment` (`PaymentsClient`)	`TEST` with Malga Sandbox, `PRODUCTION` with Malga production
`merchantInfo.merchantId`	The Google merchant ID (Google Pay & Wallet Console)

tokenizationSpecification

{
  "type": "PAYMENT_GATEWAY",
  "parameters": {
    "gateway": "malga",
    "gatewayMerchantId": "YOUR_MALGA_MERCHANT_ID"
  }
}

The gatewayMerchantId must be the same merchantId you use to create charges at Malga. It is not the Google merchant ID (merchantInfo.merchantId), which comes from the Google Pay & Wallet Console. Malga rejects a token whose gatewayMerchantId doesn’t match the merchantId of the charge.

Supported authentication methods and card networks

allowedAuthMethods

Malga supports both Google Pay authentication methods. Include both in allowedAuthMethods:

authMethod	How Malga processes it
PAN_ONLY	The card is processed as a regular card charge. To request 3D Secure, see 3D Secure for PAN_ONLY.
CRYPTOGRAM_3DS	The payment arrives as a network token, with cryptogram and ECI. The provider configured for the merchant must support network tokens. Otherwise, the charge is declined with the `payment_not_supported` code.

To avoid payment_not_supported declines, confirm with Malga that the merchant’s provider supports network tokens before keeping CRYPTOGRAM_3DS in allowedAuthMethods.

Country of settlement: Malga does not restrict settlement to a fixed list of countries. The supported settlement countries and regions depend entirely on the provider (acquirer) configured for the merchant at Malga. Confirm with Malga which countries the merchant’s provider settles in.

allowedCardNetworks

Malga accepts the AMEX, DISCOVER, ELO, MASTERCARD and VISA networks. The provider configured for the merchant must also accept the card network: if the provider does not accept it, the charge is not processed. Country of settlement: Malga does not restrict settlement to a fixed list of countries. The supported settlement countries and regions depend entirely on the provider (acquirer) configured for the merchant at Malga. Confirm with Malga which countries the merchant’s provider settles in.

List only the networks the merchant’s provider accepts. Google Pay shows the buyer only cards from the networks you list.

3D Secure for PAN_ONLY

A PAN_ONLY credential is a card number without a cryptogram, so the issuer has not authenticated the buyer. In the direct integration, to request 3D Secure 2 for these payments, send the threeDSecure2 object in the same POST /v1/charges request that carries googlePayPaymentData. CRYPTOGRAM_3DS credentials already carry a cryptogram and ECI, so they don’t need this step. To enable it:

Ask Malga to enable 3D Secure 2 on a provider configured for the merchant. The provider must support 3DS2 (see the list of supported providers). If no provider supports it, the charge is rejected.
Collect the buyer’s browser data on your checkout (user agent, accept header, language, screen size, color depth, time zone, Java/JavaScript flags and IP) and send it to your server together with the Google Pay token.
Add threeDSecure2 to the charge, as described in 3D Secure 2 with the provider. To know when it’s needed, set assuranceDetailsRequired: true in the card parameters of the PaymentDataRequest. Google then returns paymentData.paymentMethodData.info.assuranceDetails; when cardHolderAuthenticated is false (as with PAN_ONLY credentials), send threeDSecure2.
Handle the result. If the issuer approves without a challenge, the charge is returned as authorized or pre_authorized. If it requires a challenge, the charge is returned as pending, the buyer completes the challenge, and is sent back to your redirectURL. The final status arrives via webhook.

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": "Order #123",
    "capture": true,
    "paymentMethod": {
      "paymentType": "google_pay",
      "installments": 1
    },
    "paymentSource": {
      "sourceType": "wallet",
      "googlePayPaymentData": { "...": "the parsed Google Pay token" }
    },
    "threeDSecure2": {
      "redirectURL": "https://www.yourstore.com/checkout/return",
      "requestorURL": "https://www.yourstore.com",
      "browser": {
        "userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) ...",
        "acceptHeader": "text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8",
        "language": "en-US",
        "colorDepth": 24,
        "screenHeight": 1080,
        "screenWidth": 1920,
        "timeZoneOffset": "180",
        "javaEnabled": false,
        "javaScriptEnabled": true,
        "ip": "203.0.113.45"
      },
      "cardHolder": {
        "email": "buyer@example.com",
        "mobilePhone": "5511999999999"
      }
    }
  }'

For Google Pay, send threeDSecure2 without a setupId, as in the example above. If you already authenticate with your own 3DS server, send the result in threeDSecure2.mpi instead (3DS with an external MPI).

Full example

The example below builds the IsReadyToPayRequest and the PaymentDataRequest with Malga’s values, following the Google Pay API for Web tutorial.

The example uses environment: 'TEST' and fictitious data, compatible with Malga Sandbox. Nothing is actually charged and production is not affected. When going live, switch to PRODUCTION and use the Google merchant ID and the Malga production merchantId.

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' with Malga production.
const paymentsClient = new google.payments.api.PaymentsClient({
  environment: 'TEST',
});

// IsReadyToPayRequest: decides whether to show the Google Pay button.
const isReadyToPayRequest = {
  ...baseRequest,
  allowedPaymentMethods: [baseCardPaymentMethod],
};

paymentsClient
  .isReadyToPay(isReadyToPayRequest)
  .then((response) => {
    if (response.result) {
      // Show the Google Pay button, e.g. with paymentsClient.createButton(...)
    }
  })
  .catch(console.error);

// PaymentDataRequest: requests the payment.
const paymentDataRequest = {
  ...baseRequest,
  allowedPaymentMethods: [cardPaymentMethod],
  transactionInfo: {
    totalPriceStatus: 'FINAL',
    totalPrice: '1.50',
    currencyCode: 'BRL',
    countryCode: 'BR',
  },
  merchantInfo: {
    merchantName: 'My Store',
    // Google merchant ID (Google Pay & Wallet Console).
    // In TEST, Google accepts a test value.
    merchantId: 'YOUR_GOOGLE_MERCHANT_ID',
  },
};

Billing address

Malga doesn’t require a billing address or phone number from Google Pay to process the charge, so the example doesn’t set billingAddressRequired, billingAddressParameters or phoneNumberRequired. If you collect the customer’s address yourself, send it in the charge as usual (for example, in fraudAnalysis.customer.billingAddress).

Extracting the payload and sending it to Malga

After the buyer confirms the payment, loadPaymentData returns paymentData. The encrypted payload is in paymentData.paymentMethodData.tokenizationData.token, which is a JSON string.

paymentsClient
  .loadPaymentData(paymentDataRequest)
  .then((paymentData) => {
    // Encrypted JSON string, generated by Google for Malga.
    const token = paymentData.paymentMethodData.tokenizationData.token;

    // Send it to YOUR server, without changing its content.
    return fetch('/your-backend/google-pay/charge', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ token }),
    });
  })
  .catch(console.error);

Never call POST /v1/charges directly from the browser: the request requires the X-Api-Key, which is a secret key. Send the token to your server and create the charge from there.

On your server, convert the string into an object with JSON.parse and send the result in paymentSource.googlePayPaymentData when creating the charge:

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: 'Order #123',
    capture: false,
    paymentMethod: {
      paymentType: 'google_pay',
      installments: 1,
    },
    paymentSource: {
      sourceType: 'wallet',
      googlePayPaymentData,
    },
  }),
});

The Malga amount is in cents: 150 is R$ 1.50, the same value as totalPrice: '1.50' in the PaymentDataRequest.

Or, with 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": "Order #123",
    "capture": false,
    "paymentMethod": {
      "paymentType": "google_pay",
      "installments": 1
    },
    "paymentSource": {
      "sourceType": "wallet",
      "googlePayPaymentData": {
        "protocolVersion": "ECv2",
        "signature": "<token signature>",
        "intermediateSigningKey": {
          "signedKey": "<token signedKey>",
          "signatures": ["<signedKey signature>"]
        },
        "signedMessage": "<token signedMessage>"
      }
    }
  }'

Do not decrypt, validate or change the token: Malga receives exactly what Google returned. The object sent in googlePayPaymentData has the same shape as the JSON returned in tokenizationData.token. Malga accepts protocolVersion ECv2 only, and each token can be used in a single charge.

Charge lifecycle

A Google Pay charge is processed as a card charge through the provider configured in the merchant’s smart flow.

It is registered with status authorized, pre_authorized or failed (or pending while a 3D Secure challenge is in progress).
Pre-authorization and capture: send capture: false to reserve the amount (pre_authorized) and capture it later through the capture endpoint. Send capture: true to authorize and capture at once (authorized). The acquirer may automatically undo a pre-authorization that is not captured within 7 days.
Full or partial refund: send the void request, optionally with an amount lower than the original to refund part of it.

Status notifications

Object	Event	Description
`transaction`	`pending`	The charge was created at Malga
`transaction`	`pre_authorized`	The payment was pre-authorized, with the amount reserved
`transaction`	`authorized`	The payment was authorized
`transaction`	`failed`	The charge was declined before authorization, with no refund
`transaction`	`canceled`	The charge was canceled before capture, with no refund
`transaction`	`voided`	The charge was canceled after authorization, producing a refund
`transaction`	`charged_back`	The charge was disputed for fraud

Enabling Google Pay for a merchant (direct integration)

Register in the Google Pay & Wallet Console. Register your business in the Google Pay & Wallet Console and get the production Google merchant ID. It must be sent in merchantInfo.merchantId.
Follow Google’s guidelines. Build the integration with the Google Pay API developer documentation for Web or Android. Follow the Google Pay brand guidelines for Web or Android and the integration checklist for Web or Android. Submit your integration for Google’s approval before using PRODUCTION.
Publish your integration. Request production access and obtain your Google merchant ID (merchantInfo.merchantId) in the Google Pay & Wallet Console by following Google’s guide for Web: Publish your integration or Android: Publish your integration.
Ask Malga to enable it. Ask Malga to enable Google Pay for your merchantId and a compatible provider. Confirm that the provider accepts the networks you will show and, if you use CRYPTOGRAM_3DS, that it supports network tokens.
Accept Google’s terms. Read and accept the Google Pay API Acceptable Use Policy and the Google Pay API Terms of Service.
Test in Sandbox and go live. Use environment: 'TEST' with Malga Sandbox. In production, use environment: 'PRODUCTION' with Malga production.

Enabling Google Pay on Hosted Checkout

With Hosted Checkout, Malga hosts the payment page and integrates the Google Pay API on it. The merchant doesn’t write Google Pay code, register in the Google Pay & Wallet Console or have its own Google merchant ID: the Google Pay account and the Google merchant ID belong to Malga. If the merchant serves the checkout on its own domain, Malga registers that domain with Google. The hosted checkout is a redirect flow: send the buyer to the checkout URL. It can’t be embedded in an <iframe> on your site, because it is served with Content-Security-Policy: frame-ancestors 'self' and X-Frame-Options: SAMEORIGIN, so the iframe attributes allow="payment *" and sandbox don’t apply.

Ask Malga to enable Google Pay for your merchantId, with a provider that accepts the card networks you want to offer.
Accept Google’s terms. Before offering Google Pay to your buyers, read and accept the Google Pay API Acceptable Use Policy and the Google Pay API Terms of Service.
Add Google Pay to the checkout session. When you create the session, include an item with paymentType: "google_pay" and installments in paymentMethods. Google Pay can be offered alongside the other payment methods, including in sessions that use multiple.
"paymentMethods": [ { "paymentType": "credit", "installments": 1 }, { "paymentType": "google_pay", "installments": 1 } ]
Test in Sandbox. Validate the flow in Malga Sandbox before going live; Sandbox payments don’t affect production.

What the hosted checkout does for each payment:

Calls isReadyToPay and shows the official Google Pay button (createButton) only when Google confirms the buyer can pay.
Builds the PaymentDataRequest with gateway: "malga", the session’s merchantId as gatewayMerchantId, the merchant’s name as merchantInfo.merchantName, allowedAuthMethods PAN_ONLY and CRYPTOGRAM_3DS, and allowedCardNetworks AMEX, DISCOVER, ELO, MASTERCARD and VISA.
Collects the customer’s billing address (street, number, district, city, state, ZIP/postal code and country) and phone number in its own form, before showing the payment methods. It doesn’t request them from Google Pay (billingAddressRequired isn’t set) and uses the address from the form for the charge.
Creates the charge with paymentSource.sourceType: "wallet" and the token in googlePayPaymentData, as described in Extracting the payload and sending it to Malga.

Terms and policies

By using Google Pay, you agree to Google’s terms:

Comece na Malga

Conexões

Guias

Serviços adicionais

Google Pay™ integration with Malga

Prerequisites

Configuring the Google Pay API request

Values for Malga

tokenizationSpecification

Supported authentication methods and card networks

allowedAuthMethods

allowedCardNetworks

3D Secure for PAN_ONLY

Full example

Billing address

Extracting the payload and sending it to Malga

Charge lifecycle

Status notifications

Enabling Google Pay for a merchant (direct integration)

Enabling Google Pay on Hosted Checkout

Terms and policies

​Prerequisites

​Configuring the Google Pay API request

​Values for Malga

​tokenizationSpecification

​Supported authentication methods and card networks

​allowedAuthMethods

​allowedCardNetworks

​3D Secure for PAN_ONLY

​Full example

​Billing address

​Extracting the payload and sending it to Malga

​Charge lifecycle

​Status notifications

​Enabling Google Pay for a merchant (direct integration)

​Enabling Google Pay on Hosted Checkout

​Terms and policies

Prerequisites

Configuring the Google Pay API request

Values for Malga

tokenizationSpecification

Supported authentication methods and card networks

allowedAuthMethods

allowedCardNetworks

3D Secure for PAN_ONLY

Full example

Billing address

Extracting the payload and sending it to Malga

Charge lifecycle

Status notifications

Enabling Google Pay for a merchant (direct integration)

Enabling Google Pay on Hosted Checkout

Terms and policies