Method: pushProvisioningNotification

Provides Google with information necessary to complete an ongoing push provisioning request.

Responses to this query may be empty if this method does not return an HTTP 200. They are empty in situations where an ErrorResponse with a clear description could be used to help an attacker understand the payment integrator account identifier of other integrators. In these situations, where either the signing key doesn't match or the encryption key was unknown, this method will return a HTTP 404 with an empty body.

An example request looks like:


{
  "requestHeader": {
    "protocolVersion": {
      "major": 1,
      "minor": 0,
      "revision": 0
    },
    "requestId": "0123434-otp-abc",
    "requestTimestamp": "1502545413098"
  },
  "pushContext": {
    "serverSessionId": "dsrfkslk230980dflksdjflkj",
    "clientSessionId": "999"
  },
  "paymentAccount": {
    "displayName": "Example Customer's Airline Miles Card",
    "billingUserInformation": {
      "name": "Example Customer",
      "addressLine": ["123 Main St"],
      "localityName": "Springfield",
      "administrativeAreaName": "CO",
      "postalCodeNumber": "80309",
      "countryCode": "US",
      "phone": "8675309"
    },
    "paymentCard": {
      "accountNumber": "1234567891011121",
      "expiryMonth": "07",
      "expiryYear": "99"
    }
  },
  "paymentInstrumentMaterial": [
    {
      "tokenizableOpaqueAccountCredential": {
        "opaqueAccountCredential": "9sodjfgpsodigp34ge;kgjsdlfjg;sdlfkjg",
        "tokenServiceProvider": "TOKEN_PROVIDER_VISA",
        "paymentNetwork": "PAYMENT_NETWORK_VISA",
        "publicWalletId": "098123980"
      }
    },
    {
      "paymentCard": {
        "accountNumber": "1234567891011121",
        "expiryMonth": "07",
        "expiryYear": "99"
      }
    }
  ]
}

An example response looks like:


{
  "responseHeader": {
    "responseTimestamp": "1519996752221"
  },
  "result": "SUCCESS"
}

HTTP request

POST https://billpaynotification.googleapis.com/secure-serving/gsp/v1/pushProvisioningNotification

Request body

The request body contains data with the following structure:

JSON representation
{
  "requestHeader": {
    object (RequestHeader)
  },
  "paymentInstrumentMaterial": [
    {
      object (PaymentInstrumentMaterial)
    }
  ],
  "pushContext": {
    object (PushContext)
  },
  "paymentAccount": {
    object (PaymentAccount)
  }
}
Fields
requestHeader

object (RequestHeader)

REQUIRED: Common header for all requests.

paymentInstrumentMaterial[]

object (PaymentInstrumentMaterial)

REQUIRED: The payment instrument items being pushed. List must contain at least one element.

pushContext

object (PushContext)

REQUIRED: Details about an ongoing push provisioning.

paymentAccount

object (PaymentAccount)

REQUIRED: Details about the underlying payment account (as considered separately from PaymentInstrumentMaterials which can actually be used to make payments).

Response body

If successful, the response body contains data with the following structure:

Request message for the v1.pushProvisioningNotification API method.

JSON representation
{
  "responseHeader": {
    object (ResponseHeader)
  },
  "result": enum (PushProvisioningNotificationResultCode)
}
Fields
responseHeader

object (ResponseHeader)

REQUIRED: Common header for all responses.

result

enum (PushProvisioningNotificationResultCode)

REQUIRED: Result of this call.

RequestHeader

Header object that is defined on all requests sent to the server.

JSON representation
{
  "requestId": string,
  "requestTimestamp": string,
  "userLocale": string,
  "protocolVersion": {
    object (Version)
  }
}
Fields
requestId

string

REQUIRED: Unique identifier of this request.

This is a string that has a max length of 100 characters, and contains only the characters "a-z", "A-Z", "0-9", ":", "-", and "_".

requestTimestamp

string (int64 format)

REQUIRED: Timestamp of this request represented as milliseconds since epoch. The receiver should verify that this timestamp is ± 60s of 'now'. This request timestamp is not idempotent upon retries.

userLocale
(deprecated)

string

OPTIONAL: A two- or three-letter ISO 639-2 Alpha 3 language code optionally followed by a hyphen and an ISO 3166-1 Alpha-2 country code, e.g.'pt', 'pt-BR', 'fil', or 'fil-PH'. Use this to help drive the user_message fields in the response.

protocolVersion

object (Version)

REQUIRED: The version of this request.

Version

Version object which is a structured form of the classic a.b.c version structure. Major versions of the same number are guaranteed to be compatible. Note that minor and revisions can change frequently and without notice. The integrator must support all requests for the same major version.

JSON representation
{
  "major": integer,
  "minor": integer,
  "revision": integer
}
Fields
major

integer

REQUIRED: Major version. This is marked for compatibility requests with different versions are not guaranteed to be compatible.

minor

integer

REQUIRED: Minor version. This denotes significant bug fixes.

revision

integer

REQUIRED: Minor version. This denotes minor bug fixes.

PaymentInstrumentMaterial

A payment instrument or the information needed to generate/request one.

JSON representation
{

  // Union field payment_instrument_material_type can be only one of the
  // following:
  "tokenizableOpaqueAccountCredential": {
    object (TokenizableOpaqueAccountCredential)
  },
  "paymentCard": {
    object (PaymentCard)
  }
  // End of list of possible types for union field
  // payment_instrument_material_type.
}
Fields

Union field payment_instrument_material_type.

payment_instrument_material_type can be only one of the following:

tokenizableOpaqueAccountCredential

object (TokenizableOpaqueAccountCredential)

paymentCard

object (PaymentCard)

TokenizableOpaqueAccountCredential

An opaque credential that can be tokenized via a token service provider.

JSON representation
{
  "opaqueAccountCredential": string,
  "publicWalletId": string,
  "tokenServiceProvider": enum (TokenServiceProvider),
  "paymentNetwork": enum (PaymentNetwork)
}
Fields
opaqueAccountCredential

string

REQUIRED: A string, treated opaquely, that allows an integrator to identify the payment account that is being provisioned and the user's authenticated session.

publicWalletId

string

REQUIRED: The wallet instance to which this credential is being tokenized. Generated by Google and given to an integrator, which they give back in this message. Required as it may be necessary in disambiguating cases where multiple credentials are being provisioned at the same time to separate wallet destinations.

tokenServiceProvider

enum (TokenServiceProvider)

REQUIRED: The token service provider to which the opaque payment credential can be sent for tokenization. In the case of device tokenization, OPCs are generated for specific token service providers. Legal values for this field will be provided to integrators directly, but they all begin with "TOKEN_PROVIDER_".

paymentNetwork

enum (PaymentNetwork)

REQUIRED: The payment network on which the resulting token will be usable. Legal values for this field will be provided to integrators directly, but they all begin with "PAYMENT_NETWORK_".

TokenServiceProvider

Legal values for the token service provider will be provided to partners during onboarding.

Enums
TOKEN_SERVICE_PROVIDER_UNSPECIFIED Do not ever set this default value!
TOKEN_PROVIDER_AMEX
TOKEN_PROVIDER_DISCOVER
TOKEN_PROVIDER_MASTERCARD
TOKEN_PROVIDER_VISA

PaymentNetwork

Legal values for the payment network will be provided to partners during onboarding.

Enums
PAYMENT_NETWORK_UNSPECIFIED Do not ever set this default value!
PAYMENT_NETWORK_AMEX
PAYMENT_NETWORK_DISCOVER
PAYMENT_NETWORK_MASTERCARD
PAYMENT_NETWORK_VISA

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.

PushContext

Fields necessary to correlate an inbound push provisioning attempt with a user or session.

JSON representation
{
  "serverSessionId": string,
  "clientSessionId": string
}
Fields
serverSessionId

string

REQUIRED: A session ID that was generated by Google and is passed back from the integrator for verification of consistency (e.g., In Google Pay this session ID is generated by a Google server, stored in a Google database, passed to the integrator on the client side, and then back around to Google through this API, so we can verify that it is the same session ID stored in the database).

clientSessionId

string

REQUIRED: A second session ID that was generated by a web or mobile client and is passed back from the integrator. In practice, this may have been generated by either Google or the integrator. Its primary purpose is for debugging the full end-to-end flow, but it is required and may be checked for consistency.

PaymentAccount

A message that describes an underlying payment account (as opposed to a payment instrument that can be used to pay for things).

JSON representation
{
  "displayName": string,
  "billingUserInformation": {
    object (UserInformation)
  },

  // Union field account_identifier can be only one of the following:
  "paymentCard": {
    object (PaymentCard)
  },
  "paymentAccountReference": {
    object (PaymentAccountReference)
  }
  // End of list of possible types for union field account_identifier.
}
Fields
displayName

string

REQUIRED: A display name that is used to describe the payment account in the user interface during setup. Ideally some description that the user themselves has entered or is otherwise meaningful to them and helps them to understand which account is being added to Google. Note that there are other "nickname" fields in the Google Standard Payments API, and this one differs primarily in that it is only used during the setup phase.

billingUserInformation

object (UserInformation)

REQUIRED: The billing address of the account holder.

Union field account_identifier. Some sort of stable identifier that identifies the underlying account. Note that a PaymentCard used to identify the underlying account will also be stored as a payment instrument. account_identifier can be only one of the following:
paymentCard

object (PaymentCard)

paymentAccountReference

object (PaymentAccountReference)

UserInformation

Structure holding information about a user.

JSON representation
{
  "name": string,
  "addressLine": [
    string
  ],
  "localityName": string,
  "administrativeAreaName": string,
  "postalCodeNumber": string,
  "countryCode": string,
  "phone": string,
  "emailAddress": string
}
Fields
name

string

OPTIONAL: Customer's full name.

addressLine[]

string

OPTIONAL: This holds unstructured Address text.

localityName

string

OPTIONAL: This is something of a fuzzy term, but it generally refers to the city/town portion of an address. In regions of the world where localities are not well defined or do not fit into this structure well (for example, Japan and China), leave localityName empty and use addressLine.

Examples: US city, IT comune, UK post town.

administrativeAreaName

string

OPTIONAL: Top-level administrative subdivision of this country" Examples: US state, IT region, CN province, JP prefecture."

postalCodeNumber

string

OPTIONAL: Despite the name, postalCodeNumber values are frequently alphanumeric. Examples: "94043", "SW1W", "SW1W 9TQ".

countryCode

string

OPTIONAL: Customer address country code, expected to be ISO-3166-1 Alpha-2.

phone

string

OPTIONAL: Customer's phone number.

emailAddress

string

OPTIONAL: Customer's email address.

PaymentAccountReference

The Payment Account Reference, or PAR.

JSON representation
{
  "paymentAccountReference": string
}
Fields
paymentAccountReference

string

REQUIRED: The payment account reference itself.

ResponseHeader

Header object that is defined on all responses sent from the server.

JSON representation
{
  "responseTimestamp": string
}
Fields
responseTimestamp

string (int64 format)

REQUIRED: Timestamp of this response represented as milliseconds since epoch. The receiver should verify that this timestamp is ± 60s of 'now'.

PushProvisioningNotificationResultCode

Result codes for the pushProvisioningNotification method.

Enums
UNKNOWN_RESULT Do not ever set this default value!
SUCCESS The notification was successfully processed.