Method: getDisputeInquiryReport

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

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

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

בקשה לדוגמה נראית כך:


{
  "requestHeader": {
    "protocolVersion": {
      "major": 1,
      "minor": 1,
      "revision": 0
    },
    "requestId": "HsKv5pvtQKTtz7rdcw1YqE",
    "requestTimestamp": "1519996751331"
  },
  "paymentIntegratorAccountId": "InvisiCashUSA",
  "paymentLookupCriteria": {
    "googleTransactionReferenceNumberCriteria": {
      "googleTransactionReferenceNumber": "714545417102363157911822",
      "authorizationCode": "111111"
    }
  },
  "existingGoogleClaimId": "138431383281",
  "requestOriginator": {
    "organizationId": "ISSUER_256",
    "organizationDescription": "Community Bank of Some City",
    "agentId": "982749"
  }
}

דוגמה לתשובה:


{
  "responseHeader": {
    "responseTimestamp": "1519996752221"
  },
  "result": "SUCCESS",
  "googleClaimId": "138431383281",
  "report": {
    "customerAccount": {
      "customerEmail": "example@gmail.com",
      "customerName" : "Example Customer"
    },
    "order": {
      "timestamp": "1517992525972",
      "orderId": "SOP.8976-1234-1234-123456..99",
      "currencyCode": "USD",
      "subTotalAmount": "206990000",
      "totalAmount": "212990000",
      "shippingAddress": {
        "name": "Example Customer",
        "addressLine": ["123 Main St"],
        "localityName": "Springfield",
        "administrativeAreaName": "CO",
        "postalCodeNumber": "80309",
        "countryCode": "US"
      },
      "taxes": [
        {
          "description": "Colorado Sales Tax",
          "amount": "6000000"
        }
      ],
      "items": [
        {
          "description": "Super cool gizmo",
          "merchant": "HTC",
          "googleProductName": "Google Store",
          "quantity": "2",
          "totalPrice": "198000000"
        },
        {
          "description": "Gizmo charger",
          "merchant": "HTC",
          "googleProductName": "Google Store",
          "quantity": "1",
          "totalPrice": "8990000"
        }
      ]
    },
    "payment": {
      "billingAddress" : {
        "name": "Example Customer",
        "addressLine": ["123 Main St"],
        "localityName": "Springfield",
        "administrativeAreaName": "CO",
        "postalCodeNumber": "80309",
        "countryCode": "US"
      },
      "amount": "100000000",
      "refunds": [
        {
          "amount": "9250000",
          "initiatedTimestamp": "1518811245384"
        }
      ],
      "cardDetails": {
        "authResult": "APPROVED"
      }
    }
  }
}

בקשת HTTP

POST https://vgw.googleapis.com/secure-serving/gsp/v1/getDisputeInquiryReport/:PIAID

גוף הבקשה

גוף הבקשה מכיל נתונים במבנה הבא:

ייצוג JSON 
{
  "requestHeader": {
    object (RequestHeader)
  },
  "paymentIntegratorAccountId": string,
  "paymentLookupCriteria": {
    object (PaymentLookupCriteria)
  },
  "existingGoogleClaimId": string,
  "requestOriginator": {
    object (RequestOriginator)
  }
}
שדות
requestHeader

object (RequestHeader)

חובה: כותרת משותפת לכל הבקשות.
paymentIntegratorAccountId

string

חובה: מזהה החשבון של מבצע השילוב של התשלומים שמזהה את מבצע הקריאה ואת המגבלות החוזיות המשויכות לאינטראקציה הזו.
paymentLookupCriteria

object (PaymentLookupCriteria)

חובה: קריטריונים המציינים את התשלום שאמור לבדוק את הנושא.
existingGoogleClaimId

string

אופציונלי: מחרוזת ש-Google יוצרת, שהוחזרה על-ידי קריאה קודמת אל getDisputeInquiryReport, שמזהה באופן ייחודי את התלונה הזו על ערעור של לקוח.

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

מזהה התלונה שמאוכלס כאן או שנוצר כאן יוחזר בשדה googleClaimId של התשובה.

לא חוקי לספק googleClaimId שלא הוחזר על ידי שיחה קודמת אל getDisputeInquiryReport. במקרה כזה, תוחזר 'בקשה לא תקינה' מסוג HTTP 400.
requestOriginator

object (RequestOriginator)

נדרש: מידע על הארגון או על קבוצת המשנה הארגונית שיצרה את הבקשה.

גוף התגובה

מטען ייעודי (payload) של תגובה ל-method getDisputeInquiryReport.

אם הפעולה בוצעה ללא שגיאות, גוף התגובה יכלול נתונים במבנה הבא:

ייצוג JSON 
{
  "responseHeader": {
    object (ResponseHeader)
  },
  "result": enum (GetDisputeInquiryReportResultCode),
  "googleClaimId": string,
  "report": {
    object (PurchaseReport)
  }
}
שדות
responseHeader

object (ResponseHeader)

חובה: כותרת נפוצה לכל התשובות.
result

enum (GetDisputeInquiryReportResultCode)

חובה: התוצאה של השיחה הזו.
googleClaimId

string

אופציונלי: מחרוזת ש-Google יוצרת ומזהה באופן ייחודי את המחלוקת של הלקוח. (מוצג אם ורק אם result הוא SUCCESS.)

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

object (PurchaseReport)

אופציונלי: פרטים שרלוונטיים לערעור על התשלום שצוין בבקשה. (מוצג אם ורק אם result הוא SUCCESS.)

RequestHeader

אובייקט כותרת שמוגדר בכל הבקשות שנשלחות לשרת.

ייצוג JSON 
{
  "requestId": string,
  "requestTimestamp": string,
  "userLocale": string,
  "protocolVersion": {
    object (Version)
  }
}
שדות
requestId

string

חובה: המזהה הייחודי של הבקשה.

זוהי מחרוזת באורך מקסימלי של 100 תווים והיא מכילה רק את התווים "a-z", "A-Z", "0-9", ":", "-" ו-"_".
requestTimestamp

string (int64 format)

חובה: חותמת הזמן של הבקשה הזו מיוצגת כאלפיות שנייה מאז תחילת התקופה של זמן מערכת. המקבל צריך לוודא שחותמת הזמן הזו היא ± 60 שניות של 'עכשיו'. חותמת הזמן של הבקשה אינה מזהה ביחס לניסיונות החוזרים.
userLocale
(deprecated)

string

הוצא משימוש: קוד שפה בן שתיים או שלוש אותיות לפי תקן ISO 639-2 Alpha 3, ואחריו מקף וקוד מדינה לפי תקן ISO 3166-1 Alpha-2. לדוגמה: 'pt', 'pt-BR', 'fil' או 'fil-PH'. אפשר להשתמש בה כדי לכתוב את השדות userMessage בתגובה.
protocolVersion

object (Version)

חובה: הגרסה של הבקשה.

גרסה

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

ייצוג JSON 
{
  "major": integer,
  "minor": integer,
  "revision": integer
}
שדות
major

integer

חובה: הגרסה הראשית. מצב זה מסומן עבור בקשות תאימות עם גרסאות שונות לא מובטח שהן יהיו תואמות.
minor

integer

חובה: הגרסה המשנית. מדובר בתיקוני באגים משמעותיים.
revision

integer

חובה: הגרסה המשנית. מדובר בתיקונים של באגים קטנים.

PaymentLookupCriteria

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

ייצוג JSON 
{

  // Union field criteria can be only one of the following:
  "arnCriteria": {
    object (ArnCriteria)
  },
  "googleTransactionReferenceNumberCriteria": {
    object (GoogleTransactionReferenceNumberCriteria)
  }
  // End of list of possible types for union field criteria.
}
שדות

שדה איחוד criteria.

הערך של criteria יכול להיות רק אחת מהאפשרויות הבאות:
arnCriteria

object (ArnCriteria)

אופציונלי: חיפוש מבוסס על מספר אסמכתה של רוכש (ARN).
googleTransactionReferenceNumberCriteria

object (GoogleTransactionReferenceNumberCriteria)

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

ArnCriteria

קריטריונים לחיפוש תשלום על סמך מספר אסמכתה של משלם (ARN).

ייצוג JSON 
{
  "acquirerReferenceNumber": string,
  "authorizationCode": string
}
שדות
acquirerReferenceNumber

string

חובה: מספר האסמכתה של הלקוח (ARN) שמזהה את התשלום באופן ייחודי. חייב להכיל 23 ספרות.
authorizationCode

string

נדרש: קוד ההרשאה לעסקה.

GoogleTransactionReferenceNumberCriteria

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

ייצוג JSON 
{
  "googleTransactionReferenceNumber": string,
  "authorizationCode": string
}
שדות
googleTransactionReferenceNumber

string

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

string

נדרש: קוד ההרשאה לעסקה.

RequestOriginator

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

ייצוג JSON 
{
  "organizationId": string,
  "organizationDescription": string,
  "agentId": string
}
שדות
organizationId

string

נדרש: מזהה של החברה, הארגון או הקבוצה הארגונית שמהם הגיעה הבקשה. חייב להיות ייחודי בpaymentIntegratorAccountId.
organizationDescription

string

חובה: שם קריא (לבני אדם) או תיאור של הארגון, וניתן להשתמש בו כדי להקל על התקשורת בין עובדי Google לבין המארגן של אותו ארגון.
agentId

string

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

GetDisputeInquiryReportResultCode

התוצאה של הפעלת ה-method getDisputeInquiryReport.

טיפוסים בני מנייה (enums)
UNKNOWN_RESULT אל תגדיר את ערך ברירת המחדל הזה אף פעם!
SUCCESS התשלום נמצא ונשלח דוח.
PAYMENT_NOT_FOUND התשלום המבוקש לא נמצא.
PAYMENT_TOO_OLD התשלום המבוקש נמצא, אבל לא סופק דוח בגלל גיל התשלום.
ORDER_CANNOT_BE_RETURNED התשלום המבוקש שייך להזמנה קיימת, אך לא ניתן להחזירו. הסיבות כוללות מקרים שבהם ההזמנה הוסרה לבקשת הבעלים.
NO_ADDITIONAL_DETAILS התשלום המבוקש נמצא, אבל אין דוח.

PurchaseReport

דוח שמכיל פרטים רלוונטיים לגבי הרכישה שמשויכת לתשלום המבוקש.

ייצוג JSON 
{
  "customerAccount": {
    object (CustomerAccount)
  },
  "order": {
    object (Order)
  },
  "payment": {
    object (Payment)
  }
}
שדות
customerAccount

object (CustomerAccount)

חובה: מידע בנוגע ללקוח ולחשבון שלו.
order

object (Order)

חובה: מידע בנוגע להזמנה שבה בוצע התשלום.
payment

object (Payment)

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

CustomerAccount

מידע על החשבון של הלקוח

ייצוג JSON 
{
  "customerEmail": string,
  "customerName": string
}
שדות
customerEmail

string

חובה: כתובת האימייל המשויכת לחשבון Google של הלקוח.
customerName

string

חובה: שם הלקוח.

הזמנה

מידע על ההזמנה.

ייצוג JSON 
{
  "timestamp": string,
  "orderId": string,
  "currencyCode": string,
  "subTotalAmount": string,
  "totalAmount": string,
  "shippingAddress": {
    object (Address)
  },
  "items": [
    {
      object (Item)
    }
  ],
  "taxes": [
    {
      object (Tax)
    }
  ]
}
שדות
timestamp

string (int64 format)

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

string

אופציונלי: מחרוזת המזהה את הסדר הזה באופן ייחודי. האפשרות הזו לא זמינה לכל סוגי ההזמנות.
currencyCode

string

אופציונלי: קוד מטבע בן 3 אותיות לפי תקן ISO 4217 לכל הסכומים בסדר הזה. האפשרות הזו לא זמינה לכל סוגי ההזמנות.
subTotalAmount

string (Int64Value format)

אופציונלי: הסכום הכולל של ההזמנה לפני מס, מיוצג כמיקרו של המטבע שצוין ב-order.currencyCode. הערך הזה שווה ל-SUM(items.totalPrice). האפשרות הזו לא זמינה לכל סוגי ההזמנות.
totalAmount

string (Int64Value format)

אופציונלי: הסכום הכולל של ההזמנה הזו, כולל מס, מיוצג כמיקרו של המטבע שצוין ב-order.currencyCode. הערך הזה שווה ל-subTotalAmount + SUM(taxes.amount). האפשרות הזו לא זמינה לכל סוגי ההזמנות.
shippingAddress

object (Address)

אופציונלי: כתובת למשלוח של פריטים פיזיים בהזמנה הזו.
items[]

object (Item)

חובה: רשימת פריטים שהיו חלק מהזמנה זו.
taxes[]

object (Tax)

חובה: רשימת פריטים שהיו חלק מהזמנה זו. יכול להיות שהרשימה הזו ריקה.

כתובת

מבנה שמכיל מידע על כתובת.

ייצוג JSON 
{
  "name": string,
  "addressLine": [
    string
  ],
  "localityName": string,
  "administrativeAreaName": string,
  "postalCodeNumber": string,
  "countryCode": string
}
שדות
name

string

אופציונלי: השם המלא של הלקוח.
addressLine[]

string

אופציונלי: שדה זה כולל טקסט כתובת לא מובנה.
localityName

string

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

דוגמאות: עיר בארה"ב, קומוניית IT, עיר דואר בבריטניה.
administrativeAreaName

string

אופציונלי: חלוקת משנה מנהלית ברמה העליונה של המדינה הזו. דוגמאות: מדינה בארה"ב, אזור IT, מחוז CN, מחוז יפן."
postalCodeNumber

string

אופציונלי: למרות השם, בדרך כלל הערכים של postCodeNumber הם אלפאנומריים. דוגמאות: 94043, SW1W, SW1W 9TQ.
countryCode

string

אופציונלי: קוד המדינה של כתובת הלקוח, הצפוי להיות ISO-3166-1 Alpha-2.

פריט

מידע על הפריט שבהזמנה.

ייצוג JSON 
{
  "description": string,
  "merchant": string,
  "quantity": string,
  "totalPrice": string,
  "googleProductName": string
}
שדות
description

string

אופציונלי: תיאור של הפריט שנרכש. האפשרות הזו לא זמינה לכל סוגי ההזמנות.
merchant

string

חובה: המוכר, האומן או היוצר של הפריט.
quantity

string (Int64Value format)

אופציונלי: הכמות שהוזמנה מהפריט.

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

string (Int64Value format)

אופציונלי: המחיר הכולל של הפריט, מיוצג כמיקרו של המטבע שצוין ב-order.currencyCode. אם הערך quantity מאוכלס, הערך הזה משקף את המחיר הכולל של הכמות כולה. האפשרות הזו לא זמינה לכל סוגי ההזמנות.
googleProductName

string

חובה: שם שירות המוצר של Google עבור הפריט.

מס

מידע על מס שחל על הזמנה זו.

ייצוג JSON 
{
  "description": string,
  "amount": string
}
שדות
description

string

חובה: תיאור של המס.
amount

string (Int64Value format)

חובה: סכום המס, מיוצג כמיקרו של המטבע שצוין ב-order.currencyCode.

תשלום

מידע על התשלום

ייצוג JSON 
{
  "billingAddress": {
    object (Address)
  },
  "amount": string,
  "refunds": [
    {
      object (Refund)
    }
  ],

  // Union field fopDetails can be only one of the following:
  "cardDetails": {
    object (PaymentCardDetails)
  }
  // End of list of possible types for union field fopDetails.
}
שדות
billingAddress

object (Address)

חובה: כתובת לחיוב שמשויכת לתשלום הזה.
amount

string (Int64Value format)

חובה: סכום התשלום הזה, מיוצג כמיקרו של המטבע שצוין ב-order.currencyCode. הערה: ייתכן שהערך הזה לא יהיה תואם ל-order.totalAmount אם ההזמנה שולמה באמצעות מספר תשלומים.
refunds[]

object (Refund)

חובה: רשימת ההחזרים הכספיים שבוצעו לתשלום הזה. יכול להיות שהרשימה הזו ריקה.

שדה איחוד fopDetails.

הערך של fopDetails יכול להיות רק אחת מהאפשרויות הבאות:
cardDetails

object (PaymentCardDetails)

אופציונלי: פרטי תשלום ספציפיים לחשבונות של כרטיסי אשראי וכרטיסי חיוב מיידי.

החזר כספי

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

ייצוג JSON 
{
  "amount": string,
  "initiatedTimestamp": string
}
שדות
amount

string (Int64Value format)

חובה: הסכום שהוחזר, מספר חיובי של מיקרו מהמטבע שצוין ב-order.currencyCode.
initiatedTimestamp

string (int64 format)

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

PaymentCardDetails

פרטי תשלום ספציפיים לכרטיסי אשראי וכרטיסי חיוב מיידי.

ייצוג JSON 
{
  "authResult": enum (AuthResult)
}
שדות
authResult

enum (AuthResult)

חובה: תוצאה של אימות תשלום.

AuthResult

תוצאות של אימות תשלום.

טיפוסים בני מנייה (enums)
UNKNOWN_RESULT אל תגדיר את ערך ברירת המחדל הזה אף פעם!
APPROVED האימות אושר.
DENIED האימות נדחה.
NOT_ATTEMPTED לא בוצע ניסיון אימות.