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

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

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

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

  • מזומן - המשתמש משלם במזומן במיקום פיזי.
  • VAN – המשתמש מעביר כסף למספר חשבון וירטואלי.

מזומן

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

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

חוויית המשתמש ש-Google רוצה לספק היא שההזמנה של הלקוח נמסרת כשהוא יוצא מהחנות. Google מצפה לקבל ב-Google את ReferenceNumberPaidNotification תוך שלוש דקות מרגע שהלקוח שילם את מספר האסמכתה. אחרי שליחת ה-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). דוגמה ל-API של אמצעי תשלום מזומנים מופיעה בכתובת generateReferenceNumber. הנה דוגמה שמשתמשת במיפוי הזה.

למיפוי מכל ישות ב-Google לכל חשבון מוכר, Google מספקת מספרי חשבונות של כלי שילוב תשלומים (PIAID). דוגמה לשימוש ב-Cash 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 ו-ErrorResponse בגוף הבקשה, עם הסטטוס 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 תקבל את ההודעה, היא תצפה שהעסקה תהיה סופית ולא ניתן יהיה להזמין אותה.

כתובת ה-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"
}