Method: card.verifycard

Verifies a user's card to see if it is valid.

This method is called by Google to verify details of a user's card and to see if the card can be used for payments. This call does not move any money and there should be no permanent changes to the user's account.

An example request looks like:


{
  "requestHeader": {
    "protocolVersion": {
      "major": 1,
      "minor": 0,
      "revision": 0
    },
    "requestId": "ZWNobyB0cmFuc2FjdGlvbg",
    "requestTimestamp": "1481855969503"
  },
  "standardCard": {
    "accountNumber": "4123456789101112",
    "expiryDate": "01/2020",
    "cvn": "123"
  },
  "avsData": {
    "streetAddress": "123 Main St APT #200",
    "localityName": "Springfield",
    "administrativeAreaName": "CO",
    "countryCode": "US"
  }
}

An example response looks like:


{
  "responseHeader": {
    "responseTimestamp": "1481855970403",
  },
  "cardNetworkResult": {
    "network": "VISA",
    "iso8583Result": "00",
    "rawNetworkResult": "00"
  },
  "avsResult": {
    "rawAvsResult": "B",
    "streetAddress": "MATCH",
    "localityName": "MATCH",
    "administrativeAreaName": "MATCH",
    "postalCodeNumber": "NOT_SENT",
    "countryCode": "SKIPPED"
  },
  "cvnResult": "MATCH"
}

HTTP request

POST https://card-verification-service.google.com/v1/card/verifycard

The URL uses gRPC Transcoding syntax.

Request body

The request body contains data with the following structure:

JSON representation 
{
  "requestHeader": {
    object(RequestHeader)
  },
  "standardCard": {
    object(StandardCard)
  },
  "avsData": {
    object(AvsData)
  }
}
Fields
requestHeader

object(RequestHeader)

REQUIRED: Common header for all requests.

standardCard

object(StandardCard)

REQUIRED: Data about the user's payment card.

avsData

object(AvsData)

OPTIONAL: The user's address to be verified by AVS.

Response body

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

Response object for the Payment Integrator hosted card.verifycard method.

JSON representation 
{
  "responseHeader": {
    object(ResponseHeader)
  },
  "cardNetworkResult": {
    object(CardNetworkResult)
  },
  "avsResult": {
    object(AvsResult)
  },
  "cvnResult": enum(CvnResult)
}
Fields
responseHeader

object(ResponseHeader)

REQUIRED: Common header for all responses.

cardNetworkResult

object(CardNetworkResult)

REQUIRED: The result of issuing the authorization on the card network.

avsResult

object(AvsResult)

OPTIONAL: The result of verifying the address fields sent in the request.

This field is required if addressVerificationSystemData was set in the the request.
cvnResult

enum(CvnResult)

REQUIRED: The result of verifying the CVN sent in the request. If the CVN was not set on the request, this value should be NOT_SENT.

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": number,
  "minor": number,
  "revision": number
}
Fields
major

number

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

minor

number

REQUIRED: Minor version. This denotes significant bug fixes.

revision

number

REQUIRED: Minor version. This denotes minor bug fixes.

StandardCard

The standard representation of a card

JSON representation 
{
  "accountNumber": string,
  "expiryDate": string,
  "cvn": string
}
Fields
accountNumber

string

REQUIRED: The card's Primary Account Number (PAN) in plain-text.

expiryDate

string

OPTIONAL: The card's expiry date in MM/YYYY format. Optional because certain cards in certain regions do not have an expiry date.

cvn

string

OPTIONAL: If Google collected the CVN from the user it is provided here and should be verified.

AvsData

Contains address fields to be verified by AVS.

JSON representation 
{
  "streetAddress": string,
  "localityName": string,
  "administrativeAreaName": string,
  "postalCodeNumber": string,
  "countryCode": string
}
Fields
streetAddress

string

OPTIONAL: The street address of the user's billing address. When the user has provided multiple lines to input their street address (e.g., a line for apartment number), the lines are concatenated with spaces.

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 address_line.

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

string

OPTIONAL: The top-level administrative subdivision of this country for the user's billing address.

Examples: US state, IT region, UK constituent nation, JP prefecture

When country == US, this is expected to be the 2-character abbreviation for the US State.
postalCodeNumber

string

OPTIONAL: The user's billing postal code.

countryCode

string

OPTIONAL: The country code of the user's billing address in ISO-3166-1 Alpha-2 format.

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'.

CardNetworkResult

Contains a network and a raw result code from that network.

JSON representation 
{
  "network": enum(Network),
  "iso8583Result": string,
  "rawNetworkResult": string
}
Fields
network

enum(Network)

REQUIRED: The network the result code came from.

iso8583Result

string

REQUIRED: The ISO-8583 return code returned by the network.

If the network uses their own response code format, the integrator must map those response codes to the ISO-8583 return codes.
rawNetworkResult

string

REQUIRED: The raw value returned from the network. Networks that use ISO-8583 return codes already will have the same value in this field and in iso8583Result. This field is used to inform Google's risk engine and is most useful for networks that use their own response codes.

Network

Defines the possible card networks that might have returned the rawResult.

Enums
UNKNOWN_NETWORK The network was not recognized
NETWORK_NOT_INVOLVED Use this value if the decline did not come from the network, for instance if the integrator declined the purchase before it was even sent out on the card network.
AMEX AMEX Network
COMPROCARD COMPROCARD Network
DANKORT DANKORT Network
DINACARD DINACARD Network
DINERS_CLUB DINERS_CLUB Network
DISCOVER DISCOVER Network
EFTPOS EFTPOS Network
ELO ELO Network
ENROUTE ENROUTE Network
FELICA FELICA Network
GE_CAPITAL GE_CAPITAL Network
HIPERCARD HIPERCARD Network
ID ID Network
INTERAC INTERAC Network
JCB JCB Network
LASER LASER Network
MAESTRO MAESTRO Network
MASTERCARD MASTERCARD Network
PPT PPT Network
QUICPAY QUICPAY Network
RUPAY RUPAY Network
SBERCARD SBERCARD Network
SOLO SOLO Network
SYNCHRONY SYNCHRONY Network
UNIONPAY UNIONPAY Network
VISA VISA Network

AvsResult

The result of verifying the address fields provided in the request.

All fields are required because we want an explicit result for each field rather than relying on the absence of a field as an implied result.

JSON representation 
{
  "rawAvsResult": string,
  "streetAddress": enum(VerificationResult),
  "localityName": enum(VerificationResult),
  "administrativeAreaName": enum(VerificationResult),
  "postalCodeNumber": enum(VerificationResult),
  "countryCode": enum(VerificationResult)
}
Fields
rawAvsResult

string

REQUIRED: The raw AVS value returned from the card network.

streetAddress

enum(VerificationResult)

REQUIRED: The result of verifying the streetAddress sent in the addressVerificationSystemData field of the request.

If the field was not set in the request, this value should be "NOT_SENT".
localityName

enum(VerificationResult)

REQUIRED: The result of verifying the localityName sent in the addressVerificationSystemData field of the request.

If the field was not set in the request, this value should be "NOT_SENT".
administrativeAreaName

enum(VerificationResult)

REQUIRED: The result of verifying the administrativeAreaName sent in the addressVerificationSystemData field of the request.

If the field was not set in the request, this value should be "NOT_SENT".
postalCodeNumber

enum(VerificationResult)

REQUIRED: The result of verifying the postalCodeNumber sent in the addressVerificationSystemData field of the request.

If the field was not set in the request, this value should be "NOT_SENT".
countryCode

enum(VerificationResult)

REQUIRED: The result of verifying the countryCode sent in the addressVerificationSystemData field of the request.

If the field was not set in the request, this value should be "NOT_SENT".

VerificationResult

Enums
UNKNOWN_AVS_MATCH Do not ever set this default value!
NOT_SENT Google did not send this field so nothing could be done with it.
MATCH Google sent the field to the integrator and it was checked via AVS and it matched the expected value.
MISMATCH Google sent the field to the integrator and it was checked via AVS but did not match the expected value.
SKIPPED Google sent the field to the integrator but the integrator did not check the field.
NOT_SPECIFIED Google sent the field to the integrator and the integrator checked the field via AVS, but the AVS result code does not provide enough info for the integrator to know if the field matched the expected the value.

CvnResult

The result of verifying the CVN provided in the request.

Enums
UNKNOWN_CVN_RESULT Do not ever set this default value!
NOT_SENT Google did not provide the CVN, so it could not be verified.
NOT_VERIFIED Google sent the CVN, but it was not verified. This corresponds to a network result code of "F"
MATCH Google sent the CVN, it was verified, and it matched. This corresponds to a network result code of "M".
MISMATCH Google sent the CVN, it was verified, but it did not match. This corresponds to a network result code of "N".