מדריך Cash FOP (AKA Reference Number API)

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

תרחישים לדוגמה

יש כמה שימושים ב-Reference Number API. במדריך הזה נדון בשני תרחישים לדוגמה ונדריך אתכם בהטמעה שלהם.

מזומן

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

איש הקשר שלך ב-Google יבקש ממך דוגמה של הוראות התשלום הרגילות שלך. תוכלו לעבוד עם איש הקשר שלכם ב-Google כדי לשפר ולחדד את המסר.

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

VAN

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

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

לאחר ש-Google תקבל את ההודעה ReferenceNumberPaidNotification, Google תספק את המוצר והשילוב לא יוכל לבטל את העסקה.

שליחת הודעות בין השרתים שלכם לשרתי Google

בעת שליחת הודעות בין השרתים שלך לשרתים של Google, או להיפך, עשה זאת בהתאם להנחיות האלה.

בקשה נכנסת - DecryptWithVendorPrivateKey(Base64UrlDecode(request))

תגובה יוצאת - Base64UrlEncode(EncryptWithGooglePublicKey(request))

בקשת Google - Base64UrlEncode(EncryptWithGooglePublicKey(request))

תגובת Google - DecryptWithVendorPrivateKey(Base64UrlDecode(request))

הנה ספריית PGP ודוגמה ב-Java שמציגה בקשות ותגובות לטיפול.

מעקב אחר התנהגות אידמפונטית

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

למה היא חשובה

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

איך מטמיעים אידמפוציה

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

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

מידע נוסף זמין במדריך המפורט הזה.

משתמשים במספר החשבון של הכלי לשילוב תשלומים (PIAID)

שילובים עם Google עשויים לחייב שילוב עם הישויות העסקיות השונות של Google. לדוגמה, Google Play היא ישות אחת, ישות אחרת היא YouTube והשנייה היא Google Ads. ההגדרות האלה יכללו חשבונות מוכרים שונים שייצגו כל אחת מההגדרות האלה.

לצורך מיפוי מכל ישות ב-Google לכל חשבון מוכר, Google מספקת מספרי חשבון של כלי לשילוב תשלומים (PIAID). דוגמה ל- Cash FOP API זמינה בכתובת generateReferenceNumber. הנה דוגמה שמשתמשת במיפוי הזה.

לצורך מיפוי מכל ישות ב-Google לכל חשבון מוכר, Google מספקת מספרי חשבון של כלי לשילוב תשלומים (PIAID). דוגמה לשימוש ב-FOP API במזומן: generateReferenceNumber. הנה דוגמה שמשתמשת במיפוי הזה.


{
  "requestHeader": {
    "protocolVersion": {
      "major": 1,
      "minor": 0,
      "revision": 0
    },
    "requestId": "bWVyY2hhbnQgdHJhbnNhY3Rpb24gaWQ",
    "requestTimestamp": "1502220196077"
  },
  "paymentIntegratorAccountId": "InvisiCashUSA_USD",
  "transactionDescription": "Google - Music",
  "currencyCode": "USD",
  "amount": "2000000"
}

שימו לב לחלק המודגש. שני הערכים הנדרשים כאן הם paymentIntegratorAccountId שסופק על ידי איש הקשר ב-Google וחשבון המוכר שלך.

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

ממשקי API לשילוב

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

ממשקי ה-API הבאים מטפלים בהעברת כספים ובהסדרים.

תצטרכו לשלב את כל ממשקי ה-API שצוינו למעלה כדי ליצור מספרי סימוכין ולהסדיר את התשלום עם Google.

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

Google מתקשרת אל GenerateReferenceNumber כשתיזום רכישה. אנחנו מצפים ממך להשיב בצירוף מספר אסמכתה המזהה את העסקה או החשבון. זמן האחזור הצפוי הוא פחות מ-3 שניות.

כשמדובר בעסקאות במזומן, מספר האסמכתה יכול להיות עד 12 תווים.

כתובת URL: POST https://[your basepath]/v1/generateReferenceNumber

בקשת JSON

{
"requestHeader": {
    "protocolVersion": {
      "major": 1,
      "minor": 0,
      "revision": 0
    },
    "requestId": "cf9fde73-3735-4463-8e6e-c999fda35af6",
    "requestTimestamp": "1561678470395"
  },
  "paymentIntegratorAccountId": "Sample_Cash_Vendor_282",
  "transactionDescription": "Google Play - Tester",
  "currencyCode": "USD",
  "amount": "10000000"
}

קובץ JSON של התשובה

{
  "responseHeader": {
    "responseTimestamp": "1561678947659"
  },
  "result": "SUCCESS",
  "referenceNumber": "38a41c05-ba7b-4040-a909-4331d0b9ce46"
}

Java לדוגמה

`String generateReferenceNumberJson = Utils.decryptAndDecode(encodedEncryptedGenerateReferenceNumberRequest);`

GenerateReferenceNumberRequest request = gson.fromJson(generateReferenceNumberJson, GenerateReferenceNumberRequest.class);

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

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

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

כתובת URL: POST https://[your basepath]/v1/cancelReferenceNumber

בקשת JSON

{
"requestHeader": {
    "protocolVersion": {
      "major": 1,
      "minor": 0,
      "revision": 0
    },
    "requestId": "51e00f16-36ba-4490-b228-0a670d202206",
    "requestTimestamp": "1561678947926"
  },
  "paymentIntegratorAccountId": "Sample_Cash_Vendor_282",
  "referenceNumber": "38a41c05-ba7b-4040-a909-4331d0b9ce46"
}

קובץ JSON של התשובה

{
  "responseHeader": {
    "responseTimestamp": "1561680406459"
  },
  "result": "SUCCESS"
}

referenceNumberPaidNotification

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

כתובת ה-URL של נקודת הקצה referenceNumberPaidNotification:


POST https://billpaynotification.googleapis.com/secure-serving/gsp/v1/referenceNumberPaidNotification/[PIAID]

בקשת JSON

{
 "requestHeader": {
    "requestTimestamp": "1561748625577",
    "requestId": "ae8e310a-92de-436a-a32c-0bd753ae4e4b",
    "protocolVersion": {
      "major": 1,
      "minor": 0,
      "revision": 0
    }
  },
  "paymentIntegratorTransactionId": "cf9fde73-3735-4463-8e6e-c999fda35af6",
  "referenceNumber": "e4e15b5d-8154-4068-b6eb-560e2a65ac48",
  "paymentLocation": {
    "brandName": "TestMart",
    "locationId": "1234"
  },
   "paymentIntegratorAccountId": "Sample_Cash_Vendor_282",
  "paymentTimestamp": "1561748625577"
}

קובץ JSON של התשובה

{
  "responseHeader": {
    "responseTimestamp": "1561748642600"
  },
  "result": "SUCCESS"
}

הטמעת העברה של כספים

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

remittanceStatementNotification

יומיים לאחר עסקה, Google תשלח הודעת remittanceStatementNotification שתכיל סיכום של העסקאות ש-Google תיעדה באותו יום. הודעה לדוגמה נראית כך, יומיים לאחר עסקה:

POST https://www.integratordomain.com/v1/remittanceStatementNotification

בקשת JSON


{
  "requestHeader": {
    "protocolVersion": {
      "major": 1,
      "minor": 0,
      "revision": 0
    },
    "requestId": "0123434-statement-abc",
    "requestTimestamp": "1502632800000"
  },
  "paymentIntegratorAccountId": "InvisiCashUSA_USD",
  "remittanceStatementSummary": {
    "statementDate": "1502607600000",
    "billingPeriod": {
      "startDate": "1502434800000",
      "endDate": "1502521199000",
    },
    "dateDue": "1503212400000",
    "currencyCode": "INR",
    "totalDueByIntegrator": "1076000000",
  }
}

שימו לב למיפוי של totalDueByIntegrator. בשורה הזו ניתן לראות את הסכום נטו שהשותף חייב (במיקרו). בנוסף, התאריך וסוג המטבע מופיעים בהודעה הזו, כאשר תקופת החיוב מייצגת את 00:00:00.000 ואת 23:59:59.999 של יום העסקה המוקדם ביותר והיום האחרון של העסקה, בהתאמה.

התאמה (remittanceStatementDetails)

לצורך התאמה, מבצע השילוב יקרא ל-remittanceStatementDetails כדי לקבל את רשימת האירועים הכלולים ב-remittanceStatementNotification.

Google מגיבה לבקשה של remittanceStatementDetails באמצעות רשימת אירועים מעומדת. יש להפעיל את remittanceStatementDetails מספר פעמים אם מספר העסקאות הכולל גדול מ-1,000. אין צורך להגיש את הבקשות ברצף, ואפשר לבצע אותן במקביל.

בקש כתובת אתר

POST https://billpaynotification.googleapis.com/secure-serving/gsp/v1/remittanceStatementDetails

דוגמה לגוף הבקשה

{
  "requestHeader": {
    "protocolVersion": {
      "major": 1,
      "minor": 0,
      "revision": 0
    },
    "requestId": "statement_detail_request_139932019",
    "requestTimestamp": "1502551332087"
  },
  "paymentIntegratorAccountId": "InvisiCashUSA_USD",
  "statementId": "0123434-statement-abc",
  "numberOfEvents": 4
}

בהמשך מופיע קטע קצר של תגובה רחבה יותר, שמתאר שני אירועי תיעוד (עסקאות).

"captureEvents": [ {
    {
      "eventRequestId": "bWVyY2hhbnQgdHJhbnNhY3Rpb24gaWQ",
      "paymentIntegratorEventId": "ioj32SOIjf23oijSDfoij",
      "eventCharge": "700000000",
      "eventFee": "-28000000"
    },
    {
      "eventRequestId": "Ggghvh78200PQ3Yrpb",
      "paymentIntegratorEventId": "iasdf23dSdfijSDfoij",
      "eventCharge": "800000000",
      "eventFee": "-32000000"
    }
  }

למידע נוסף, אפשר לעיין ב-remittanceStatementDetails.

acceptRemittanceStatement וגם acceptRemittanceStatementWithModifications

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

משתמשים בשיטה acceptRemittanceStatement כשאין מיסים על עמלות.

אם המחירים כוללים מס, יש להתקשר אל acceptRemittanceStatementWithModifications ולהגדיר את שיעור המס. אם שיעור המס השתנה, יש לוודא שהוא מעודכן. לאחר ביצוע מוצלח של acceptRemittanceStatement, יש לבצע את ההעברה הבנקאית לחשבון Google.

כתובת URL של בקשה עבור acceptRemittanceStatement

POST https://billpaynotification.googleapis.com/secure-serving/gsp/v1/acceptRemittanceStatement

דוגמה לגוף הבקשה

{
  "requestHeader": {
    "protocolVersion": {
      "major": 1,
      "minor": 0,
      "revision": 0
    },
    "requestId": "0123434-abc",
    "requestTimestamp": "1502545413098"
  },
  "paymentIntegratorAccountId": "InvisiCashUSA_USD",
  "statementId": "0123434-statement-abc"
}

דוגמה לתשובה

{
  "responseHeader": {
    "responseTimestamp": "1519996752221"
  }
  "acceptRemittanceStatementResultCode": "SUCCESS"
}

כתובת URL של בקשה עבור acceptRemittanceStatementWithModifications

POST https://billpaynotification.googleapis.com/secure-serving/gsp/v1/acceptRemittanceStatementWithModifications

דוגמה לגוף הבקשה

{
  "requestHeader": {
    "protocolVersion": {
      "major": 1,
      "minor": 0,
      "revision": 0
    },
    "requestId": "0123434-abc",
    "requestTimestamp": "1502545413098"
  },
  "paymentIntegratorAccountId": "InvisiCashUSA_USD",
  "statementId": "0123434-statement-abc"
  "feeToVatModification": {
    "vatToFeeRatioInMicros": "150000"
  }
}

דוגמה לתשובה

{
  "responseHeader": {
    "responseTimestamp": "1519996752221"
  }
  "acceptRemittanceStatementWithModificationsResultCode": "SUCCESS"
}