תשלום במזומן

סקירה כללית

Google Standard Payments תומכת באמצעי תשלום מבוססי-מזומן (אמצעי תשלום), כמו רכישות בחנות נוחות (למשל 7-Eleven). ברמה הכללית, משתמש שרוצה לשלם על מוצרים יוצר מספר אסמכתה דרך כלי השילוב של תשלומים. לאחר מכן המשתמש לוקח את מספר האסמכתה הזה לחנות נוחות, לקיוסק או לבנק ומשלם אותו.

הוספת תשלום
1) המשתמש מוסיף אמצעי תשלום
בחירת מיקום לתשלום
2) אחר כך הם בוחרים איפה לשלם
הוראות תשלום
3) לבסוף, הם מקבלים הוראות תשלום

מושגים וטרמינולוגיה

Symbols & Conventions

The key words "MUST," "MUST NOT," "REQUIRED," "SHALL," "SHALL NOT," "SHOULD," "SHOULD NOT," "RECOMMENDED," "MAY," and "OPTIONAL" in these documents are to be interpreted as described in RFC 2119.

Timestamps

All timestamps are represented as milliseconds since the Unix epoch (Jan 1, 1970) in UTC.

For example:

  • April 23, 2019 8:23:25 PM GMT = 1556051005000 milliseconds
  • August 16, 2018 12:28:35 PM GMT = 1534422515000 milliseconds

Amounts

Monetary values in this API are in a format called "micros," a standard at Google. Micros are an integer based, fixed precision format. To represent a monetary value in micros, multiply the standard currency value by 1,000,000.

For example:

  • USD$1.23 = 1230000 micro USD
  • USD$0.01 = 10000 micro USD

Idempotency

All method calls within this API must have idempotent behavior. Google will sporadically retry requests to ensure that transactions are in the same state on both sides. Integrators should not attempt to reprocess any request already successfully processed. The response for the successful processing should be reported instead. All methods have a common RequestHeader which contains a requestId. This requestId is the idempotency key for all calls.

Any non terminal response (a non HTTP 200-success), must not be idempotently processed. So a request that previously got a 400 (bad request/failed precondition), when called a second time, must not idempotently return 400, it must be re-evaluated. At re-evaluation, it could return a 400 or be processed successfully.

For more information on idempotency see this detailed guide.

Integrator

A company who uses Google’s Payment Platform for their business. It could be internal (1P), such as Youtube or AdWords, It can also be an external (3P) business wanting to integrate their service to work with Google’s ecosystem.

FOP

Form of Payment. This is more general than an instrument. Visa, MasterCard, and PayPal are all FOPs.

Instrument

A particular instance of a form of payment by a specific customer. For instance, a user’s credit card, or their PayPal account. A tokenized FOP for a particular customer is also an instrument, because it is an instance of a form of payment for that customer, securely stored on our system.

Token

A representation, on Google’s system, of a specific user’s payment method. Since it contains all the information needed to make a purchase, a token is also an instrument. This may include such information as an account number a user has with their integrator.

תהליכי מפתח

Google משתמשת בשני תהליכי מפתח כדי ליצור את מספרי האסמכתה האלה ולשלם עבורם:

  1. יצירת זרימה של מספרי אסמכתה.
  2. תהליך של מספר אסמכתה לתשלום.

לאחר מכן, ההתאמה וההסדר מהרכישות שבוצעו מטופלים על ידי תהליך העברת הכספים.

התרשים הבא ממחיש כל אחד מהתהליכים האלה.

סקירה כללית על אמצעי תשלום במזומן

סקירה כללית ברמה גבוהה של אמצעי תשלום במזומן

שני התהליכים הראשונים מתוארים בפירוט בסעיפים הבאים. בדף תהליך העברת הכספים מפורט מידע נוסף על התהליך הזה.

יצירת מספר אסמכתה

מטרת התהליך של יצירת מספר האסמכתה היא ליצור ולהחליף מזהה (מספר אסמכתה) שגם Google וגם מבצע השילוב יכולים להשתמש בו כדי לזהות רכישה. לאחר מכן המשתמש יכול להשתמש במספר האסמכתה הזה בחנות נוחות, בקיוסק או בבנק כדי להשלים את הרכישה. המזהה הזה נוצר על ידי מבצע השילוב לבקשת Google באמצעות קריאה לשיטה generateReferenceNumber. הבקשה ליצירת מספר האסמכתה כוללת סכום ותיאור עסקה.

בתרשים הבא אפשר לראות איך מספר אסמכתה נוצר ונשלח ללקוח, עם הוראות.

יצירת זרימה של מספרי אסמכתה

מספר סימוכין ליצירת כסף

הנה רשימה של האובייקטים ומה הם מייצגים:

  • משתמש: המשתמש שרוצה לשלם על משהו באמצעות אמצעי התשלום הזה.
  • ממשק המשתמש של Google: זהו הממשק שבו המשתמש מבצע את הרכישה. זה יכול להיות דרך האינטרנט או דרך אפליקציה.
  • שרת Google: שרת הקצה העורפי ב-Google שמבקש את מספר האסמכתה ויוצר הוראות תשלום למשתמש.
  • שרת משלב התשלומים: שרת הקצה העורפי של הכלי לשילוב תשלומים שעוקב אחרי פרטי התשלום ומפיק את מספר האסמכתה.

התהליך הזה מתחיל במשתמש שרוצה להשתמש באמצעי התשלום הזה במזומן.

  1. המשתמש ניגש לממשק המשתמש של Google ששולח בקשה למספר אסמכתה.
  2. ממשק המשתמש של Google שולח הודעה לשרת Google על כך שנדרש מספר סימוכין (getReferenceNumber).
  3. השרת של Google מבקש מהשרת לשילוב תשלומים ליצור מספר אסמכתה (generateReferenceNumber).
  4. השרת של שילוב התשלומים יוצר ושולח את מספר האסמכתה לשרת של Google.
  5. שרת Google יוצר הוראות תשלום יחד עם מספר האסמכתה. לאחר מכן הוא שולח את המידע הזה לממשק המשתמש של Google.
  6. ממשק המשתמש של Google שולח את ההוראות ואת מספר האסמכתה האלה למשתמש.

הערות לגבי מספרי אסמכתה

ניתן לשלם את מספרי הסימוכין פעם אחת בלבד, וניתן לבטל אותם באמצעות התהליך של ביטול מספר האסמכתה. כמו כן, מספרי הסימוכין חייבים להיות אלפאנומריים וצריכים לתמוך בפורמטים מרובים לתצוגה.

בנוסף להצגת מספר האסמכתה, ממשקי המשתמש של Google יכולים לייצג את מספר הסימוכין בפורמט קוד 128 (פורמט ברקוד). ניתן לבקש תמיכה בפורמטים אחרים של ברקוד.

מספר הסימוכין של התשלום

המשתמש ישתמש במספר האסמכתה הזה בחנות נוחות, בקיוסק או בבנק כדי לזהות את הרכישה שעליה הוא רוצה לשלם. מבצע השילוב צריך לבקש מהמשתמש לאשר את התשלום על הרכישה על ידי הצגת סכום הרכישה, התאריך ותיאור העסקה לפני התשלום.

ברגע שהמשתמש בוחר לשלם, הוא צריך לשלם במלואו ולשלם רק פעם אחת. ה-API הזה לא תומך בתשלומים בסכום גבוה או נמוך יותר למספר אסמכתה אחד. אין תמיכה בתשלומים מרובים למספר אסמכתה יחיד.

אחרי שהמשתמש משלם, מבצע השילוב צריך להודיע ל-Google באופן מיידי שמספר האסמכתה הזה שולם באמצעות השיטה referenceNumberPaidNotification. המבצע מופעל לשיטה הזו תוך שניות ספורות מרגע התשלום הפיזי של המשתמש, וכך מאפשר למשתמש לקבל את המוצרים שלו במהירות. (ניתן להוסיף את השיחה הזו לתור אם הרשת מושבתת).

לאחר התשלום, מספר האסמכתה והסכום ייכללו בהצהרת העברת הכספים שנשלחה ב-T+2 ימים.

הנה תרשים רצף שממחיש את התשלום של מספר אסמכתה.

תהליך עבודה עם מספר אסמכתה של תשלום

תהליך עבודה עם מספר אסמכתה של תשלום

האובייקטים בתרשים מייצגים את הדברים הבאים:

  • משתמש: המשתמש שרוצה לשלם על משהו באמצעות אמצעי התשלום הזה.
  • חנות נוחות: המיקום שבו המשתמש מבצע את התשלום לפי מספר האסמכתה וההוראות שניתנו, כמו חנות נוחות.
  • שרת כלי לשילוב תשלומים: שרת הקצה העורפי של הכלי לשילוב תשלומים שעוקב אחרי פרטי התשלום.
  • שרת Google: שרת הקצה העורפי ב-Google שמבקש את מספר האסמכתה ויוצר הוראות תשלום למשתמש.

תהליך זה מתחיל במשתמש שהולך לחנות נוחות כדי לבצע תשלום בהתאם להוראות שניתנו לו.

  1. המשתמש מגיע לחנות נוחות כדי לבצע תשלום.
  2. לאחר השלמת העסקה, נשלחת לחנות הנוחות הודעה על כך לשילוב התשלומים.
  3. נשלחת הודעת אימות לחנות הנוחות דרך השרת של שילוב התשלומים.
  4. חנות הנוחות מציינת שהעסקה בוצעה בהצלחה מבחינת המשתמש, והמוצרים יסופקו למשתמש בקרוב.
  5. השרת של שילוב התשלומים שולח הודעה לשרת של Google על כך שמספר האסמכתה שולם (referenceNumberPaidNotification). השלב הזה לא יכול לחסום את שלב 4.
  6. נשלחת מ-Google Server הודעת אישור לשרת של שילוב התשלומים.

ביטול מספר האסמכתה

Google יכולה לבטל את מספרי הסימוכין. אם Google תבטל מספר אסמכתה, תתבצע קריאה לשיטה cancelReferenceNumber. לאחר שהשיחה חוזרת, לא ניתן לשלם באמצעות מספר האסמכתה הזה, והמטמיע חייב לדחות את התשלום עבור המספר הזה. אחרי שהשיחה הזו תתבצע בהצלחה, כל השיחות העתידיות אל referenceNumberPaidNotification ייכשלו.

אם תהליך התשלום כבר התחיל, לדוגמה, אם המשתמש הזין את מספר האסמכתה בקיוסק אבל עדיין לא שילם, מבצע השילוב צריך להחזיר קוד תגובה HTTP 423 עם ErrorResponse שמכיל את USER_ACTION_IN_PROGRESS.

השלב הבא: תהליך העברת הכספים