Google Opaque Payment Card specification

Return to API documentation

Revision history

GoogleOpaquePaymentCard

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.