The Google Pay API introduced new Android client libraries in August 2018. These new libraries
support the construction of an
IsReadyToPayRequest
or
PaymentDataRequest
from a JSON object that is serialized as a string. This guide
explains how to update Android code that uses a Builder
object to the equivalent JSON-formatted
string that's passed to the fromJson()
method of IsReadyToPayRequest
and
PaymentDataRequest
.
Payment methods
In previous versions of the Google Pay API, the Builder
object we used only
supported cards as a form of payment for
IsReadyToPayRequest
or PaymentDataRequest
. In the latest version of the
Google Pay API, the CARD
payment method is only one of multiple
possible payment methods for IsReadyToPayRequest
or PaymentDataRequest
.
Constants are no longer used. The Builder
object that was used in the previous version
referenced integer constants. The new, JSON-formatted string sets
equivalent string values in the allowedAuthMethods
property array of
CardParameters
. In
order to update your code, identify your case, and follow the instructions below:
- If your app supported
PAYMENT_METHOD_CARD
:- Add
"PAN_ONLY"
to theallowedAuthMethods
array.
- Add
- If your app supported
PAYMENT_METHOD_TOKENIZED_CARD
:- Add
"CRYPTOGRAM_3DS"
to theallowedAuthMethods
array.
- Add
Apps were previously assigned a default set of allowed card networks if you didn't specify them. Apps are now required to provide a list of allowed card networks.
Builder
IsReadyToPayRequest.newBuilder() .addAllowedPaymentMethod( WalletConstants.PAYMENT_METHOD_CARD) .addAllowedPaymentMethod( WalletConstants.PAYMENT_METHOD_TOKENIZED_CARD);
PaymentDataRequest.newBuilder() .addAllowedPaymentMethod( WalletConstants.PAYMENT_METHOD_CARD) .addAllowedPaymentMethod( WalletConstants.PAYMENT_METHOD_TOKENIZED_CARD);
fromJson
{ "apiVersion": 2, "apiVersionMinor": 0, "allowedPaymentMethods": [ { "type": "CARD", "parameters": { "allowedAuthMethods": [ "PAN_ONLY", "CRYPTOGRAM_3DS" ], "allowedCardNetworks": [ "AMEX", "DISCOVER", "MASTERCARD", "VISA" ] } } ] }
Card payment data tokenization
The Google Pay API returns encrypted card data that's referenced by your specified gateway
or decrypted on your servers. Information previously provided to a PaymentMethodTokenizationParameters
builder should be defined in the
PaymentMethodTokenizationSpecification
of a CARD
payment method.
Builder
PaymentMethodTokenizationParameters.newBuilder() .setPaymentMethodTokenizationType( WalletConstants.PAYMENT_GATEWAY) .addParameter( "gateway", "example") .addParameter( "gatewayMerchantId", "exampleGatewayMerchantId")
fromJson
{ "allowedPaymentMethods": [{ "type": "CARD", "tokenizationSpecification": { "type": "PAYMENT_GATEWAY", "parameters": { "gateway": "example", "gatewayMerchantId": "exampleGatewayMerchantId" } } }] }
Billing address
You have the option to require a billing address or phone number to associate with a
CARD
payment
method. If you decide to require a billing address or phone number, you must specify the
configuration of the required response in the
BillingAddressParameters
JSON object.
Builder
PaymentDataRequest.newBuilder() .setPhoneNumberRequired(true) .setCardRequirements( CardRequirements.newBuilder() .setBillingAddressRequired(true) .setBillingAddressFormat( WalletConstants.BILLING_ADDRESS_FORMAT_FULL));
fromJson
{ "allowedPaymentMethods": [{ "type": "CARD", "parameters": { "billingAddressRequired": true, "billingAddressParameters": { "format": "FULL", "phoneNumberRequired": true } } }] }
Shipping address
You have the option to require your user to provide a shipping address, they can use a stored
shipping address or enter a new one. The shipping address is a top-level property in the
PaymentDataRequest
JSON object. The shipping address countries you allow were previously added to a
ShippingAddressRequirements
builder, and should now be specified in the
ShippingAddressParameters
JSON object.
Builder
PaymentDataRequest.newBuilder() .setPhoneNumberRequired(true) .setShippingAddressRequired(true) .setShippingAddressRequirements( ShippingAddressRequirements.newBuilder() .addAllowedCountryCode("US") .addAllowedCountryCode("CA"))
fromJson
{ "shippingAddressRequired": true, "shippingAddressParameters": { "allowedCountryCodes": [ "US", "CA" ], "phoneNumberRequired": true } }
PaymentData response
A response is a PaymentDataRequest
object that contains a JSON-formatted response
that's available to the
toJson()
class method. In order to receive this response, create a PaymentDataRequest
object with the
fromJson()
class method and pass it to the
loadPaymentData
method of a PaymentsClient
. A PaymentData
instance is extracted from an
Intent
. A JSON-formatted string can be parsed into JSON name-value pairs by
JSONObject
or other JSON-aware libraries.
Previous Getters
PaymentData paymentData = PaymentData.getFromIntent(data);
Current JSON
PaymentData paymentData = PaymentData.getFromIntent(data); String json = paymentData.toJson(); if (json != null) { JSONObject paymentDataJson = new JSONObject(json); JSONObject paymentMethodData = paymentDataJson.get("paymentMethodData"); }
Summary text for the selected payment method is available in the description
property. See the
CardInfo
JSON object reference
for additional properties that are available when the CARD
type is returned.
Previous Getters
paymentData .getCardInfo() .getCardDescription();
Current JSON
paymentMethodData.get("description");
Information about a selected payment method and its tokenization is placed inside of the
paymentMethodData
property.
Previous Getters
paymentData .getPaymentMethodToken() .getToken();
Current JSON
paymentMethodData .get("tokenizationData") .get("token");
Encrypted message response
Apps that specify a DIRECT
payment method tokenization type and accept
Android device tokens, previously
WalletConstants.PAYMENT_METHOD_TOKENIZED_CARD
,
must update the way they handle the decrypted
encryptedMessage
property
on their servers. Both PAN_ONLY
and CRYPTOGRAM_3DS
types of
authenticated cards appear as a paymentMethod
of CARD
, with additional
information about the authentication method and fields specific to the authentication method
provided in paymentMethodDetails
.
As a result, if your server isn't updated, it can't forward Android device tokens to your
gateway or processor. This is because your server can't distinguish between multiple types of
card authentication in the response. Cards are a paymentMethod
of CARD
with additional information about the selected card's authentication method in
paymentMethodDetails.authMethod
. The tokens are authenticated with a 3-D Secure
cryptogram and optional electronic commerce indicator (ECI).
ECI
{ "paymentMethod": "TOKENIZED_CARD", "paymentMethodDetails": { "authMethod": "3DS", "dpan": "1111222233334444", "expirationMonth": 10, "expirationYear": 2020, "3dsCryptogram": "AAAAAA...", "3dsEciIndicator": "eci indicator" } }
3-D Secure cryptogram
{ "paymentMethod": "CARD", "paymentMethodDetails": { "authMethod": "CRYPTOGRAM_3DS", "pan": "1111222233334444", "expirationMonth": 10, "expirationYear": 2020, "cryptogram": "AAAAAA...", "eciIndicator": "eci indicator" } }