Google Pay™

DEPRECATED

An endpoint to decrypt and tokenize a Google Payment token. This endpoint only supports the ECv2 token versions. It supports both auth methods, PAN_ONLY and CRYPTOGRAM_3DS.

When requesting a payment token, use basistheory as the gateway and your tenant ID for gatewayMerchantId. There is no requirement to include addresses. Basis Theory does not perform address verification.

const tokenizationSpecification = {
  type: 'PAYMENT_GATEWAY',
  parameters: {
    'gateway': 'basistheory',
    'gatewayMerchantId': '<TENANT ID>'
  }
};

Tokenize

This process utilizes Basis Theory's Token Intents. This endpoint will decrypt a provided Google Payment token and tokenize to a Basis Theory Token Intent.

To use the API, pass the encrypted Google Payment token received from the Google API in the google_payment_method_token object in the Basis Theory request object.

Basis Theory supports the PAN_ONLY and CRYPTOGRAM_3DS authorization methods. The table below shows the resulting Token Intent type based on the Google Payment Token's authMethod attribute.

Auth Method	Token Type
PAN_ONLY	card
CRYPTOGRAM_3DS	network_token

POST

https://api.basistheory.com/connections/google-pay/tokenize

Permissions

connections:google-pay:invoke

Request

cURL

curl --request POST \
  --url https://api.basistheory.com/connections/google-pay/tokenize \
  --header 'BT-API-KEY: <API_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
  "google_payment_method_token": {
    "protocolVersion": "ECv2",
    "signature": "...",
    "intermediateSigningKey": {
      "signedKey": "...",
      "signatures": [
        "..."
      ]
    },
    "signedMessage": "..."
  }'

Node

await client.googlepay.tokenize({
    googlePaymentMethodToken: {...}
});

C#

await client.Googlepay.TokenizeAsync(new GooglePayTokenizeRequest
{
  GooglePaymentMethodToken = new GooglePaymentMethodToken
  {
    ...
  }
});

Python

client.googlepay.tokenize(
  google_payment_method_token={
    ...
  }
)

Java

BasisTheoryApiClient client = new BasisTheoryApiClient(ClientOptions.builder().build());
GooglePayTokenizeRequest request = GooglePayTokenizeRequest.builder()
    .googlePaymentMethodToken(...)
    .build();
TokenIntent tokenIntent = client.googlepay().tokenize(request);

Go

tokenizeRequest := &basistheory.GooglePayTokenizeRequest{
    GooglePaymentMethodToken: &basistheory.GooglePaymentMethodToken{
        ProtocolVersion: "ECv2",
        Signature:      "...",
        IntermediateSigningKey: &basistheory.IntermediateSigningKey{
            SignedKey:  "...",
            Signatures: []string{"..."},
        },
        SignedMessage: "...",
    },
}

tokenIntent, err := client.Googlepay.Tokenize(ctx, tokenizeRequest)

Request Parameters

Attribute	Required	Type	Description
google_payment_method_token	true	Google Payment Token	The Google Payment method token.

Response

Returns a Token Intent if successful. Returns an error if there were validation errors, if the Google payment token failed to decrypt create, or the Token Intent failed to create.

{
  "token_intent": {
    "id": "d4cf4b73-d6c7-4270-a3dc-5854d889708b",
    "type": "card",
    "tenant_id": "064bbc70-204b-4ef1-a757-ec0878be5945",
    "fingerprint": "3SUw6NP2JgpQAJW4tvVczznnzxnTKrBM9TVXGpPPB7Vf",
    "created_by": "f0f504e5-79c2-40a6-aad3-dbee7a692828",
    "created_at": "2025-01-24T15:37:52.8143798+00:00",
    "expires_at": "2025-01-25T15:37:52.8143802+00:00",
    "card": {
      "bin": "411111",
      "last4": "1111",
      "expiration_month": 12,
      "expiration_year": 2027,
      "brand": "visa",
      "funding": "debit",
      "authentication": "sca_required"
    },
    "authentication": {
      "threeds_cryptogram": "AAAAAAA....",
      "eci_indicator": "02"
    },
    "_extras": {
      "tsp_details": {
        "tsp": "Google",
        "auth_method": "PAN_ONLY",
        "message_id": "AH2EjtdkuuxxO3nA7RuWAo0fU4u5BPoySvd9ajlSSrTWy3yTCu2IRbRwp8K3sFjSUS-ELa7UzetwY6UFsNLISYiKY6arNIOfYxutYYH3LJdIH0UcmoRDzmM",
        "eci_indicator": "",
        "assurance_details": {
          "account_verified": true,
          "card_holder_authenticated": false
        }
      }
    }
  }
}

Token Intents and the resulting tokens created from a Google payment token will contain a tsp_details object in the _extras attribute.

The attributes in the _extras object are NOT addressable in proxies or reactors.

Attribute	Type	Description
_extras	Object	Parent object containing additional details.
tsp_details	Object	Details related to the transaction service provider (TSP).
tsp	String	The name of the transaction service provider.
auth_method	String	The authentication method used.
message_id	String	Unique identifier for the message.
eci_indicator	String	Electronic Commerce Indicator (may be empty).
assurance_details	Object	Information about the assurance of the transaction.
account_verified	Boolean	Indicates if the account was verified.
card_holder_authenticated	Boolean	Indicates if the cardholder was authenticated.

Testing

Testing with a Google Pay token

This endpoint can be used with both TEST and PRODUCTION Google Pay payment data. To use Google Pay TEST payment data, set the TEST environment when generating the Google Pay payment data and use a Basis Theory Application under a TEST Tenant for making your /connections/google-pay/tokenize request. PROD Tenants will only work with PRODUCTION Google Pay payment data.

Testing without a Google Pay token

Basis Theory provides a mechanism to create fake Token Intents using this endpoint. Changing the protocolVersion to BasisTheory will instead process a fake Google payment token in a different manner.

To create a card Token Intent, set the signature to card. The signedMessage should contain number, expiration_month, and expiration_year.

Fake card token

{
  "google_payment_method_token": {
    "protocolVersion": "BasisTheory",
    "signature": "card",
    "intermediateSigningKey": {
      "signedKey": "fake",
      "signatures": [
        "fake"
      ]
    },
    "signedMessage": "{\"number\": 4242424242424242, \"expiration_month\": 4, \"expiration_year\": 2025 }"
  }
}

To create a network_token, set the signature to network_token. In addition to the attributes defined for the fake card token, include cryptogram and eci_indicator. The value of these attributes will be persisted in the authentication object of the Token Intent.

Fake network_token

{
  "google_payment_method_token": {
    "protocolVersion": "BasisTheory",
    "signature": "network_token",
    "intermediateSigningKey": {
      "signedKey": "fake",
      "signatures": [
        "fake"
      ]
    },
    "signedMessage": "{\"number\": 4242424242424242, \"expiration_month\": 12, \"expiration_year\": 2025, \"cryptogram\": \"AAAAA....\", \"eci_indicator\": \"01\"}"
  }
}

Migration Guide

This guide outlines the changes required to migrate from the deprecated Google Pay integration using Token Intents to the new Google Pay Token integration.

Key Changes

1. Endpoint Changes

• Old endpoint under /connections/google-pay/tokenize is being deprecated
• New endpoints are under /google-pay/*

2. Permission Changes

• Old: connections:google-pay:invoke
• New: google-pay:create

3. Response Type Changes

• Old: Returns Token Intent objects
• New: Returns Google Pay Token objects directly or Token Intent objects depending on the authorization method

API Changes

Tokenization

- // Old Tokenization
POST /connections/google-pay/tokenize
{
  "google_payment_method_token": {
    "intermediateSigningKey": { ... }
    "protocolVersion": "...",
    "signature": "...",
    "signedMessage": "...",
  }
}

Response: { "token_intent": { ... } }

+ // New Tokenization
POST /google-pay
  {
    "google_payment_data": {
      "intermediateSigningKey": { ... }
      "protocolVersion": "...",
      "signature": "...",
      "signedMessage": "...",
    }
  }

Response: { "google_pay": { ... } } // For CRYPTOGRAM_3DS authorization method.

Response: { "token_intent": { ... } } // For PAN_ONLY authorization method.

Proxy Expression Changes

- // Old Proxy Expression
"token": "{{ token_intent: <TOKEN_INTENT_ID> | json: \"$.data.number\" }}"

+ // New Proxy Expression
"token": "{{ google_pay: <TOKEN_ID> | json: \"$.data.number\" }}"

Application Changes

1. Public Application Permissions

- permissions: ["connections:google-pay:invoke"]
+ permissions: ["google-pay:create"]

2. Private Application Permissions

- permissions: ["token:use"]
+ permissions: ["proxy:invoke"]

Benefits of Migration

1. Simplified Token Management: Direct Google Pay tokens instead of Token Intents
2. Better Permission Control: More granular permissions for Google Pay operations
3. Future Compatibility: Access to new features and improvements

Testing the Migration

1. Update your application permissions to include the new permissions
2. Update API endpoint references in your code
3. Modify proxy expressions to use: a. The new google_pay: syntax for Google Pay Tokens (CRYPTOGRAM_3DS authorization method) a. The existing token_intent: syntax for Google Pay Tokens (PAN_ONLY authorization method)
4. Test the complete payment flow in your staging environment
5. Verify token creation and payment processing with your payment service provider

Timeline

The deprecated /connections/google-pay/tokenize endpoint will continue to function for a transition period. However, we recommend migrating to the new endpoints as soon as possible to ensure continued functionality and access to new features.

Additional Resources

For additional information on using Google Pay™, view the documentation provided by Google.

• Google Pay Android developer documentation
• Google Pay Android integration checklist
• Google Pay Android brand guidelines
• Google Pay Web developer documentation
• Google Pay Web integration checklist
• Google Pay Web Brand Guidelines