מספר חשבון
מספר החשבון נשלח חזרה מהשרת של מבצע השילוב במהלך השיוך. הוא עוזר ל-Google לזהות את החשבון הבסיסי בשתי דרכים. הראשונה היא לזהות כמה כלים שמשתמשים באותו חשבון משתמש בסיסי כדי להעריך סיכונים והונאות. שנית, נציגי שירות הלקוחות של Google משתמשים במידע הזה כדי לזהות את החשבון. הערך הזה חייב לזהות באופן ייחודי את חשבון המשתמש בכל בקשות השיוך, והוא חייב להיות לא ניתן לשינוי בחשבון הספציפי, והמשתמשים צריכים לזהות אותו.
לדוגמה, אם שותפה לשילוב מוצרי Google משתמשת בכתובת אימייל כדי לזהות זהות, זו יכולה להיות כתובת האימייל. עם זאת, אם מבצע השילוב משתמש בכתובת אימייל להתחברות אבל אפשר לשנות את הכתובת הזו, לא מומלץ להשתמש בכתובת האימייל במזהה החשבון. בכל מקרה שבו תבחרו, הערך שלו חייב להיות זהה במספר ניסיונות שיוך עם אותה זהות משתמש של כלי לשילוב תשלומים.
חבילת אפליקציות Android (APK)
הפורמט של קובץ החבילות המשמש את מערכת ההפעלה Android להפצה ולהתקנה של אפליקציות לנייד.
ניהול גרסאות API
המפרט הזה תומך בניהול גרסאות. הגרסאות הנתמכות מוגדרות בשרת של Google. כשעוברים מגרסה N ל-M (כאשר M היא גרסה ראשית גדולה מ-N), השילוב צריך לתמוך גם ב-N וגם ב-M עד ש-Google תאמת שכל תעבורת הנתונים הועברה ל-M. הגרסאות מזוהות באופן שונה בהתאם להקשר. ממשקי API ל-Android וממשקי WebRedirect יעבירו את גרסת ה-API כפרמטר לבקשה. הקריאות משרת לשרת מעבירות את הגרסה כחלק מנתיב כתובת ה-URL.
גרסאות אינן קבועות על ידי תהליך העבודה. לכן, במהלך ההעברה מ-N ל-M, מבצע השילוב עשוי לראות תיעוד עם גרסה M והחזר כספי בגרסה N עבור אותה עסקה. במהלך השיוך, מבצע השילוב עשוי לקבל בקשת אימות של גרסה M עם בקשת שיוך של גרסה N.
מזהה השיוך
השדה associationID מזהה את השיוך בין החשבון של הלקוח לבין המכשיר של Google. הערך associationId דומה מאוד ל-GPT. למעשה, משך החיים שלו זהה לזה של GPT, ויש לו עוצמה (cardinality) של 1:1 ל-GPT. הערך associationId שונה מה-GPT ברגישות. ה-GPT הוא אסימון רגיש המשמש לתשלומים. השדה associationId הוא מזהה ציבורי שמייצג את אותו קשר, אבל בעל אופי לא רגיש.
אמצעי התשלום associationId מועבר לשילוב התשלומים במהלך associateAccount. הערך הזה מועבר במהלך האימות מחדש למבצע השילוב. כך יכול השילוב לקבל הקשר לגבי החשבון שצריך לעבור אימות. אם מעבירים את מזהה השיוך, צריך למלא מראש את אותו חשבון שזוהה במהלך השיוך המקורי ולאמת אותו מולו.
מצופה מהכלי לשילוב תשלומים לאחסן את כל מזהי השיוך ולשייך אותם לחשבון משלב מסוים, לכל משך החיים של החוזה בין מבצע השילוב ל-Google.
המזהה של בקשת האימות
השיטות refreshToken, associateAccount ותיעוד (אופציונלי) מתייחסות לאימות. הפורמט של ההפניה הזו הוא requestId של האימות הספציפי שאליו Google מתייחסת. משלב התשלומים ישתמש בשדה הזה כדי לוודא שאכן בוצע אימות בהצלחה של השיטה.
בשיטות לכידה אפשר להזין requestId לאימות. זה קורה בשני מקרים. אם Google תאמת את המשתמש ממש לפני הצילום, Google תמלא את השדה requestId לאימות. בנוסף, לעיתים קרובות Google מבצעת אימות של המשתמש בזמן ההגדרה, כשמוגדר תזמון תשלומים אוטומטי. Google כותבת את האימות requestId בלוח הזמנים ושולחת את הערך requestId יחד עם כל הקלטה המשויכת ללוח הזמנים הזה.
שילובי תשלומים צפויים לאחסן את כל הגדרות האימות של requestIds למשך 30 יום. אם חברה לשילוב תשלומים רוצה לבדוק את requestIds של האימות שיכול להיות קיים בבקשת לכידה, כולל אלה שכלולות בלוחות הזמנים של התשלומים, היא צריכה לאחסן את כל פריטי ה-requestId של האימות למשך כל משך החיים של החוזה בין מבצע השילוב ל-Google.
חברה
חברה היא קונספט שמוגדר בהגדרות ובחוזה של Google. חברה מגדירה את הקשר בין מבצע השילוב ל-Google. מפתחות PGP ורשויות אישורים ברמה הבסיסית של SSL (אופציונלי) משויכים לחברה. הגורם החשוב ביותר הוא שחברה משויכת למזהה חשבון אחד או יותר של כלי לשילוב תשלומים. תגי GPT שנוצרו בתוך חברה פועלים לרוב עם כל מספרי החשבונות לשילוב תשלומים בחברה. יש מקרים חריגים. לדוגמה, אם ה-GPT משויך לחשבון שמוגדר במטבע אחד (ואין בו תמיכה בעמלות FX), ומנסים לבצע רכישה לפי מספר חשבון של כלי לשילוב תשלומים במטבע אחר.
אמצעי תשלום (FOP)
כל העסקאות כוללות אמצעי תשלום אחד או יותר, כמו כרטיס אשראי או העברה בנקאית. אמצעי התשלום האלה משמשים את המשתמשים כדי לשלם ל-Google עבור מוצר או שירותים, או את Google כדי לשלם למשתמשים במקרה של משתמשי AdSense ומפתחים של Google Play. אמצעי תשלום נקראים גם לעיתים קרובות 'אמצעי תשלום', 'אמצעי תשלום' ו'אמצעי תשלום'.
אסימון תשלום של Google (GPT)
GPT הוא ערך אקראי בקידוד base64 שנוצר על ידי שרת Google בזמן השיוך, והוא מועבר לשרת השילוב. GPT הוא מזהה פרטי שמייצג את הקישור בין חשבון המשתמש של מבצע השילוב לבין המכשיר של Google. GPT הוא אסימון שמחליף את פרטי הכניסה של המשתמש או את מזהה החשבון. אסימון זה משמש בתהליך הקנייה כדי לזהות את החשבון לזיכוי או לחיוב, והוא סודי לשני הצדדים. כדי להבטיח פרטיות, אסור לשלוח GPT בטקסט ברור, וההצפנה צריכה להיות מוצפנת.
GPT שונה מ-associationId כי associationId לא מוגן
ועובר בחינם באמצעים ציבוריים (כתובות URL, חיבורים לא מאובטחים). GPT מוכר רק ל-Google ולכלי השילוב.
מטמיע התשלומים אמור לאחסן את כל תגי ה-GPT ולשייך אותם לחשבון משלב ספציפי לכל משך החיים של החוזה בין מבצע השילוב ל-Google.
אי-ספיקות
ניתן להחיל פעולה אידמפונטית מספר פעמים, מבלי לשנות את התוצאה ומבלי לגרום לה תופעות לוואי חדשות מעבר ליישום הראשוני של הפעולה. בדרך כלל, הזיהוי משתמש ב"מפתח" כדי לזהות את אותה הבקשה. כל הבקשות שמוגדרות בין שני השרתים משתמשות במפתח אידמפוטמי שמוגדר בכותרת הבקשה. בכותרת הבקשה יש מזהה בקשה שמשמש כמפתח זהות. מזהה הבקשה הוא ייחודי בכל העולם. בקשות
Idempotent צריכות להיות זהות בדיוק לגוף JSON, למעט חריג אחד. הערך requestTimestamp ישתנה בכל בקשה. זוהי הבחנה חשובה. הערך requestTimestamp הוא השעה שבה השרת שלח את הבקשה הזו. והיא ייחודית לכל ניסיון. התכונה הזו עוזרת להפחית את היכולת לבצע התקפות מחדש.
באופן דומה, תגובה אידמפונטית חייבת להיות זהה לגוף JSON, אבל הערך responseTimestamp יהיה שונה לכל תגובה.
כל השיטות מסוג שרת-אל-שרת מלבד שיטת Echo חייבות להיות אידמפונטיות. בקשות אימות לממשק המשתמש של מבצע השילוב (Android או אתר) הן לא זהות.
במסמך העזר תוכלו לראות דוגמאות להתנהגות אידמפונטית.
מזהה (ID)
מזהים מייצגים טרנזקציה או תקשורת בין שילוב התשלומים ל-Google.
מכשור
אמצעי התשלום מייצג אמצעי תשלום שמור שמשויך ללקוח Google יחיד. דוגמאות לכלי נגינה:
- מספר כרטיס אשראי שרשום במערכת
- חשבון בנק ומספר ניתוב
למשתמשים יכולים להיות מספר אמצעים המשויכים לזהות ב-Google.
Micros
ערכים כספיים ב-API הזה מיוצגים בפורמט שנקרא "micros", תקן ב-Google. מיקרו-נתונים הם פורמט של דיוק קבוע המבוסס על מספרים שלמים. כדי לייצג ערך כספי במיליוניות השנייה, צריך להכפיל את הערך הסטנדרטי של המטבע ב-1,000,000.
לדוגמה:
- 1.23 דולר ארה"ב = 1230000 מיקרו דולר ארה"ב
- 0.01 דולר ארה"ב = 10,000 מיקרו דולר ארה"ב
משלב תשלומים
השילוב החיצוני שמעבד תשלומים בגין טרנזקציית משתמש.
מספר חשבון של כלי לשילוב תשלומים
המזהה הזה מייצג מגבלות סביב החוזה בין Google לבין מבצע השילוב. מספר החשבון של מבצע השילוב נוצר על ידי Google ומוקצה למבצע השילוב בזמן ההגדרה. בדרך כלל מזהה זה נקרא "MID". כל הבקשות והתגובות חייבות לכלול את המזהה הזה. המזהה הזה אטום ואין לנתח אותו. יכול להיות שהפורמט של המזהה הזה לא יהיה עקבי בכל המזהים שהונפקו.
המזהה הזה לא משתנה בכל משך החיים של עסקה. במקרה של הקלטה ושל החזר כספי, ייעשה שימוש באותו מזהה.
האילוצים של מספר החשבון של מבצע השילוב מוגדרים על ידי החוזה עצמו. בדרך כלל, המגבלות מתייחסות לחשבוניות. לדוגמה, חברה לשילוב מוצרי Google תומכת בחשבוניות של CAD ו-MXN כ-USD, אבל דורשת שעסקאות באירו חייבות להיות מחויבות בחשבונית באירו. במקרה הזה, המערכת תשתמש בשני מספרי חשבון שונים לשילוב תשלומים, אחד להנפקת חשבוניות בדולר ארה"ב והשני להנפקת חשבוניות באירו.
אפשר להוציא משימוש את המזהה לטובת מזהים חדשים. אם מוציאים משימוש מזהה מסוים, Google מפסיקה ליזום תיעוד של המזהה הזה. עם זאת, מבצע השילוב חייב לכבד החזרים כספיים על עסקאות שבוצעו נגד אותו מזהה למשך שנה אחת מרגע התחלת התיעוד האחרונה (התחלת הצילום מוגדרת כ-requestTimestamp שנמצא ב-requestHeader).
פרטים אישים מזהים (PII)
פרטים אישיים מזהים (PII) הם מידע שמזהה באופן אישי אדם וכל נתונים אחרים ש-Google יכולה לקשר באופן סביר לפרטים כאלה, כמו שם משתמש, כתובת אימייל, כתובת למשלוח דואר או מספר טלפון, בין אם לבדו או ביחד
בקש מספר מזהה
השדה requestId מזהה את כל התקשורת בין Google לבין משלב התשלומים.
SPII
מידע אישי רגיש (SPII) הוא קבוצת משנה של פרטים אישיים מזהים (PII) שמסכנים את המשתמשים כשהם בסיכון או בשימוש לרעה. במקרים רבים, הפרטים האישיים המזהים (SPII) כוללים דרישות מגבילות לטיפול ולאחסון שחלות על ידי ישויות משפטיות, רגולטוריות וישויות תאימות.
אסימון
האסימונים מוסיפים שכבת אבטחה נוספת כאשר מועברים פרטי כניסה רגישים, כמו פרטים אישיים מזהים (PII) או פרטים אישיים מזהים (SPII) בין Google לבין מבצע השילוב.
כתובת משתמש
בזמן היצירה של אמצעי התשלום, Google בודקת אם המשתמש הוא לקוח של Google Payments. השירות הזה אינו קשור להיות לקוח של Google. כדי להיות לקוחות של Google Payments, אנחנו צריכים את הכתובת לחיוב של המשתמש. יש רשויות רגולטוריות שמחייבות אותנו לדעת את הכתובת המלאה של המשתמש, וסוכנויות אחרות מחייבות קבוצת משנה של הכתובת הזו.
אם לשילוב התשלומים יש כתובת רשומה עבור המשתמש הזה, Google תרצה לקבל את הכתובת הזו בתהליך השיוך כדי למלא מראש עבור המשתמש את טופס הכתובת. המשתמש יכול לשנות את הכתובת שהוזנה מראש. מילוי מראש של כתובת המשתמש מפחית את הקשיים בתהליך ההוספה של כלים, ומגביר את שיעור ההמרה של משתמשים שמוסיפים את הכלים האלו.
אם משתפים את הכתובת, Google משתמשת בה גם כחישוב מודל הסיכונים שלהן. כך מערכת הסיכונים של Google יכולה לפענח את הכתובת שלדברי המשתמש היא מחויבות, ובמקביל להשוות אותה למיקום ה-IP שבו המשתמש נמצא כרגע.
שיתוף כתובות הוא רק אופטימיזציה. זה בסדר וצפוי שלחלק מהשילובים לא תהיה כתובת לחיוב עבור המשתמש או שהם לא יוכלו לשתף כתובת זו.
Web-Safe Base64-Encoding
תקן הקידוד שצוין בקטע RFC 4648, קידוד Base 64 עם URL ו-Filename Safe Alphabet, נקרא לפעמים גם קידוד "web-safe Base64" או "base64url". (הקידוד הזה זהה לקידוד base64 עם כתובת ה-URL והאלפבית הבטוח של שם הקובץ מ-RFC 3548 מקטע 4). יש לקודד את כל הערכים המוצפנים והחתומים באמצעות התקן הזה.