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. مطلوب: تفاصيل طريقة الدفع لمعاملة Capture هذه. يمكن أن يكون fopDetails واحدًا فقط مما يلي:
googlePaymentToken

string

رمز مميّز ستستخدمه الشركتان للتعرّف على حساب عمليات الشراء بينهما.
mandateDetails

object (MandateDetails)

تفاصيل الدفع الخاصة بالتفويضات.
mandateWithNotificationDetails

object (MandateWithNotificationDetails)

تفاصيل الدفع الخاصة بالتفويضات، حيث يجب توفير upcomingTransactionNotification.

حقل الاتحاد account_verification.

يمكن أن يكون account_verification واحدًا فقط مما يلي:
authenticationRequestId

string

اختياري: requestId لطلب المصادقة المرتبط. فإذا لم يكن هذا الملف موجودًا، فلا يمكن ربط أي مصادقة بهذا الالتقاط.

في حال توفّر هذه السمة، هذا يعني أنّه تمّت مصادقة المستخدم قبل هذه المكالمة مباشرةً، أو تمت مصادقته عند إعداد جدول دفع مبرمَج.
otpVerification

object (OtpVerification)

اختياري: البيانات اللازمة للتحقّق من كلمة المرور لمرة واحدة التي تم إنشاؤها من 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)

OPTIONAL: النتيجة الأولية لهذا الالتقاط. تُستخدَم هذه السمة للمساعدة في إعلام محرّك بحث Google بشأن المخاطر والتحليلات. في حالات ربط الرموز البرمجية والرفض، يتم فقدان البيانات أحيانًا. يمكن أن تختار شركة الدمج منح Google رمزًا أوليًا. على سبيل المثال، يمكن لبوابة بطاقة الائتمان (شركة الدمج) استخدام هذا الحقل لإبلاغ Google برمز الرفض الذي تم استلامه من شبكة VISA. في هذه الحالة، ستكون القيمة scope هي "فيزا" وكانت بطاقة 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

رموز النتائج للتسجيل.

عمليات التعداد
UNKNOWN_RESULT لا تضبط هذه القيمة التلقائية على الإطلاق.
SUCCESS الالتقاط الناجح، وتسليم البضائع.
CHARGE_EXCEEDS_TRANSACTION_LIMIT يتجاوز amount لطلب الالتقاط هذا الحد المسموح به لكل معاملة. في حال استخدام هذا الرمز، يمكنك ملء الحقل transactionlimited لأغراض مراسلة المستخدمين.
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

الحساب نشط، ولكن تم إلغاء صلاحية علامة "علامة ناشر Google" من قِبل المستخدم من جانب جهة الدمج.

سيؤدي عرض هذه القيمة إلى إغلاق وسيلة المستخدم مع Google. سيضطر المستخدم إلى إضافة أداة جديدة من خلال إجراء عملية الربط مرة أخرى.
TOKEN_REFRESH_REQUIRED ويتطلب عرض هذا من المستخدم أن يمر بتدفق إعادة التحميل.
OTP_NOT_MATCHED لم تتطابق كلمة المرور لمرة واحدة مع ما أرسله مسؤول الدمج.
OTP_ALREADY_USED سبق أن تم استخدام كلمة المرور لمرة واحدة (OTP).
RISK_DECLINED

تم رفض المعاملة بسبب فحص للمخاطر من جانب جهة الدمج.

يتعذّر إتمام عملية الدفع هذه بشكل دائم، لكنّه لا يتسبب في إغلاق وسيلة المستخدم في Google.
NO_GOOD_FUNDING_SOURCE_AVAILABLE لا يمتلك المستخدم أي مصدر تمويل قيد التشغيل تم إعداده في حسابه والذي يمكنه الدفع مقابل المعاملة.
FUNDING_SOURCE_UNAVAILABLE

جهة إصدار الأموال الأساسية أو مصدرها غير متاح، ولن تنجح عملية الدفع الحالية إذا تمّت إعادة المحاولة.

ستعيد Google محاولة الدفع عندما يعرض أحد الشركاء رمز الاستجابة 4xx أو 5xx. نتيجةً لذلك، على الشركاء عادةً إرجاع أحد رموز الاستجابة هذه إذا نجحت إعادة محاولة إرسال الدفعة نفسها عند توفّر مصدر الأموال الأساسي من جديد. ولكن إذا كانت هناك أسباب فنية تستمر في تعذّر إعادة محاولة الدفع من قِبل Google، يمكن للشريك إرجاع "FUNDING_SOURCE_UNAREA" كوسيلة لإعلام Google بأنّه يجب عدم إعادة محاولة عملية الدفع نفسها.

ملاحظة: بإمكان Google إعادة محاولة إجراء عملية الدفع هذه ولكن باستخدام رقم تعريف طلب مختلف، ولكن سيتم وضع علامة "مرفوض" على طلب الدفع هذا.
MANDATE_NOT_ACTIVE لم يعُد التفويض المستخدَم لعملية الالتقاط هذه نشطًا. ستؤدي هذه القيمة المعروضة إلى إغلاق أداة التفويض الخاصة بالمستخدم مع Google.
UPCOMING_TRANSACTION_NOTIFICATION_EXPIRED انتهت صلاحية الإشعار الذي تم إرساله إلى المستخدم مقابل دفعة تفويض متكرّرة.