Google Pay payment handler configuration

This reference is based on the config object schema for the Google Pay payment handler for Universal Commerce Protocol (UCP).

{
  "api_version": 2,
  "api_version_minor": 0,
  "environment": "TEST" | "PRODUCTION",
  "merchant_info": {
    "merchant_id": string,
    "merchant_name": string,
    "merchant_origin": string,
    "auth_jwt": string
  },
  "allowed_payment_methods": [
    {
      "type": "CARD",
      "parameters": {
        "allowed_auth_methods": [
          "PAN_ONLY"
        ],
        "allowed_card_networks": [
          "AMEX" | "DISCOVER" | "ELECTRON" | "ELO" | "ELO_DEBIT" | "INTERAC" | "JCB" | "MAESTRO" | "MASTERCARD" | "VISA"
        ],
        "allow_prepaid_cards": boolean,
        "allow_credit_cards": boolean,
        "assurance_details_required": boolean,
        "billing_address_required": boolean,
        "billing_address_parameters": {
          "format": "MIN" | "FULL" | "FULL-ISO3166",
          "phone_number_required": boolean
        }
      },
      "tokenization_specification": {
        "type": "PAYMENT_GATEWAY" | "DIRECT",
        "parameters": {
          ...
        }
      }
    }
  ]
}

Properties

Property Type Necessity Description
api_version integer Required The major Google Pay API version. Only 2 is supported.
api_version_minor integer Required The minor Google Pay API version. Only 0 is supported.
environment string Required The Google Pay environment to use.
  • TEST: Testing-only payment credentials.
  • PRODUCTION: Real, authorizable payment credentials.
merchant_info object Required Identity details for the merchant.
merchant_info.merchant_id string Required Your Google Pay merchant ID from the Google Pay & Wallet Console. This is required for the PRODUCTION environment. It is optional and ignored in the TEST environment.
merchant_info.merchant_name string Optional The merchant's user-facing business name.
merchant_info.merchant_origin string Optional The fully qualified web domain where the checkout occurs (format: hostname).
merchant_info.auth_jwt string Optional Authorization JWT for certain integration contexts.
allowed_payment_methods object[ ] Required The payment methods allowed for this transaction.
allowed_payment_methods[].type string Required The type of supported payment method. Only CARD is supported.
allowed_payment_methods[].parameters object Required Parameters required to configure the CARD payment method.
allowed_payment_methods[].parameters.allowed_auth_methods string[ ] Required Fields supported to authenticate a card transaction.
  • PAN_ONLY: Returns the primary account number (PAN) and expiration date for a card on file in Google Wallet.
allowed_payment_methods[].parameters.allowed_card_networks string[ ] Required The card networks supported by the merchant. Supported values: AMEX, DISCOVER, ELECTRON, ELO, ELO_DEBIT, INTERAC, JCB, MAESTRO, MASTERCARD, VISA.
allowed_payment_methods[].parameters.allow_prepaid_cards boolean Optional Set to false if you don't support prepaid cards. Default is true.
allowed_payment_methods[].parameters.allow_credit_cards boolean Optional Set to false if you don't support credit cards. Default is true.
allowed_payment_methods[].parameters.assurance_details_required boolean Optional Set to true to request card assurance details.
allowed_payment_methods[].parameters.billing_address_required boolean Optional Set to true if you require a billing address to complete the transaction.
allowed_payment_methods[].parameters.billing_address_parameters object Optional Parameters that configure the returned billing address.
allowed_payment_methods[].parameters.billing_address_parameters.format string Optional Billing address format required to complete the transaction.
  • MIN: Name, country code, and ZIP/postal code (default).
  • FULL: Name, street address, locality, region, country code, and ZIP/postal code.
  • FULL-ISO3166: Name, street address, locality, region, country code, postal code, and iso3166AdministrativeArea.
allowed_payment_methods[].parameters.billing_address_parameters.phone_number_required boolean Optional Set to true if you require a phone number to complete the transaction.
allowed_payment_methods[].tokenization_specification object Required Configuration that defines how payment credentials are returned to you.
allowed_payment_methods[].tokenization_specification.type string Required The tokenization type.
  • PAYMENT_GATEWAY: Used if you process payments through a [supported gateway](/pay/api#participating-processors). Returns an encrypted payload to be passed to your PSP.
  • DIRECT: Used if you decrypt credentials yourself (requires PCI DSS Level 1 compliance).
allowed_payment_methods[].tokenization_specification.parameters object Required Parameters specific to the selected tokenization type.

For PAYMENT_GATEWAY, required parameters are: For DIRECT, required parameters are:
  • protocolVersion: The version of the encryption and signature protocol expected in the Google Pay credential. Only ECv2 is supported. See Payment data cryptography for more information.
  • publicKey: Base64-encoded elliptic curve public key. See the Encryption public key format section for more information.