- בקשת HTTP
- גוף הבקשה
- גוף התשובה
- RemittanceStatementSummary
- BillingPeriod
- RemittanceInstructions
- אירוע
מחזירה פרטי עסקה של הצהרת תשלום.
זהו API לפי חלוקה לדפים. אפשר לציין את מספר אירועי העסקאות בכל דף באמצעות numberOfEvents
. אם לא צוין, יוחזר המספר המקסימלי של 1,000 אירועים לכל דף. כל בקשה ל-API הזה תחזיר nextEventOffset
שמפנה לאירוע העסקה הבא בדוח, וגם totalEvents
שמציין את מספר העסקאות הכולל בדוח. אם הדף הנוכחי שאוחזר מכיל את העסקאות האחרונות בדוח, לא יופיע nextEventOffset
בתגובה.
הערך של statementId
הוא requestId
מ-remittanceStatementNotificationRequest
אם נקודת הקצה נתקלת בשגיאה במהלך עיבוד הבקשה, התשובה מנקודת הקצה הזו תהיה מסוג
.ErrorResponse
אם השיטה הזו לא מחזירה HTTP 200, התשובות לשאילתה הזו יכולות להיות ריקות. גוף התגובה הוא ריק במצבים שבהם
עם תיאור ברור יכול לעזור לתוקפים להבין את מזהה החשבון של מבצע השילוב של התשלומים של משלבים אחרים. במצבים כאלה, שבהם מפתח החתימה לא תואם, המזהה של משלב התשלומים לא נמצא או שמפתח ההצפנה לא היה ידוע, השיטה הזו תחזיר קוד HTTP 404 עם גוף ריק. אם ניתן לאמת את חתימת הבקשה, בגוף התגובה יוחזר מידע נוסף לגבי השגיאה.ErrorResponse
בקשה לדוגמה נראית כך:
{
"requestHeader": {
"protocolVersion": {
"major": 1,
"minor": 0,
"revision": 0
},
"requestId": "statement_detail_request_139932019",
"requestTimestamp": "1502551332087"
},
"paymentIntegratorAccountId": "InvisiCashUSA_USD",
"statementId": "0123434-statement-abc",
"numberOfEvents": 4
}
דוגמה לתשובה:
{
"responseHeader": {
"responseTimestamp": "1481900013178"
},
"eventOffset": 0,
"nextEventOffset": 4,
"totalEvents": 15,
"remittanceStatementSummary": {
"statementDate": "1502521200000",
"billingPeriod": {
"startDate": "1502434800000",
"endDate": "1502434800000"
},
"dateDue": "1502348400000",
"currencyCode": "INR",
"totalDueByIntegrator": "1076000000",
"remittanceInstructions": {
"memoLineId": "stmt-1AB-pp0-invisi"
}
},
"captureEvents": [
{
"eventRequestId": "bWVyY2hhbnQgdHJhbnNhY3Rpb24gaWQ",
"paymentIntegratorEventId": "ioj32SOIjf23oijSDfoij",
"eventCharge": "700000000",
"eventFee": "-28000000"
},
{
"eventRequestId": "Ggghvh78200PQ3Yrpb",
"paymentIntegratorEventId": "iasdf23dSdfijSDfoij",
"eventCharge": "800000000",
"eventFee": "-32000000"
}
],
"refundEvents": [
{
"eventRequestId": "liUrreQY233839dfFFb24gaQM",
"paymentIntegratorEventId": "asd3SDf3f3oijSDfoij",
"eventCharge": "-200000000",
"eventFee": "8000000"
},
{
"eventRequestId": "IIghhhUrreQY233839II9qM==",
"paymentIntegratorEventId": "DFjidoso12FSDFSDE",
"eventCharge": "-150000000",
"eventFee": "6000000"
}
]
}
בקשת HTTP
POST https://vgw.googleapis.com/secure-serving/gsp/v1/remittanceStatementDetails/:PIAID
גוף הבקשה
גוף הבקשה מכיל נתונים במבנה הבא:
ייצוג JSON |
---|
{
"requestHeader": {
object ( |
שדות | |
---|---|
requestHeader |
חובה: כותרת משותפת לכל הבקשות. |
paymentIntegratorAccountId |
חובה: זהו מזהה החשבון של הכלי לשילוב תשלומים שמזהה מגבלות חוזיות סביב ההצהרה הזו. |
statementId |
חובה: מזהה הבקשה של ההודעה בנוגע לדף החשבון. |
eventOffset |
אופציונלי: החזרת אירועים שמתחילים מההיסט הזה. יש להגדיר את הערך הזה כ- |
numberOfEvents |
אופציונלי: מספר האירועים שיוצגו בכל דף. אם לא צוין או גדול מ-1,000, הערך יהיה 1,000. |
גוף התגובה
אובייקט תשובה לשיטה של פרטי הצהרת התשלום.
אם הפעולה בוצעה ללא שגיאות, גוף התגובה יכלול נתונים במבנה הבא:
ייצוג JSON |
---|
{ "responseHeader": { object ( |
שדות | |
---|---|
responseHeader |
חובה: כותרת נפוצה לכל התשובות. |
remittanceStatementSummary |
חובה: סיכום של הצהרת התשלום הזו. |
eventOffset |
חובה: קיזוז האירוע מהתגובה הזו. |
nextEventOffset |
אופציונלי: ההיסט של האירוע הבא שיש להחזיר. אם לא צוין, אין אירועים נוספים לאחזור עבור הצהרה זו. |
totalEvents |
חובה: המספר הכולל של האירועים שמופיעים בדף החשבון הזה. |
totalWithholdingTaxes |
חובה: הסכום של כל המיסים שנוכו במקור מהדוח הזה. הערך הזה מוגדר במיקרו-מיקרו. |
captureEvents[] |
חובה: קבוצת אירועים לתיעוד. |
refundEvents[] |
חובה: קבוצת אירועים של החזרים כספיים. |
reverseRefundEvents[] |
אופציונלי: קבוצת אירועים של החזר כספי הפוך. |
chargebackEvents[] |
אופציונלי: קבוצת אירועים של החזר כספי בעקבות ביטול עסקה. |
reverseChargebackEvents[] |
אופציונלי: קבוצת אירועים של החזר כספי הפוך. |
adjustmentEvents[] |
אופציונלי: קבוצה של אירועי התאמה. ניתן להוסיף אירועי התאמה לפי שיקול דעתה של Google כדי לגשר על פערים בחיוב. לדוגמה, אם חושבו עמלות נמוכות מדי בקבוצת עסקאות קודמות, ייתכן שייעשה שימוש בהתאמה כדי לבצע את השילוב כולו. |
RemittanceStatementSummary
אובייקט סיכום לגבי הצהרת תשלום.
ייצוג JSON |
---|
{ "statementDate": string, "billingPeriod": { object ( |
שדות | |
---|---|
statementDate |
חובה: התאריך (באמריקה/לוס אנג'לס) שבו נוצרה ההצהרה. |
billingPeriod |
חובה: תקופת החיוב שמוגדרת בדף החשבון. |
dateDue |
אופציונלי: התאריך שבו יש להעביר את התשלום. הנתונים האלה מיוצגים כאלפיות שנייה מתחילת התקופה (epoch). זהו תאריך (ולכן הוא יתחיל תמיד באלפיות השנייה הראשונה של היום באזור הזמן של החיוב). ערך זה מוגדר כל עוד הערך של |
currencyCode |
חובה: קוד מטבע בן 3 אותיות לפי תקן ISO 4217. |
totalDueByIntegrator |
חובה: הערך הזה הוא במיקרו במטבע |
remittanceInstructions |
נדרש: פרטים על אופן ביצוע התשלום |
BillingPeriod
תקופת החיוב בדף החשבון הזה.
ייצוג JSON |
---|
{ "startDate": string, "endDate": string } |
שדות | |
---|---|
startDate |
חובה: תאריך ההתחלה של תקופת החיוב. הנתונים האלה מיוצגים כאלפיות שנייה מתחילת התקופה (epoch). זהו תאריך (ולכן הוא יתחיל תמיד באלפיות השנייה הראשונה של היום באזור הזמן של החיוב). זוהי אלפית השנייה הראשונה של היום בתקופת החיוב, 00:00:00.000 |
endDate |
חובה: תאריך הסיום של תקופת החיוב. הנתונים האלה מיוצגים כאלפיות שנייה מתחילת התקופה (epoch). זוהי אלפית השנייה האחרונה של היום האחרון של תקופת החיוב, 23:59:59.999 |
RemittanceInstructions
מבנה שמכיל מידע לגבי אופן התשלום של הודעת התשלום.
ייצוג JSON |
---|
{ "memoLineId": string } |
שדות | |
---|---|
memoLineId |
חובה: מזהה שחובה להוסיף בשורת התזכיר של התשלום לצורך זיהוי תשלום. |
אירוע
מבנה שמייצג אירוע יחיד שנכלל בהצהרת תשלום.
ייצוג JSON |
---|
{ "eventRequestId": string, "paymentIntegratorEventId": string, "eventCharge": string, "eventFee": string, "presentmentChargeAmount": string, "presentmentCurrencyCode": string, "exchangeRate": string, "nanoExchangeRate": string } |
שדות | |
---|---|
eventRequestId |
חובה: במקרה של תיעוד או אירוע של החזר כספי, אלה יהיו ה |
paymentIntegratorEventId |
חובה: מזהה של משלב התשלומים שהוחזר עבור האירוע הזה. במקרה של תיעוד מדובר ב לשדה הזה יש אורך משתנה. כדי לבצע שילוב, כל מזהה שיסופק לאירוע הזה יופיע כאן. אם מבצע השילוב לא סיפק ערך לאירוע המתאים, השדה הזה יכיל את אותו הערך שמופיע בשדה במקרה של החזר כספי הפוך, החזרים כספיים בעקבות ביטול עסקה ואירועי החזר כספי הפוך, מדובר ב- האורך והפורמט של השדה הזה תלויים בשדה המקור של כל מזהה. עיינו במסמכי התיעוד של כל אחד משדות המקור לקבלת פרטים על הדרישות בנוגע לאורך ולמערכת תווים. חשוב לשים לב שהשדה הזה עשוי לפעמים להכיל מזהים שנוצרו על ידי Google, והאורך המקסימלי שלהם עשוי להיות שונה מזה של מזהים שנוצרו על ידי מבצע השילוב. |
eventCharge |
חובה: בקוד המטבע המוגדר בדף החשבון. אם הערך הוא שלילי, פירוש הדבר הוא ערך כספי שעובר מ-Google לשילוב התשלומים. אם זה חיובי, מדובר בכסף מכלי שילוב התשלומים של Google. לדוגמה, תיעוד עסקאות יהיה תמיד חיובי, ועסקאות של החזר כספי תמיד יהיו שליליות. במקרה של ביטול החזר כספי וביטול אירוע של החזר כספי בעקבות ביטול עסקה, תמיד יהיו חיוביים. אירועי חיוב חוזר יהיו תמיד שליליים. הערך הזה מוגדר במיקרו-מיקרו. |
eventFee |
חובה: בקוד המטבע המוגדר בדף החשבון. אם הערך הוא שלילי, פירוש הדבר הוא ערך כספי שעובר מ-Google לשילוב התשלומים. אם זה חיובי, מדובר בכסף מכלי שילוב התשלומים של Google. לדוגמה, אם הסכם קובע ש-Google תשלם 1% מה- הערך הזה מוגדר במיקרו-מיקרו. |
presentmentChargeAmount |
אופציונלי: סכום העסקה במטבע הנוכחי (הנקרא גם עסקה) לפני המרת החוץ. שדה זה תואם לאותה מוסכמת סימון כמו השדה הערך הזה מוגדר במיקרו-מיקרו. |
presentmentCurrencyCode |
אופציונלי: קוד מטבע בן 3 אותיות לפי תקן ISO 4217, שמציין את המטבע של ההצגה (עסקה). |
exchangeRate |
אופציונלי: שער החליפין שישמש בהמרת סכום המצגת לסכום היישוב (חשבונית). הערך הזה הוא במיקרו נקודות בסיס (1 נקודת בסיס = 0001 = .01%). כלומר, כדי לקבל את שער החליפין, יש לחלק את השדה הזה ב-10^10. |
nanoExchangeRate |
אופציונלי: שער החליפין המשמש להמרת סכום ההצגה לסכום הסדר (חשבונית), מבוטא בנקודות על בסיס ננו. הערך הזה הוא בנקודות בסיס ננו (1 נקודת בסיס = 0001 = 01%). כלומר, כדי לקבל את שער החליפין, יש לחלק את השדה הזה ב-10^13. השדה הזה וגם ExchangeRate יאוכלסו. הם שערי המרה שווים, המבוטאים ברמת דיוק שונה. בגרסאות עתידיות, שער החליפין יוסר לטובת nanoExchangeRate. |