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)

חובה: כותרת משותפת לכל התשובות.

cardNetworkResult

object(CardNetworkResult)

חובה: התוצאה של הנפקת ההרשאה ברשת הכרטיס.

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)

REQUIRED: חותמת הזמן של הבקשה הזו, מיוצגת באלפיות השנייה מאז epoch. על המקבל לאמת שחותמת הזמן הזו היא בטווח של ± 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

חובה: הגרסה הראשית. הוא מסומן עבור בקשות תאימות עם גרסאות שונות לא מובטח שהן יעמדו בדרישות.

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.

טיפוסים בני מנייה (enum)
UNKNOWN_NETWORK הרשת לא זוהתה
NETWORK_NOT_INVOLVED צריך להשתמש בערך הזה אם הדחייה לא הגיעה מהרשת, לדוגמה אם השילוב דחה את הרכישה לפני שהיא נשלחה ברשת הכרטיסים.
AMEX רשת AMEX
COMPROCARD רשת COMPROCARD
DANKORT רשת DANKORT
DINACARD רשת DINACARD
DINERS_CLUB רשת DINERS_CLUB
DISCOVER רשת Discover
EFTPOS רשת EFTPOS
ELO רשת ELO
ENROUTE רשת אחרת
FELICA רשת FELICA
GE_CAPITAL רשת GE_CAPITAL
HIPERCARD רשת HIPERCARD
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)

חובה: התוצאה של אימות הערך streetAddress שנשלח בשדה addressVerificationSystemData של הבקשה.

אם השדה לא הוגדר בבקשה, הערך צריך להיות NOT_SENT.
localityName

enum(VerificationResult)

חובה: התוצאה של אימות הערך localityName שנשלח בשדה addressVerificationSystemData של הבקשה.

אם השדה לא הוגדר בבקשה, הערך צריך להיות NOT_SENT.
administrativeAreaName

enum(VerificationResult)

חובה: התוצאה של אימות הערך administrativeAreaName שנשלח בשדה addressVerificationSystemData של הבקשה.

אם השדה לא הוגדר בבקשה, הערך צריך להיות NOT_SENT.
postalCodeNumber

enum(VerificationResult)

חובה: התוצאה של אימות הערך postalCodeNumber שנשלח בשדה addressVerificationSystemData של הבקשה.

אם השדה לא הוגדר בבקשה, הערך צריך להיות NOT_SENT.
countryCode

enum(VerificationResult)

חובה: התוצאה של אימות הערך countryCode שנשלח בשדה addressVerificationSystemData של הבקשה.

אם השדה לא הוגדר בבקשה, הערך צריך להיות NOT_SENT.

VerificationResult

טיפוסים בני מנייה (enum)
UNKNOWN_AVS_MATCH אל תגדירו את ערך ברירת המחדל הזה אף פעם!
NOT_SENT Google לא שלחה את השדה הזה, לכן לא ניתן היה לעשות איתו שום דבר.
MATCH Google שלחה את השדה למטמיע והוא נבדק באמצעות AVS והוא התאים לערך הצפוי.
MISMATCH Google שלחה את השדה למטמיע והוא נבדק באמצעות AVS, אבל הוא לא התאים לערך הצפוי.
SKIPPED Google שלחה את השדה למטמיע, אבל מבצע השילוב לא בדק את השדה.
NOT_SPECIFIED Google שלחה את השדה למבצע השילוב, והכלי בדק את השדה באמצעות פעולת AVS, אבל קוד התוצאה של ה-AVS לא סיפק מספיק מידע כדי לאפשר למטמיע לדעת אם השדה תואם לערך הצפוי.

CvnResult

התוצאה של אימות מספר אימות הכרטיס שסופק בבקשה.

טיפוסים בני מנייה (enum)
UNKNOWN_CVN_RESULT אל תגדירו את ערך ברירת המחדל הזה אף פעם!
NOT_SENT Google לא סיפקה את מספר אימות הכרטיס (CVN) ולכן לא ניתן היה לאמת אותו.
NOT_VERIFIED Google שלחה את מספר אימות הכרטיס, אבל הוא לא אומת. הוא תואם לקוד של תוצאת הרשת "F"
MATCH Google שלחה את מספר אימות הכרטיס (CVN), הוא אומת ונמצא תואם. הוא תואם לקוד תוצאת הרשת "M".
MISMATCH Google שלחה את מספר אימות הכרטיס. הוא אומת אבל הוא לא תואם. הוא תואם לקוד תוצאת הרשת "N".