Google Pay™

Create

Decrypts a Google Pay™ payment method token and creates either a Google Pay™ resource or a Basis Theory's Token Intent based on the provided encrypted token. This endpoint only supports the ECv2 token versions. It supports both auth methods, PAN_ONLY and CRYPTOGRAM_3DS.

Basis Theory supports the PAN_ONLY and CRYPTOGRAM_3DS authorization methods. The table below shows the resulting resources based on the Google Pay™ payment method token's authMethod attribute.

Auth Method	Resource Type
PAN_ONLY	`token_intent`
CRYPTOGRAM_3DS	`google_pay`

You can specify the merchant registration to use for a request, ensuring the correct associated keys are selected to decrypt and tokenize the incoming payment data.

POST

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

Permissions

google-pay:create

Request

cURL
Node
C#
Python

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

await client.googlePay.create();

await client.GooglePay.CreateAsync(new GooglePayCreateRequest());

client.google_pay.create()

Request Parameters

Attribute	Required	Description
`expires_at`	false	An optional expiration date for the token. If blank, no expiration date is set for the token.
`google_payment_data`	true	The Google Pay™ resource.
`merchant_registration_id`	false	The unique identifier of the merchant registration created through the Basis Theory Merchant API.

Response

Returns a Google Pay™ resource for tokenized cards that consists of device PAN and cryptograms. The return will include the Card BIN enrichments. Returns an error if there were validation errors, if the Google Pay™ payment method token failed to decrypt or the token failed to create.

{
  "google_pay": {
    "id": "b7248b11-acfb-4695-93a9-9609f90ec038",
    "tenant_id": "...",
    "status": "active",
    "expires_at": "2030-12-25T00:00:00+00:00",
    "created_by": "50c63e9b-91e5-4a6a-9f9e-81088d106f2c",
    "created_at": "2025-08-06T11:02:53.9261435+00:00",
    "fingerprint": "7bAjvyqJqfPc4jRjniEk87vNrjR74Xax1HnMREWsTiMz",
    "card": {
      "bin": "411111",
      "last4": "1111",
      "expiration_month": 12,
      "expiration_year": 2027,
      "brand": "visa",
      "funding": "debit",
      "authentication": "sca_required"
    },
    "details": {
      "tsp": "Google",
      "auth_method": "PAN_ONLY",
      "message_id": "AH2EjtdkuuxxO3nA7RuWAo0fU4u5BPoySvd9ajlSSrTWy3yTCu2IRbRwp8K3sFjSUS-ELa7UzetwY6UFsNLISYiKY6arNIOfYxutYYH3LJdIH0UcmoRDzmM",
      "eci_indicator": "",
      "assurance_details": {
        "account_verified": true,
        "card_holder_authenticated": false
      }
    }
  }
}

For encrypted cards with an authorization method of "PAN_ONLY", a Token Intent will be created. Refer to Token Intents documentation for more information.

To compute the fingerprint for Google Pay™ resources, the system utilizes the card number contained within the encrypted payment token.

Retrieve

Retrieves an already tokenized Google Pay™ resource. For encrypted cards with an authorization method of "PAN_ONLY" use Token Intents documentation.

GET

https://api.basistheory.com/google-pay/{:id}

Permissions

google-pay:read google-pay:reveal

Request

cURL
Node
C#
Python

curl --request GET \
--url https://api.basistheory.com/google-pay/3c367ed4-678d-4b98-9cec-d7eaa0f0c26e \
--header 'BT-API-KEY: <API_KEY>'

await client.googlePay.get("id");

await client.GooglePay.GetAsync("id");

client.google_pay.get(
id="id",
)

Response

Returns a Google Pay™ resource. If the application has google-pay:reveal, then the data element will contain the unencrypted card information. If the application has google-pay:read, then the data element will contain masked card information.

{
  "id": "99978b31-78e8-4751-926c-83775bfb126b",
  "tenant_id": "eb210708-f709-495f-b4de-b9e3877bd4c3",
  "status": "active",
  "expires_at": "2025-12-25T00:00:00+00:00",
  "created_by": "c1847894-2f72-4999-a47d-bf9a12d19ca9",
  "created_at": "2025-08-04T16:19:50.9013495+00:00",
  "fingerprint": "7bAjvyqJqfPc4jRjniEk87vNrjR74Xax1HnMREWsTiMz",
  "card": {
    "bin": "42424242",
    "last4": "4242",
    "expiration_month": 6,
    "expiration_year": 2025,
    "brand": "mastercard",
    "funding": "credit",
    "authentication": "sca_required",
    "issuer": {
      "country": "PL",
      "name": "3DS Test Cards (TEST)"
    },
    "issuer_country": {
      "alpha2": "PL",
      "name": "Bermuda",
      "numeric": "369"
    },
    "segment": "Commercial"
  },
  "data": {
    "number": "4242424242424242",
    "expiration_month": 6,
    "expiration_year": 2025
  },
  "authentication": {
    "threeds_cryptogram": "AAAAAA=",
    "eci_indicator": "7"
  }
}

Google Pay™ resources created from a Google Pay™ payment method token will contain a details attribute.

Attribute	Type	Description
`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.

Delete

Deletes an already tokenized Google Pay™ resource. For encrypted cards with an authorization method of "PAN_ONLY" use Token Intents documentation.

DELETE

https://api.basistheory.com/google-pay/{:id}

Permissions

google-pay:delete

Request

cURL
Node
C#
Python

curl --request DELETE \
--url https://api.basistheory.com/google-pay/3c367ed4-678d-4b98-9cec-d7eaa0f0c26e \
--header 'BT-API-KEY: <API_KEY>'

await client.googlePay.delete("id");

await client.GooglePay.DeleteAsync("id");

client.google_pay.delete(
id="id",
)

Response

Returns a Google Pay™ resource with summarized information.

{
  "id": "99978b31-78e8-4751-926c-83775bfb126b",
  "tenant_id": "eb210708-f709-495f-b4de-b9e3877bd4c3",
  "status": "active",
  "expires_at": "2025-12-25T00:00:00+00:00"
}

Google Pay™ Merchant Registration

Basis Theory supports Google Pay™ using merchant-owned encryption keys, allowing you to maintain full control over your Google Pay™ configuration while securely tokenizing payment data through Basis Theory.

With this approach, encryption keys are generated, rotated, and managed directly by the merchant through the Google Pay™ API. Basis Theory securely stores your encrypted key material and uses it at runtime to decrypt and tokenize Google Pay™ payment data.

Prerequisites

Before integrating with Basis Theory’s Google Pay™ APIs, ensure that:

You have a Google Pay™ merchant account
You have registered one or more encryption keys with the Google Pay™ API
Your integration supports key rotation (multiple active keys may be registered simultaneously)

Google Pay™ recommends maintaining multiple active keys to enable seamless key rotation without service interruption.

Merchant Registration

Your first step is to register your merchant using the Basis Theory Merchant API. This creates a merchant record that securely associates your Google Pay™ configuration and encrypted encryption keys with your tenant.

Once registered, the merchant can be referenced in Basis Theory’s Google Pay™ tokenization endpoints to ensure the correct keys are used when decrypting and tokenizing payment data.

Create Merchant Registration

Registers a resource representing a Google Pay™ merchant.

POST

https://api.basistheory.com/google-pay/merchant-registration

Permissions

google-pay:manage

Request

cURL
Node
C#
Python

curl --request POST \
--url https://api.basistheory.com/google-pay/merchant-registration \
--header 'BT-API-KEY: <API_KEY>' \
--header 'Content-Type: application/json' \
--data '{
  "merchant_identifier": "my_gateway_merchant_id"
}'

await client.googlePay.merchant.create();

await client.GooglePay.Merchant.CreateAsync(new GooglePayMerchantRegisterRequest());

client.google_pay.merchant.create()

Request Parameters

Attribute	Required	Description
`merchant_identifier`	true	The merchant identifier — also known as the processor name — as registered with the Google Pay™ API.

Response

Returns a Google Pay™ Merchant registration with the registered merchant_identifier. Returns an error if there were validation errors, or the resource failed to create.

{
  "id": "b7248b11-acfb-3949-93a9-9609f90ec038",
  "tenant_id": "893e4980-8732-4166-934c-6217476e3391",
  "merchant_identifier": "my_gateway_merchant_id",
  "created_by": "50c63e9b-91e5-4a6a-9f9e-81088d106f2c",
  "created_at": "2025-08-06T11:02:53.9261435+00:00"
}

Retrieve Merchant Registration

Retrieves a resource representing a Google Pay™ merchant registration.

GET

https://api.basistheory.com/google-pay/merchant-registration/{:id}

Permissions

google-pay:manage

Request

cURL
Node
C#
Python

curl --request GET \
--url https://api.basistheory.com/google-pay/merchant-registration/3c367ed4-678d-4b98-9cec-d7eaa0f0c26e \
--header 'BT-API-KEY: <API_KEY>'

await client.googlePay.merchant.get("id");

await client.GooglePay.Merchant.GetAsync("id");

client.google_pay.merchant.get(
id="id",
)

Response

Returns a Google Pay™ Merchant registration.

{
  "id": "b7248b11-acfb-3949-93a9-9609f90ec038",
  "tenant_id": "893e4980-8732-4166-934c-6217476e3391",
  "merchant_identifier": "my_gateway_merchant_id",
  "created_by": "50c63e9b-91e5-4a6a-9f9e-81088d106f2c",
  "created_at": "2025-08-06T11:02:53.9261435+00:00"
}

Delete Merchant Registration

Deletes a resource representing a Google Pay™ merchant registration.

DELETE

https://api.basistheory.com/google-pay/merchant-registration/{:id}

Permissions

google-pay:manage

Request

cURL
Node
C#
Python

curl --request DELETE \
--url https://api.basistheory.com/google-pay/merchant-registration/3c367ed4-678d-4b98-9cec-d7eaa0f0c26e \
--header 'BT-API-KEY: <API_KEY>'

await client.googlePay.merchant.delete("id");

await client.GooglePay.Merchant.DeleteAsync("id");

client.google_pay.merchant.delete(
id="id",
)

Response

Returns a Google Pay™ Merchant registration with summarized information.

{
  "id": "b7248b11-acfb-3949-93a9-9609f90ec038",
  "tenant_id": "893e4980-8732-4166-934c-6217476e3391",
  "merchant_identifier": "my_gateway_merchant_id",
  "created_by": "50c63e9b-91e5-4a6a-9f9e-81088d106f2c",
  "created_at": "2025-08-06T11:02:53.9261435+00:00"
}

Google Pay™ Merchant Certificates

Once a merchant is registered, merchant-owned encryption certificates can be associated with it and will be used to decrypt and tokenize Google Pay™ payment data during tokenization requests.

Create Merchant Certificates

Registers a new merchant encryption certificate that will be used to decrypt and tokenize Google Pay™ payment data.

POST

https://api.basistheory.com/google-pay/merchant-registration/{:id}/certificates

Permissions

google-pay:manage

Request

cURL
Node
C#
Python

curl --request POST \
  --url https://api.basistheory.com/google-pay/merchant-registration/3c367ed4-678d-4b98-9cec-d7eaa0f0c26e/certificates \
  --header 'BT-API-KEY: <API_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
    "merchant_certificate_data": "MIIJVQIBAzCCCR8GCSqGSIb3DQEHAaCCCRAAggkM...",
    "merchant_certificate_password": "super_secret_password_123"
  }'

await client.googlePay.merchant.certificates.create("merchantId", request: GooglePayMerchantCertificatesRegisterRequest = {})

await client.GooglePay.Merchant.Certificates.CreateAsync("merchantId",
new GooglePayMerchantCertificatesRegisterRequest()
);

client.client.google_pay.merchant.certificates.create(
merchant_id="merchantId",
merchant_certificate_data="",
merchant_certificate_password=""
)

Request Parameters

Attribute	Required	Description
`merchant_certificate_data`	true	A base64-encoded, encrypted P12 file containing both the certificate and the private key used to encrypt payment data for the merchant.
`merchant_certificate_password`	true	The password used to decrypt the merchant_certificate_data. AES-256-CBC with PBKDF2 is used to decrypt the certificate data.

Response

Returns a summarized resource representing a registered Google Pay™ merchant encryption certificate. Returns an error if there were validation errors, if the certificate failed to decrypt or the certificate failed to create.

{
  "id": "b7248b11-acfb-3949-93a9-9609f90ec038",
  "tenant_id": "893e4980-8732-4166-934c-6217476e3391",
  "merchant_identifier": "my_gateway_merchant_id",
  "merchant_certificate_expiration_date": "2029-08-06T11:02:53.9261435+00:00",
  "merchant_certificate_fingerprint": "a1:b2:c3:d4:e5:f6:78:90:ab:cd:ef:12:34:56:78:90:12:34:56:78",
  "created_by": "50c63e9b-91e5-4a6a-9f9e-81088d106f2c",
  "created_at": "2025-08-06T11:02:53.9261435+00:00"
}

There is a limitation of two active certificates per merchant at any given time.

Retrieve Merchant Certificates

Retrieves a resource representing a registered Google Pay™ merchant encryption certificate.

GET

https://api.basistheory.com/google-pay/merchant-registration/{:merchantId}/certificates/{:id}

Permissions

google-pay:manage

Request

cURL
Node
C#
Python

curl --request GET \
--url https://api.basistheory.com/google-pay/merchant-registration/3c367ed4-678d-4b98-9cec-d7eaa0f0c26e/certificates/343067ed4-678d-4b98-9cec-d7eaa0f0c26e \
--header 'BT-API-KEY: <API_KEY>'

await client.googlePay.merchant.certificates.get("merchantId", "id")

await client.GooglePay.Merchant.Certificates.GetAsync("merchantId", "id");

client.google_pay.merchant.certificates.get(
merchant_id="merchantId",
id="id",
)

Response

Returns a Google Pay™ merchant encryption certificate.

{
  "id": "b7248b11-acfb-3949-93a9-9609f90ec038",
  "tenant_id": "893e4980-8732-4166-934c-6217476e3391",
  "merchant_identifier": "my_gateway_merchant_id",
  "merchant_certificate_expiration_date": "2029-08-06T11:02:53.9261435+00:00",
  "merchant_certificate_fingerprint": "a1:b2:c3:d4:e5:f6:78:90:ab:cd:ef:12:34:56:78:90:12:34:56:78",
  "created_by": "50c63e9b-91e5-4a6a-9f9e-81088d106f2c",
  "created_at": "2025-08-06T11:02:53.9261435+00:00"
}

Delete Merchant Certificates

Deletes an existing Google Pay™ merchant encryption certificate and its associated configuration.

DELETE

https://api.basistheory.com/google-pay/merchant-registration/{:merchantId}/certificates/{:id}

Permissions

google-pay:manage

Request

cURL
Node
C#
Python

curl --request DELETE \
--url https://api.basistheory.com/google-pay/merchant-registration/3c367ed4-678d-4b98-9cec-d7eaa0f0c26e/certificates/343067ed4-678d-4b98-9cec-d7eaa0f0c26e \
--header 'BT-API-KEY: <API_KEY>'

await client.googlePay.merchant.certificates.delete("merchantId", "id")

await client.GooglePay.Merchant.Certificates.DeleteAsync("merchantId", "id");

client.google_pay.merchant.certificates.delete(
merchant_id="merchantId",
id="id",
)

Response

Returns a Google Pay™ merchant encryption certificate with summarized information.

{
  "id": "b7248b11-acfb-3949-93a9-9609f90ec038",
  "tenant_id": "893e4980-8732-4166-934c-6217476e3391",
  "merchant_identifier": "my_gateway_merchant_id",
  "merchant_certificate_expiration_date": "2029-08-06T11:02:53.9261435+00:00",
  "merchant_certificate_fingerprint": "a1:b2:c3:d4:e5:f6:78:90:ab:cd:ef:12:34:56:78:90:12:34:56:78",
  "created_by": "50c63e9b-91e5-4a6a-9f9e-81088d106f2c",
  "created_at": "2025-08-06T11:02:53.9261435+00:00"
}

Create​

Permissions​

Request​

Request Parameters​

Response​

Retrieve​

Permissions​

Request​

Response​

Delete​

Permissions​

Request​

Response​

Google Pay™ Merchant Registration​

Prerequisites​

Merchant Registration​

Create Merchant Registration​

Permissions​

Request​

Request Parameters​

Response​

Retrieve Merchant Registration​

Permissions​

Request​

Response​

Delete Merchant Registration​

Permissions​

Request​

Response​

Google Pay™ Merchant Certificates​

Create Merchant Certificates​

Permissions​

Request​

Request Parameters​

Response​

Retrieve Merchant Certificates​

Permissions​

Request​

Response​

Delete Merchant Certificates​

Permissions​

Request​

Response​

Create

Permissions

Request

Request Parameters

Response

Retrieve

Permissions

Request

Response

Delete

Permissions

Request

Response

Google Pay™ Merchant Registration

Prerequisites

Merchant Registration

Create Merchant Registration

Permissions

Request

Request Parameters

Response

Retrieve Merchant Registration

Permissions

Request

Response

Delete Merchant Registration

Permissions

Request

Response

Google Pay™ Merchant Certificates

Create Merchant Certificates

Permissions

Request

Request Parameters

Response

Retrieve Merchant Certificates

Permissions

Request

Response

Delete Merchant Certificates

Permissions

Request

Response