GoogleOpaquePaymentCard

  • GoogleOpaquePaymentCard is an encrypted and signed representation of payment card details for client-side push provisioning.

  • The card details are encrypted using PGP and may be web-safe base64 encoded.

  • The structure includes protocol header, validation context (e.g., server session ID), and payment card information (account number, expiry).

  • The JSON representation of the card details before encryption contains fields for version, server session ID, account number, expiry month, and expiry year.

  • Google uses the provided validation context to ensure the push provisioning is legitimate and intended for the correct destination.

Opaque (i.e., encrypted) payment card sent via client-side push provisioning. It is deliberately named to be similar to the Opaque Payment Card that is already passed through client-side push provisioning to Token Service Providers for the purpose of tokenization.

Here's an example of a clear text JSON request:


{
  "protocolHeader": {
    "version": 1
  },
  "validationContext": {
    "serverSessionId": "GoogleSession123"
  },
  "paymentCard": {
    "accountNumber": "4321123412341234",
    "expiryMonth": "12",
    "expiryYear": "29"
  }
}

The underlying JSON representation of the

GoogleOpaquePaymentCard

is encrypted and signed in accordance with the OpenPGP specification defined in RFC 4880, and then a non-URL-safe Base64 encoding is applied to the encrypted bytes, in accordance with RFC 4648, section 4, with the encoded output being represented as a byte array.

Below is sample Java server code for generating a Google OPC, starting from a

String

that contains the underlying JSON representation. Here, the java.util.Base64 class is used to accomplish the Base64 encoding.


  String googleOpcJson =
      "{"
          + "  \"protocolHeader\": {"
          + "    \"version\": 1"
          + "  },"
          + "  \"validationContext\": {"
          + "    \"serverSessionId\": \"GoogleSession123\""
          + "  },"
          + "  \"paymentCard\": {"
          + "    \"accountNumber\": \"4321123412341234\","
          + "    \"expiryMonth\": \"12\","
          + "    \"expiryYear\": \"29\""
          + "  }"
          + "}";
  byte[] googleOpcSignedAndEncryptedBytes =
      openPgpSignAndEncrypt(
          googleOpcJson, issuerPrivateSigningKey,
          googlePublicEncryptionKey);
  // This Base64 encoded byte array is the final representation of the
  // Google OPC that should be
  // returned to the Android or Web client.
  byte[] googleOpcBase64Bytes =
      Base64.getEncoder()
            .encode(googleOpcSignedAndEncryptedBytes);
JSON representation 
{
  "protocolHeader": {
    object (ProtocolHeader)
  },
  "validationContext": {
    object (ValidationContext)
  },
  "paymentCard": {
    object (PaymentCard)
  }
}
Fields
protocolHeader

object (ProtocolHeader)

REQUIRED: A header for this message.
validationContext

object (ValidationContext)

REQUIRED: Context for the push that can be verified.
paymentCard

object (PaymentCard)

REQUIRED: Payment card details.

ProtocolHeader

Header object that includes protocol layer fields.

JSON representation 
{
  "version": string
}
Fields
version

string (Int64Value format)

REQUIRED: The version of the JSON API spec used to construct this Google Opaque Payment Card object. The current version will be provided by Google and will change at Google's discretion, but generally only for major (i.e., breaking) changes.

ValidationContext

Fields that allow Google to validate the push is valid in the given context, for example the expected destination. This information will be compared to other unsigned information for consistency.

JSON representation 
{

  // Union field intended_destination can be only one of the following:
  "serverSessionId": string
  // End of list of possible types for union field intended_destination.
}
Fields
Union field intended_destination. REQUIRED: The intended "destination" of the push, for validation purposes. Only one destination should be supplied. intended_destination can be only one of the following:
serverSessionId

string

A push provisioning session ID in the form of a UUID generated by a Google server. The destination user is implied by the session.

PaymentCard

Description of a payment card account (i.e., credit card, debit card, charge card).

JSON representation 
{
  "accountNumber": string,
  "expiryMonth": string,
  "expiryYear": string
}
Fields
accountNumber

string

REQUIRED: The account number itself (i.e., the FPAN).
expiryMonth

string

REQUIRED: Expiration month, formatted MM.
expiryYear

string

REQUIRED: Expiration year, formatted YY.