Method: card.verifycard

Verifica o cartão de um usuário para ver se ele é válido.

Esse método é chamado pelo Google para verificar os detalhes do cartão de um usuário e conferir se ele pode ser usado para pagamentos. Esta chamada não transfere nenhum dinheiro e não deve haver alterações permanentes na conta do usuário.

Um exemplo de solicitação é semelhante a este:


{
  "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"
  }
}

Veja um exemplo de resposta:


{
  "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"
}

Solicitação HTTP

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

O URL usa a sintaxe de transcodificação gRPC.

Corpo da solicitação

O corpo da solicitação contém dados com a seguinte estrutura:

Representação JSON 
{
  "requestHeader": {
    object(RequestHeader)
  },
  "standardCard": {
    object(StandardCard)
  },
  "avsData": {
    object(AvsData)
  }
}
Campos
requestHeader

object(RequestHeader)

OBRIGATÓRIO: cabeçalho comum para todas as solicitações.

standardCard

object(StandardCard)

OBRIGATÓRIO: dados sobre o cartão de pagamento do usuário.

avsData

object(AvsData)

OPCIONAL: o endereço do usuário a ser verificado pelo AVS.

Corpo da resposta

Se bem-sucedido, o corpo da resposta incluirá dados com a estrutura a seguir:

Objeto de resposta para o método card.verifycard hospedado pelo integrador de pagamentos.

Representação JSON 
{
  "responseHeader": {
    object(ResponseHeader)
  },
  "cardNetworkResult": {
    object(CardNetworkResult)
  },
  "avsResult": {
    object(AvsResult)
  },
  "cvnResult": enum(CvnResult)
}
Campos
responseHeader

object(ResponseHeader)

OBRIGATÓRIO: cabeçalho comum para todas as respostas.

cardNetworkResult

object(CardNetworkResult)

OBRIGATÓRIO: o resultado da emissão da autorização na rede do cartão.

avsResult

object(AvsResult)

OPCIONAL: o resultado da verificação dos campos de endereço enviados na solicitação.

Esse campo será obrigatório se addressVerificationSystemData tiver sido definido na solicitação.
cvnResult

enum(CvnResult)

OBRIGATÓRIO: o resultado da verificação do CVN enviado na solicitação. Se o CVN não tiver sido definido na solicitação, esse valor precisará ser NOT_SENT.

RequestHeader

Objeto de cabeçalho definido em todas as solicitações enviadas ao servidor.

Representação JSON 
{
  "requestId": string,
  "requestTimestamp": string,
  "userLocale": string,
  "protocolVersion": {
    object(Version)
  }
}
Campos
requestId

string

OBRIGATÓRIO: identificador exclusivo da solicitação.

Essa é uma string com comprimento máximo de 100 caracteres e que contém apenas os caracteres "a-z", "A-Z", "0-9", ":", "-" e "_".
requestTimestamp

string (int64 format)

OBRIGATÓRIO: carimbo de data/hora da solicitação representado como milissegundos desde o período. O destinatário precisa verificar se esse carimbo de data/hora tem cerca de 60 segundos de "agora". Esse carimbo de data/hora da solicitação não é idempotente em novas tentativas.

userLocale
(deprecated)

string

OPCIONAL: um código de idioma ISO 639-2 Alfa 3 de duas ou três letras opcionalmente seguido por um hífen e um código de país ISO 3166-1 Alfa-2 (por exemplo, "pt", "pt-BR", "fil" ou "fil-PH"). Use isso para ajudar a direcionar os campos user_message na resposta.
protocolVersion

object(Version)

OBRIGATÓRIO: a versão da solicitação.

Versão

Objeto de versão, que é uma forma estruturada da estrutura de versão clássica do a.b.c. As principais versões do mesmo número têm a garantia de compatibilidade. Observe que pequenas e revisões podem mudar com frequência e sem aviso prévio. O integrador precisa oferecer suporte a todas as solicitações para a mesma versão principal.

Representação JSON 
{
  "major": number,
  "minor": number,
  "revision": number
}
Campos
major

number

OBRIGATÓRIO: versão principal. Essa opção é marcada para solicitações de compatibilidade com versões diferentes que não têm garantia de compatibilidade.

minor

number

OBRIGATÓRIO: versão secundária. Isso indica correções de bugs significativas.

revision

number

OBRIGATÓRIO: versão secundária. Isso indica pequenas correções de bugs.

StandardCard

Representação padrão de um cartão

Representação JSON 
{
  "accountNumber": string,
  "expiryDate": string,
  "cvn": string
}
Campos
accountNumber

string

OBRIGATÓRIO: o número da conta principal (PAN, na sigla em inglês) do cartão em texto simples.

expiryDate

string

OPCIONAL: a data de validade do cartão no formato MM/AAAA. Opcional, porque alguns cartões em determinadas regiões não têm data de validade.

cvn

string

OPCIONAL: se o Google coletou o CVN do usuário, ele é fornecido aqui e precisa ser verificado.

AvsData

Contém campos de endereço a serem verificados pelo AVS.

Representação JSON 
{
  "streetAddress": string,
  "localityName": string,
  "administrativeAreaName": string,
  "postalCodeNumber": string,
  "countryCode": string
}
Campos
streetAddress

string

OPCIONAL: o endereço de faturamento do usuário. Quando o usuário fornece várias linhas para inserir o endereço (por exemplo, uma linha para o número do apartamento), as linhas são concatenadas com espaços.

localityName

string

OPCIONAL: é um termo impreciso, mas geralmente se refere à parte da cidade de um endereço. Em regiões do mundo onde as localidades não são bem definidas ou não se encaixam bem nessa estrutura (por exemplo, Japão e China), deixe localeName em branco e use address_line.

Exemplos: cidade nos EUA, comunidade na Itália, distrito postal no Reino Unido.
administrativeAreaName

string

OPCIONAL: a subdivisão administrativa de nível superior desse país para o endereço de faturamento do usuário.

Exemplos: estado dos EUA, região da Itália, país constituinte do Reino Unido, prefeitura do Japão

Quando o país for == US, deve ser a abreviação de 2 caracteres do estado dos EUA.
postalCodeNumber

string

OPCIONAL: o CEP de faturamento do usuário.

countryCode

string

OPCIONAL: o código do país do endereço de faturamento do usuário no formato ISO-3166-1 Alpha-2.

ResponseHeader

Objeto de cabeçalho definido em todas as respostas enviadas do servidor.

Representação JSON 
{
  "responseTimestamp": string
}
Campos
responseTimestamp

string (int64 format)

OBRIGATÓRIO: carimbo de data/hora da resposta representado como milissegundos desde o período. O destinatário precisa verificar se esse carimbo de data/hora tem cerca de 60 segundos de "agora".

CardNetworkResult

Contém uma rede e um código de resultado bruto dessa rede.

Representação JSON 
{
  "network": enum(Network),
  "iso8583Result": string,
  "rawNetworkResult": string
}
Campos
network

enum(Network)

OBRIGATÓRIO: a rede de origem do código do resultado.

iso8583Result

string

OBRIGATÓRIO: o código de retorno ISO-8583 retornado pela rede.

Se a rede usar o próprio formato de código de resposta, o integrador vai precisar mapear esses códigos de resposta para os códigos de retorno ISO-8583.
rawNetworkResult

string

REQUIRED: o valor bruto retornado da rede. As redes que usam códigos de retorno ISO-8583 já terão o mesmo valor nesse campo e em iso8583Result. Esse campo é usado para informar o mecanismo de risco do Google e é mais útil para redes que usam os próprios códigos de resposta.

Rede

Define as possíveis redes de cartões que podem ter retornado o rawResult.

Enums
UNKNOWN_NETWORK A rede não foi reconhecida
NETWORK_NOT_INVOLVED Use esse valor se a recusa não tiver vindo da rede, por exemplo, se o integrador recusar a compra antes mesmo de ela ser enviada para a rede do cartão.
AMEX Rede AMEX
COMPROCARD Rede COMPROCARD
DANKORT Rede DANKORT
DINACARD Rede DINACARD
DINERS_CLUB DINERS_CLUB Rede
DISCOVER Rede DISCOVER
EFTPOS Rede EFTPOS
ELO Rede ELO
ENROUTE INSCREVER-SE na rede
FELICA Rede FELICA
GE_CAPITAL GE_CAPITAL Rede
HIPERCARD Rede HIPERCARD
ID ID Rede
INTERAC Rede INTERAC
JCB Rede JCB
LASER Rede LASER
MAESTRO Rede MAESTRO
MASTERCARD Rede MASTERCARD
PPT Rede PPT
QUICPAY Rede QUICPAY
RUPAY Rede RUPAY
SBERCARD Rede SBERCARD
SOLO Rede SOLO
SYNCHRONY Rede SYNCHRONY
UNIONPAY Rede UNIONPAY
VISA Rede VISA

AvsResult

O resultado da verificação dos campos de endereço fornecidos na solicitação.

Todos os campos são obrigatórios porque queremos um resultado explícito para cada campo, em vez de confiar na ausência de um campo como um resultado implícito.

Representação JSON 
{
  "rawAvsResult": string,
  "streetAddress": enum(VerificationResult),
  "localityName": enum(VerificationResult),
  "administrativeAreaName": enum(VerificationResult),
  "postalCodeNumber": enum(VerificationResult),
  "countryCode": enum(VerificationResult)
}
Campos
rawAvsResult

string

OBRIGATÓRIO: o valor AVS bruto retornado da rede do cartão.

streetAddress

enum(VerificationResult)

OBRIGATÓRIO: o resultado da verificação do streetAddress enviado no campo addressVerificationSystemData da solicitação.

Se o campo não foi definido na solicitação, esse valor deve ser "NOT_SENT".
localityName

enum(VerificationResult)

OBRIGATÓRIO: o resultado da verificação do localityName enviado no campo addressVerificationSystemData da solicitação.

Se o campo não foi definido na solicitação, esse valor deve ser "NOT_SENT".
administrativeAreaName

enum(VerificationResult)

OBRIGATÓRIO: o resultado da verificação do administrativeAreaName enviado no campo addressVerificationSystemData da solicitação.

Se o campo não foi definido na solicitação, esse valor deve ser "NOT_SENT".
postalCodeNumber

enum(VerificationResult)

OBRIGATÓRIO: o resultado da verificação do postalCodeNumber enviado no campo addressVerificationSystemData da solicitação.

Se o campo não foi definido na solicitação, esse valor deve ser "NOT_SENT".
countryCode

enum(VerificationResult)

OBRIGATÓRIO: o resultado da verificação do countryCode enviado no campo addressVerificationSystemData da solicitação.

Se o campo não foi definido na solicitação, esse valor deve ser "NOT_SENT".

VerificationResult

Enums
UNKNOWN_AVS_MATCH Nunca defina esse valor padrão.
NOT_SENT O Google não enviou este campo, então não foi possível fazer nada com ele.
MATCH O Google enviou o campo para o integrador, que foi verificado pelo AVS e correspondeu ao valor esperado.
MISMATCH O Google enviou o campo para o integrador e ele foi verificado via AVS, mas não correspondeu ao valor esperado.
SKIPPED O Google enviou o campo para o integrador, mas ele não o verificou.
NOT_SPECIFIED O Google enviou o campo para o integrador, e ele verificou o campo via AVS, mas o código de resultado do AVS não fornece informações suficientes para saber se o campo corresponde ao valor esperado.

CvnResult

O resultado da verificação do CVN na solicitação.

Enums
UNKNOWN_CVN_RESULT Nunca defina esse valor padrão.
NOT_SENT O Google não forneceu o CVN, por isso não foi possível fazer a verificação.
NOT_VERIFIED O Google enviou o CVN, mas ele não foi verificado. Isso corresponde a um código de resultado de rede "F"
MATCH O Google enviou o CVN, ele foi verificado e correspondeu. Isso corresponde a um código de resultado de rede de "M".
MISMATCH O Google enviou o CVN. Ele foi verificado, mas não corresponde. Isso corresponde a um código de resultado de rede de "N".