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

חובה: התיאור של העסקה שאפשר להוסיף לדף החשבון של הלקוח. הותאם ל-userLocale שנמצא ב-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

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

טיפוסים בני מנייה (enum)
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 פג תוקף ההתראה שנשלחה למשתמש בנוגע לתשלום קבוע של ייפוי כוח.