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)

اختياري: البيانات اللازمة لإثبات صحة كلمة المرور لمرة واحدة (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" (بطاقة 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

رموز نتائج الالتقاط

عمليات التعداد
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

الحساب نشط، ولكن تم إبطال صلاحية علامة 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 انتهت صلاحية الإشعار الذي تم إرساله إلى المستخدم للحصول على دفعة تفويض متكررة.