Google Pay

Accept Google Pay on the Ginger Payments hosted payment page, or in your own checkout.

With Google Pay, your customers pay with a card stored in their Google account. They don't enter card details. Google Pay works on mobile phones and computers, in most browsers and operating systems.

Google Pay terms

To accept Google Pay, you must follow the Google Pay APIs Acceptable Use Policy and accept the Google Pay API Terms of Service.

You can accept Google Pay in two ways:

Integration	How it works	Google registration
Hosted payment page	Ginger Payments shows the Google Pay button on the hosted payment page.	Not needed
Server-to-server	You show the Google Pay button in your own checkout and send the payment token to Ginger Payments.	Needed: you integrate with the Google Pay API

Hosted payment page

On the hosted payment page, you don't need to register with Google. Once Google Pay is active in your project, it appears on the hosted payment page along with your other payment methods. To send your customer straight to Google Pay, create the order with google-pay as the payment method:

curl https://api.dev.gingerpayments.com/v1/orders/ \
  --user "$API_KEY:" \
  --header "Content-Type: application/json" \
  --data '{
    "currency": "EUR",
    "amount": 995,
    "merchant_order_id": "EXAMPLE001",
    "description": "Example Google Pay order",
    "return_url": "https://www.example.com/order/EXAMPLE001",
    "webhook_url": "https://www.example.com/webhook",
    "transactions": [
      {
        "payment_method": "google-pay"
      }
    ],
    "customer": {
      "merchant_customer_id": "123456789",
      "email_address": "user@example.com",
      "first_name": "John",
      "last_name": "Smith",
      "address_type": "billing",
      "address": "100 Main St",
      "postal_code": "SW1A 1AA",
      "city": "London",
      "country": "GB",
      "locale": "en",
      "phone_numbers": ["+441234567890"],
      "ip_address": "198.51.100.1"
    }
  }'

Redirect your customer to the payment_url of the transaction in the response. Then handle the result as for any other payment: wait for the webhook and check the order status.

Server-to-server

With a server-to-server integration, you show the Google Pay button in your own checkout. Your customer either selects a card stored in their Google account or adds a new one. You pass the resulting payment token to Ginger Payments for processing.

Before you start, read Google's documentation and make sure your integration follows it:

Authentication methods

Google Pay returns cards with one of two authentication methods. Both are always enabled; you can't turn either of them off.

Method	What it means
`PAN_ONLY`	The card is stored in your customer's Google account and isn't bound to a device, for example on desktop or on non-Android mobile web.
`CRYPTOGRAM_3DS`	The card is bound to an Android device. Issuers can delegate strong customer authentication to Google for later payments on that device. The payment comes with a cryptogram.

Choose a flow

You can process the payment token from Google in two ways:

Flow	Who decrypts the Google Pay token	Who manages the Google Pay keys
Encrypted payload	Ginger Payments	Ginger Payments
Decrypted payload	You	You

Encrypted payload

You pass the encrypted payment token from Google to Ginger Payments. Ginger Payments decrypts it and stores the card in the vault.

With the activation of Google Pay, you receive the tokenization parameters to configure in your Google Pay payment request and the URL of the Google Pay token service. The examples below use it as $GOOGLE_PAY_TOKEN_URL.

Step	Endpoint	What it does
1	`POST /v1/orders/`	Creates the order and the Google Pay transaction.
2	`POST {google_pay_token_url}/tokens/`	Decrypts the payment token and returns a `vaultToken`, cryptogram and ECI indicator.
3	`POST /pay/{order_id}/select-payment-method/google-pay/{transaction_id}/`	Executes the payment.

Create the order

Create an order with a google-pay transaction, as in the hosted payment page example. The response contains the IDs and the setup token you need in the next steps:

{
  "id": "6bf8a727-bef2-4420-8d41-af82f6f19f3d",
  "status": "new",
  "transactions": [
    {
      "id": "59f5866a-c216-472e-b803-8a4e83c4578a",
      "payment_method": "google-pay",
      "payment_method_details": {
        "setup_token": "c6d0a22b-df22-41a2-aac1-d647173ff219"
      },
      "status": "new"
    }
  ]
}

The response is shortened. Save the order id, the transaction id and the setup_token.

Store the payment details

Your customer selects a card in Google Pay. Google returns the payment token in paymentData.paymentMethodData.tokenizationData.token. Send it as a string, together with the setup token and transaction ID from step 1:

curl "$GOOGLE_PAY_TOKEN_URL/tokens/" \
  --header "Content-Type: application/json" \
  --data '{
    "googlePayMessage": "{\"signature\":\"MEUCIQDXc...03d\",\"protocolVersion\":\"ECv2\",\"signedMessage\":\"...\"}",
    "setupToken": "c6d0a22b-df22-41a2-aac1-d647173ff219",
    "transactionId": "59f5866a-c216-472e-b803-8a4e83c4578a"
  }'

For a test project connected to the Google Pay test environment, use $GOOGLE_PAY_TOKEN_URL/test/tokens/ instead.

{
  "vaultToken": "d972dc43-6a3d-4dcf-b54e-6e9a0fe325e3",
  "cryptogram": "AgAAAAAABk4DWZ4C28yUQAAAAAA=",
  "eciIndicator": "05"
}

cryptogram and eciIndicator can be empty. An empty cryptogram means the card was returned as PAN_ONLY, and the payment is processed as a regular card payment.

Execute the payment

Send the values from step 2 to the payment URL of the transaction, together with your customer's browser details:

curl https://api.dev.gingerpayments.com/pay/6bf8a727-bef2-4420-8d41-af82f6f19f3d/select-payment-method/google-pay/59f5866a-c216-472e-b803-8a4e83c4578a/ \
  --header "Content-Type: application/json" \
  --data '{
    "vaultToken": "d972dc43-6a3d-4dcf-b54e-6e9a0fe325e3",
    "cryptogram": "AgAAAAAABk4DWZ4C28yUQAAAAAA=",
    "eciIndicator": "05",
    "browser_info_screen_width": 1920,
    "browser_info_screen_height": 1080,
    "browser_info_color_depth": 24,
    "browser_info_user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/121.0.0.0 Safari/537.36",
    "browser_info_time_zone_offset": 0,
    "browser_info_language": "en-US",
    "browser_info_java_enabled": false
  }'

Field	Description
`vaultToken`	The vault token from step 2.
`cryptogram`	The cryptogram from step 2. Can be empty.
`eciIndicator`	The ECI indicator from step 2. Can be empty.
`browser_info_screen_width`	Screen width of your customer's device, in pixels.
`browser_info_screen_height`	Screen height of your customer's device, in pixels.
`browser_info_color_depth`	Color depth of the screen, in bits.
`browser_info_user_agent`	User agent of your customer's browser.
`browser_info_time_zone_offset`	Time zone offset of your customer's browser.
`browser_info_language`	Language of your customer's browser, such as `en-US`.
`browser_info_java_enabled`	Whether Java is enabled in your customer's browser.

{
  "is_successful": true,
  "redirect_url": "https://api.dev.gingerpayments.com/pay/6bf8a727-bef2-4420-8d41-af82f6f19f3d/59f5866a-c216-472e-b803-8a4e83c4578a/completed/",
  "reason": "none"
}

Redirect your customer to the redirect_url. Then wait for the webhook and check the order status before you deliver.

Decrypted payload

You decrypt the payment token from Google yourself, with your own Google Pay keys, and store the card details in the Ginger Payments vault.

You handle card data

The decrypted payload contains the card number. Your systems must be PCI DSS compliant to process it. See Server-to-server.

Step	Endpoint	What it does
1	`POST /v1/orders/`	Creates the order and the Google Pay transaction.
2	Google Pay	Your customer selects a card. You decrypt the payload.
3	`POST https://tokens.dev.gingerpayments.com/v1/cards/`	Stores the card details in the vault and returns a `vault_token`.
4	`POST /pay/{order_id}/select-payment-method/google-pay/{transaction_id}/`	Executes the payment.

Create the order

Create an order with a google-pay transaction, as in the hosted payment page example. Save the order id, the transaction id and the setup_token from payment_method_details.

Get the payment data from Google

Your customer taps the Google Pay button and selects a card. Google returns an encrypted payload. Decrypt it with your Google Pay keys, and take the card number (pan), expirationMonth and expirationYear from it, plus the cryptogram and eciIndicator when present.

Store the card details

Store the card in the vault with the setup_token from step 1. The expiry date uses the format MMYYYY:

curl https://tokens.dev.gingerpayments.com/v1/cards/ \
  --user "$API_KEY:" \
  --header "Content-Type: application/json" \
  --data '{
    "pan": "4871049999999910",
    "expiry": "122028",
    "setup_token": "c6d0a22b-df22-41a2-aac1-d647173ff219"
  }'

{
  "brand": "visa",
  "brands": ["visa"],
  "truncated_pan": "4871********9910",
  "vault_token": "d972dc43-6a3d-4dcf-b54e-6e9a0fe325e3"
}

The setup token can be used once, within 300 seconds after the order was created.

Execute the payment

Send the vault_token from the vault as vaultToken, plus the cryptogram and ECI indicator from the decrypted payload when present, to the payment URL of the transaction. The request and response are the same as in step 3 of the encrypted payload flow.

Customer details

Send the customer object with every Google Pay order. Depending on your acquirer, these fields can be required:

Field	Description
`merchant_customer_id`	Your own customer reference.
`email_address`	Your customer's email address.
`first_name`	1 to 120 characters. Pattern: `^[\w -,\.À-ÖØ-öø-ÿ]+$`
`last_name`	1 to 120 characters. Pattern: `^[\w -,\.À-ÖØ-öø-ÿ]+$`
`address_type`	Always `billing`.
`address`	Billing address, 1 to 120 characters. Pattern: `^[\w -,\.\-À-ÖØ-öø-ÿ]+$`
`postal_code`	1 to 10 characters. Pattern: `^[A-Z0-9]+( [A-Z0-9]*)?$`
`city`	1 to 120 characters. Pattern: `^[\w -,\.\-À-ÖØ-öø-ÿ]+$`
`country`	ISO 3166-1 alpha-2 country code, such as `GB`.
`phone_numbers`	List of phone numbers, including the country code.

Recurring payments

Google Pay supports recurring payments. See Recurring payments with Google Pay.

Hosted payment pageCopy Anchor Link

Server-to-serverCopy Anchor Link

Authentication methodsCopy Anchor Link

Choose a flowCopy Anchor Link

Encrypted payloadCopy Anchor Link

Create the orderCopy Anchor Link

Store the payment detailsCopy Anchor Link

Execute the paymentCopy Anchor Link

Decrypted payloadCopy Anchor Link

Create the orderCopy Anchor Link

Get the payment data from GoogleCopy Anchor Link

Store the card detailsCopy Anchor Link

Execute the paymentCopy Anchor Link

Customer detailsCopy Anchor Link

Recurring paymentsCopy Anchor Link

On this page

Hosted payment page

Server-to-server

Authentication methods

Choose a flow

Encrypted payload

Create the order

Store the payment details

Execute the payment

Decrypted payload

Create the order

Get the payment data from Google

Store the card details

Execute the payment

Customer details

Recurring payments