Method: card.verifycard

사용자의 카드가 유효한지 확인합니다.

이 메서드는 Google에서 사용자의 카드의 세부정보를 확인하고 해당 카드를 결제에 사용할 수 있는지 확인하기 위해 호출합니다. 이 통화로 인해 금액이 이전되지는 않으며 사용자 계정에 영구적인 변경사항이 없어야 합니다.

요청의 예는 다음과 같습니다.


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

응답 예는 다음과 같습니다.


{
  "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 요청

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

URL은 gRPC 트랜스코딩 구문을 사용합니다.

요청 본문

요청 본문에는 다음과 같은 구조의 데이터가 포함됩니다.

JSON 표현 
{
  "requestHeader": {
    object(RequestHeader)
  },
  "standardCard": {
    object(StandardCard)
  },
  "avsData": {
    object(AvsData)
  }
}
필드
requestHeader

object(RequestHeader)

필수: 모든 요청의 공통 헤더입니다.

standardCard

object(StandardCard)

필수: 사용자의 결제 카드에 관한 데이터입니다.

avsData

object(AvsData)

선택사항: AVS에서 확인할 사용자의 주소입니다.

응답 본문

성공할 경우 응답 본문에 다음 구조의 데이터가 포함됩니다.

결제 통합업체에서 호스팅하는 card.verifycard 메서드의 응답 객체입니다.

JSON 표현 
{
  "responseHeader": {
    object(ResponseHeader)
  },
  "cardNetworkResult": {
    object(CardNetworkResult)
  },
  "avsResult": {
    object(AvsResult)
  },
  "cvnResult": enum(CvnResult)
}
필드
responseHeader

object(ResponseHeader)

REQUIRED: 모든 응답의 공통 헤더입니다.

cardNetworkResult

object(CardNetworkResult)

REQUIRED: 카드 네트워크에서 승인을 발행한 결과입니다.

avsResult

object(AvsResult)

선택사항: 요청에서 전송한 주소 입력란을 확인한 결과입니다.

요청에서 addressVerificationSystemData가 설정된 경우 이 필드는 필수입니다.
cvnResult

enum(CvnResult)

필수: 요청에 전송된 CVN을 인증한 결과입니다. 요청에 CVN이 설정되지 않은 경우 이 값은 NOT_SENT이어야 합니다.

RequestHeader

서버로 전송된 모든 요청에 정의된 헤더 객체입니다.

JSON 표현 
{
  "requestId": string,
  "requestTimestamp": string,
  "userLocale": string,
  "protocolVersion": {
    object(Version)
  }
}
필드
requestId

string

필수: 이 요청의 고유 식별자입니다.

최대 길이가 100자인 문자열이며 'a~z', 'A~Z', '0-9', ':', '-', '_' 문자만 포함됩니다.
requestTimestamp

string (int64 format)

필수: 에포크 이후 밀리초로 표시되는 이 요청의 타임스탬프입니다. 수신자는 이 타임스탬프가 '지금'의 ±60초인지 확인해야 합니다. 이 요청 타임스탬프는 재시도 시 멱등성을 갖지 않습니다.

userLocale
(deprecated)

string

선택사항: 두 글자 또는 세 글자로 된 ISO 639-2 Alpha 3 언어 코드이며 원하는 경우 하이픈과 ISO 3166-1 Alpha-2 국가 코드가 뒤에 옵니다(예: 'pt', 'pt-BR', 'fil', 'fil-PH'). 응답에서 user_message 필드를 설정하는 데 도움이 됩니다.
protocolVersion

object(Version)

필수: 이 요청의 버전입니다.

버전

기존 a.b.c 버전 구조의 구조화된 형식인 버전 객체입니다. 동일한 번호의 메이저 버전은 호환성이 보장됩니다. 부수적인 변경사항은 예고 없이 자주 변경될 수 있습니다. 통합업체는 동일한 주 버전에 대한 모든 요청을 지원해야 합니다.

JSON 표현 
{
  "major": number,
  "minor": number,
  "revision": number
}
필드
major

number

REQUIRED: 메이저 버전입니다. 이는 다른 버전의 호환성 요청이 호환된다는 보장이 없는 경우에 표시됩니다.

minor

number

필수: 마이너 버전입니다. 이는 중요한 버그 수정을 나타냅니다.

revision

number

필수: 마이너 버전입니다. 사소한 버그 수정을 나타냅니다.

StandardCard

카드의 표준 표현

JSON 표현 
{
  "accountNumber": string,
  "expiryDate": string,
  "cvn": string
}
필드
accountNumber

string

필수: 일반 텍스트로 된 카드의 주 계좌 번호 (PAN)입니다.

expiryDate

string

선택사항: MM/YYYY 형식의 카드 만료일입니다. 특정 지역의 특정 카드에는 만료일이 없기 때문에 선택사항입니다.

cvn

string

선택사항: Google이 사용자로부터 CVN을 수집한 경우 여기에 제공되며 인증을 받아야 합니다.

AvsData

AVS에서 확인할 주소 필드가 포함됩니다.

JSON 표현 
{
  "streetAddress": string,
  "localityName": string,
  "administrativeAreaName": string,
  "postalCodeNumber": string,
  "countryCode": string
}
필드
streetAddress

string

선택사항: 사용자 청구서 수신 주소의 상세 주소입니다. 사용자가 상세 주소를 입력하기 위해 여러 줄 (예: 아파트 동호수를 나타내는 줄)을 제공한 경우 이 줄은 공백으로 연결됩니다.

localityName

string

선택사항: 모호한 용어이지만 일반적으로 주소의 시/군/구 부분을 나타냅니다. 지역이 잘 정의되지 않거나 이 구조에 잘 맞지 않는 지역 (예: 일본 및 중국)의 경우 localityName을 비워 두고 address_line을 사용합니다.

예: 미국 도시, IT 코뮤, 영국 우체국
administrativeAreaName

string

선택사항: 사용자의 청구서 수신 주소에 해당하는 이 국가의 최상위 행정 구역 단위입니다.

예: 미국 주, IT 지역, 영국 선거구, 일본 현

country == US인 경우 미국 주의 2자 약어를 사용해야 합니다.
postalCodeNumber

string

선택사항: 사용자의 청구 우편번호입니다.

countryCode

string

선택사항: 사용자 청구서 수신 주소의 국가 코드입니다(ISO-3166-1 Alpha-2 형식).

ResponseHeader

서버에서 전송된 모든 응답에 정의된 헤더 객체입니다.

JSON 표현 
{
  "responseTimestamp": string
}
필드
responseTimestamp

string (int64 format)

필수: 에포크 이후 밀리초로 표시되는 이 응답의 타임스탬프입니다. 수신자는 이 타임스탬프가 '지금'의 ±60초인지 확인해야 합니다.

CardNetworkResult

네트워크 및 해당 네트워크의 원시 결과 코드를 포함합니다.

JSON 표현 
{
  "network": enum(Network),
  "iso8583Result": string,
  "rawNetworkResult": string
}
필드
network

enum(Network)

필수: 결과 코드의 출처 네트워크입니다.

iso8583Result

string

필수: 네트워크에서 반환된 ISO-8583 반환 코드입니다.

네트워크가 자체 응답 코드 형식을 사용하는 경우 통합자는 이러한 응답 코드를 ISO-8583 반환 코드에 매핑해야 합니다.
rawNetworkResult

string

필수: 네트워크에서 반환된 원시 값입니다. ISO-8583 반환 코드를 사용하는 네트워크는 이미 이 필드와 iso8583Result에 동일한 값을 갖게 됩니다. 이 필드는 Google의 위험 엔진에 정보를 제공하는 데 사용되며 자체 응답 코드를 사용하는 네트워크에 가장 유용합니다.

네트워크

rawResult를 반환했을 수 있는 가능한 카드 네트워크를 정의합니다.

열거형
UNKNOWN_NETWORK 네트워크가 인식되지 않았습니다.
NETWORK_NOT_INVOLVED 구매 거부가 네트워크에서 발생하지 않은 경우, 예를 들어 통합업체에서 구매가 카드 네트워크로 전송되기 전에 구매를 거부한 경우 이 값을 사용합니다.
AMEX AMEX 네트워크
COMPROCARD COMPROCARD 네트워크
DANKORT DANKORT 네트워크
DINACARD DINACARD 네트워크
DINERS_CLUB DINERS_CLUB 네트워크
DISCOVER 디스커버 네트워크
EFTPOS EFTPOS 네트워크
ELO ELO 네트워크
ENROUTE ENROUTE 네트워크
FELICA FELICA 네트워크
GE_CAPITAL GE_CAPITAL 네트워크
HIPERCARD HIPERCARD 네트워크
ID ID 네트워크
INTERAC INTERAC 네트워크
JCB JCB 네트워크
LASER 레이저 네트워크
MAESTRO MAESTRO 네트워크
MASTERCARD MASTERCARD 네트워크
PPT PPT 네트워크
QUICPAY QUICPAY 네트워크
RUPAY RUPAY 네트워크
SBERCARD SBERCARD 네트워크
SOLO SOLO 네트워크
SYNCHRONY SYNCHRONY 네트워크
UNIONPAY UNIONPAY 네트워크
VISA VISA 네트워크

AvsResult

요청에 제공된 주소 필드를 확인한 결과입니다.

암시적 결과로 필드의 부재에 의존하기보다는 각 필드에 명시적 결과를 원하기 때문에 모든 필드가 필요합니다.

JSON 표현 
{
  "rawAvsResult": string,
  "streetAddress": enum(VerificationResult),
  "localityName": enum(VerificationResult),
  "administrativeAreaName": enum(VerificationResult),
  "postalCodeNumber": enum(VerificationResult),
  "countryCode": enum(VerificationResult)
}
필드
rawAvsResult

string

필수: 카드 네트워크에서 반환된 원시 AVS 값입니다.

streetAddress

enum(VerificationResult)

필수: 요청의 addressVerificationSystemData 필드에 전송된 streetAddress를 확인한 결과입니다.

요청에 필드가 설정되지 않은 경우 이 값은 'NOT_SENT'여야 합니다.
localityName

enum(VerificationResult)

필수: 요청의 addressVerificationSystemData 필드에 전송된 localityName를 확인한 결과입니다.

요청에 필드가 설정되지 않은 경우 이 값은 'NOT_SENT'여야 합니다.
administrativeAreaName

enum(VerificationResult)

필수: 요청의 addressVerificationSystemData 필드에 전송된 administrativeAreaName를 확인한 결과입니다.

요청에 필드가 설정되지 않은 경우 이 값은 'NOT_SENT'여야 합니다.
postalCodeNumber

enum(VerificationResult)

필수: 요청의 addressVerificationSystemData 필드에 전송된 postalCodeNumber를 확인한 결과입니다.

요청에 필드가 설정되지 않은 경우 이 값은 'NOT_SENT'여야 합니다.
countryCode

enum(VerificationResult)

필수: 요청의 addressVerificationSystemData 필드에 전송된 countryCode를 확인한 결과입니다.

요청에 필드가 설정되지 않은 경우 이 값은 'NOT_SENT'여야 합니다.

VerificationResult

열거형
UNKNOWN_AVS_MATCH 이 기본값을 설정하면 안 됩니다.
NOT_SENT Google에서 이 필드를 전송하지 않았으므로 아무것도 처리할 수 없습니다.
MATCH Google이 필드를 통합업체에 보냈으며 AVS를 통해 확인되었고 예상 값과 일치했습니다.
MISMATCH Google이 필드를 통합업체에 보냈으며 AVS를 통해 확인했지만 예상 값과 일치하지 않았습니다.
SKIPPED Google이 필드를 통합업체에 보냈지만 통합업체가 필드를 확인하지 않았습니다.
NOT_SPECIFIED Google이 필드를 통합업체에 전송하고 통합업체는 AVS를 통해 필드를 확인했지만 AVS 결과 코드는 필드가 예상된 값과 일치하는지 통합업체가 알 수 있는 충분한 정보를 제공하지 않습니다.

CvnResult

요청에 제공된 CVN을 확인한 결과입니다.

열거형
UNKNOWN_CVN_RESULT 이 기본값을 설정하면 안 됩니다.
NOT_SENT Google에서 CVN을 제공하지 않았으므로 확인할 수 없습니다.
NOT_VERIFIED Google에서 CVN을 전송했지만 확인되지 않았습니다. 네트워크 결과 코드 'F'에 해당합니다.
MATCH Google에서 CVN을 보냈고 인증이 확인되었으며 일치합니다. 이는 네트워크 결과 코드 'M'에 해당합니다.
MISMATCH Google에서 CVN을 전송했으며 인증을 받았지만 일치하지 않았습니다. 이 값은 네트워크 결과 코드 'N'에 해당합니다.