Method: capture

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

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

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


{
  "requestHeader": {
    "protocolVersion": {
      "major": 1,
      "minor": 0,
      "revision": 0
    },
    "requestId": "bWVyY2hhbnQgdHJhbnNhY3Rpb24gaWQ",
    "requestTimestamp": "1502220196077"
  },
  "paymentIntegratorAccountId": "InvisiCashUSA_USD",
  "googlePaymentToken": "ZXhhbXBsZSB1bmlxdWUgcGF5bWVudCB0b2tlbiB2YWx1ZQ",
  "transactionDescription": "Google - Music",
  "currencyCode": "INR",
  "amount": "728000000",
  "captureContext": {}
}

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


{
  "responseHeader": {
    "responseTimestamp": "1481900013178"
  },
  "result": "SUCCESS",
  "paymentIntegratorTransactionId": "aW50ZWdyYXRvciB0cmFuc2FjdGlvbiBpZA"
}

בקשת HTTP

POST https://www.integratorhost.example.com/v1/capture

גוף הבקשה

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

ייצוג JSON 
{
  "requestHeader": {
    object (RequestHeader)
  },
  "paymentIntegratorAccountId": string,
  "transactionDescription": string,
  "currencyCode": string,
  "amount": string,
  "captureContext": {
    object (CaptureContext)
  },

  // Union field fopDetails can be only one of the following:
  "googlePaymentToken": string,
  "mandateDetails": {
    object (MandateDetails)
  },
  "mandateWithNotificationDetails": {
    object (MandateWithNotificationDetails)
  }
  // End of list of possible types for union field fopDetails.

  // Union field account_verification can be only one of the following:
  "authenticationRequestId": string,
  "otpVerification": {
    object (OtpVerification)
  }
  // End of list of possible types for union field account_verification.
}
שדות
requestHeader

object (RequestHeader)

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

string

חובה: זהו מזהה החשבון של הכלי לשילוב תשלומים שמזהה מגבלות חוזיות סביב העסקה הזו.
transactionDescription

string

חובה: זהו התיאור של העסקה שניתן להציג בדף החשבון של הלקוח. מותאם לשוק המקומי של המשתמש שנמצא ב-requestHeader. אפשר לשנות את הפורמט הזה ללא הודעה מראש ולא לנתח אותו אף פעם.
currencyCode

string

חובה: קוד מטבע בן 3 אותיות לפי תקן ISO 4217
amount

string (Int64Value format)

חובה: סכום הרכישה, במיקרו של יחידת המטבע.
captureContext

object (CaptureContext)

חובה: הקשר לגבי הצילום הזה.
שדה איחוד fopDetails. חובה: פרטי אמצעי תשלום עבור עסקת הצילום הזו. הערך של fopDetails יכול להיות רק אחת מהאפשרויות הבאות:
googlePaymentToken

string

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

object (MandateDetails)

פרטי תשלום ספציפיים לייפוי כוח.
mandateWithNotificationDetails

object (MandateWithNotificationDetails)

פרטי תשלום ספציפיים לייפוי כוח, במקרים שבהם נדרש upcomingTransactionNotification.

שדה איחוד account_verification.

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

string

אופציונלי: requestId של בקשת האימות המשויכת. אם הוא לא נמצא, לא ניתן לקשור אימות להקלטה הזו.

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

object (OtpVerification)

אופציונלי: הנתונים הנדרשים לאימות OTP שנוצר מ-sendOtp. השדה הזה מוצג רק אם המשתמש עבר את הנתיב sendOtp.

גוף התגובה

אובייקט תגובה לשיטת ההקלטה.

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

ייצוג JSON 
{
  "responseHeader": {
    object (ResponseHeader)
  },
  "paymentIntegratorTransactionId": string,
  "userMessage": string,
  "result": enum (CaptureResultCode),
  "rawResult": {
    object (RawResult)
  },
  "transactionLimit": string,
  "currentBalance": string
}
שדות
responseHeader

object (ResponseHeader)

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

string

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

לשם נוחות, המזהה הזה נכלל בפרטי ההעברה
userMessage
(deprecated)

string

הוצא משימוש: תיאור של התוצאה שיוצג למשתמש אם התוצאה אינה SUCCESS.
result

enum (CaptureResultCode)

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

object (RawResult)

אופציונלי: תוצאה גולמית של הצילום הזה. הנתונים משמשים לקבלת מידע על מנגנון הסיכונים וניתוח הסיכונים של Google. במצבים של מיפוי קוד סירוב, לפעמים נתונים אובדים נתונים. מבצע השילוב יכול לבחור לתת ל-Google קוד גולמי. לדוגמה, שער כרטיס אשראי (המבצע השילוב) עשוי להשתמש בשדה הזה כדי להעביר ל-Google את קוד הדחייה המדויק שהתקבל מרשת VISA. במקרה כזה, הערך של scope יהיה "Visa" ו-rawCode יהיה הערך שהחזירה רשת ה-VISA.

הערך הזה הוא חובה אם הערך של result אינו SUCCESS.
transactionLimit

string (Int64Value format)

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

המגבלה הזו צריכה להיות המגבלה ביחס לcurrencyCode שצוינה בבקשה.
currentBalance

string (Int64Value format)

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

הערך הזה חייב להיות באותו מטבע כמו currencyCode שצוין בבקשה.

MandateDetails

פרטים לגבי ייפוי הכוח שממנו יש לאסוף.

ייצוג JSON 
{
  "mandateId": string
}
שדות
mandateId

string

חובה: המזהה של ייפוי הכוח שנוצר על ידי Google ונשלח במהלך השיחה עם createMandate.

MandateWithNotificationDetails

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

ייצוג JSON 
{
  "mandateId": string,
  "upcomingTransactionNotificationId": string
}
שדות
mandateId

string

חובה: המזהה של ייפוי הכוח שנוצר על ידי Google ונשלח במהלך השיחה עם createMandate.
upcomingTransactionNotificationId

string

חובה: requestId מתוך השיחה עם upcomingTransactionNotification, שבוצעה כדי להודיע מראש על העסקה הזו.

CaptureContext

האובייקט הזה מספק הקשר לגבי האופן שבו התקבלה הבקשה לצילום.

ייצוג JSON 
{
  "userIpAddress": string
}
שדות
userIpAddress

string

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

CaptureResultCode

קודים של תוצאות להקלטה.

טיפוסים בני מנייה (enums)
UNKNOWN_RESULT אל תגדיר את ערך ברירת המחדל הזה אף פעם!
SUCCESS המשלוח הושלם בהצלחה.
CHARGE_EXCEEDS_TRANSACTION_LIMIT ערך amount של בקשת הלכידה הזו חורג מהמגבלה לעסקה. אם משתמשים בקוד הזה, יש לאכלס את השדה transactionLimit לצורך העברת הודעות למשתמשים.
CHARGE_EXCEEDS_DAILY_LIMIT לא ניתן להשתמש בחשבון הזה לביצוע רכישות כרגע כי הוא חרג מהמגבלות היומיות שלו.
CHARGE_EXCEEDS_MONTHLY_LIMIT לא ניתן להשתמש בחשבון הזה לביצוע רכישות כרגע כי הוא חרג מהמגבלות החודשיות שלו.
CHARGE_UNDER_LIMIT amount של בקשת ההקלטה הזו לא עומד בסכום העסקה המינימלי.
INSUFFICIENT_FUNDS אין בחשבון הזה מספיק כסף כדי להבטיח את לכידה.
ACCOUNT_DOES_NOT_SUPPORT_CURRENCY חשבון זה אינו תומך במטבע המבוקש.
ACCOUNT_CLOSED

חשבון המשתמש אצל מבצע השילוב נסגר.

החזרת הערך הזה תגרום לסגירה של הכלי של המשתמש ב-Google. המשתמש ייאלץ להוסיף אמצעי חדש על ידי חזרה על תהליך השיוך.
ACCOUNT_CLOSED_ACCOUNT_TAKEN_OVER

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

החזרת הערך הזה תגרום לסגירה של הכלי של המשתמש ב-Google. המשתמש ייאלץ להוסיף אמצעי חדש על ידי חזרה על תהליך השיוך.
ACCOUNT_ON_HOLD החשבון מושהה.
ACCOUNT_CLOSED_FRAUD

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

החזרת הערך הזה תגרום לסגירה של הכלי של המשתמש ב-Google. המשתמש ייאלץ להוסיף אמצעי חדש על ידי חזרה על תהליך השיוך.
GOOGLE_PAYMENT_TOKEN_INVALIDATED_BY_USER

החשבון פעיל, אבל ה-GPT בוטל על ידי המשתמש בצד של מבצע השילוב.

החזרת הערך הזה תגרום לסגירה של הכלי של המשתמש ב-Google. המשתמש ייאלץ להוסיף אמצעי חדש על ידי חזרה על תהליך השיוך.
TOKEN_REFRESH_REQUIRED כדי להחזיר את הנתונים, המשתמש יצטרך לעבור תהליך רענון.
OTP_NOT_MATCHED הסיסמה החד-פעמית (OTP) לא תאמה למה השילוב שלח.
OTP_ALREADY_USED כבר נעשה שימוש ב-OTP.
RISK_DECLINED

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

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

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

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

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