Method: capture

Initiates money movement between a customer's account held with Google and the payment processor. The combination of requestId within the header and paymentIntegratorAccountId is the idempotency key and uniquely identifies this transaction. All mutations on this transaction (refunds) populate the requestId value in the captureRequestId field.

If the endpoint encounters an error while processing the request, the response body from this endpoint should be of type ErrorResponse.

An example request looks like:


{
  "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": {}
}

An example response looks like:


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

HTTP request

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

Request body

The request body contains data with the following structure:

JSON representation 
{
  "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.
}
Fields
requestHeader

object (RequestHeader)

REQUIRED: Common header for all requests.
paymentIntegratorAccountId

string

REQUIRED: This is the payment integrator account identifier that identifies contractual constraints around this transaction.
transactionDescription

string

REQUIRED: This is the description of the transaction that can be put on the customer's statement. Localized to the userLocale found in the requestHeader. This format can be changed without notice and must never be parsed.
currencyCode

string

REQUIRED: ISO 4217 3-letter currency code
amount

string (Int64Value format)

REQUIRED: The amount of the purchase, in micros of the currency unit.
captureContext

object (CaptureContext)

REQUIRED: Context about this capture.
Union field fopDetails. REQUIRED: FOP Details for this Capture transaction. fopDetails can be only one of the following:
googlePaymentToken

string

Token that both companies will use to identify the account for purchases between each other.
mandateDetails

object (MandateDetails)

Payment details specific to mandates.
mandateWithNotificationDetails

object (MandateWithNotificationDetails)

Payment details specific to mandates, where an upcomingTransactionNotification is required.

Union field account_verification.

account_verification can be only one of the following:
authenticationRequestId

string

OPTIONAL: requestId of the associated authentication request. If this is not present then no authentication can be tied to this capture.

If this is present then the user was authenticated immediately preceding this call, or was authenticated when an automated payment schedule was set up.
otpVerification

object (OtpVerification)

OPTIONAL: Data necessary to verify an OTP generated from sendOtp. This is only present if the user went through the sendOtp path.

Response body

Response object for the capture method.

If successful, the response body contains data with the following structure:

JSON representation 
{
  "responseHeader": {
    object (ResponseHeader)
  },
  "paymentIntegratorTransactionId": string,
  "userMessage": string,
  "result": enum (CaptureResultCode),
  "rawResult": {
    object (RawResult)
  },
  "transactionLimit": string,
  "currentBalance": string
}
Fields
responseHeader

object (ResponseHeader)

REQUIRED: Common header for all responses.
paymentIntegratorTransactionId

string

OPTIONAL: This identifier is specific to the integrator and is generated by the integrator. This is the identifier that the integrator knows this transaction by.

For convenience, this identifier is included with in the remittance details
userMessage
(deprecated)

string

DEPRECATED: A description of the result to be displayed to the user if the result is not SUCCESS.
result

enum (CaptureResultCode)

REQUIRED: Result of this capture.
rawResult

object (RawResult)

OPTIONAL: Raw result of this capture. Used to help inform Google's risk engine and analytics. In decline code–mapping situations, data is sometimes lost. The integrator can choose to give Google a raw code. For example, a credit card gateway (the integrator) may use this field to communicate to Google the exact decline code that was received from the VISA network. In that case, the scope would be "visa" and the rawCode would be whatever the VISA network returned.

This value is required if the result is not SUCCESS.
transactionLimit

string (Int64Value format)

OPTIONAL: If Result is CHARGE_EXCEEDS_TRANSACTION_LIMIT, then this is the maximum amount the user could spend on a transaction (in micros). This is used for structured, user facing messaging and decline rate analysis.

This must be a limit relative to the currencyCode on the request.
currentBalance

string (Int64Value format)

OPTIONAL: If Result is INSUFFICIENT_FUNDS, then this is the current available balance in the user's account (in micros). This is used for structured, user facing messaging.

This value must be in the same currency as the currencyCode on the request.

MandateDetails

Details about the mandate to capture from.

JSON representation 
{
  "mandateId": string
}
Fields
mandateId

string

REQUIRED: The Google generated mandate ID that was sent during the createMandate call.

MandateWithNotificationDetails

Details about the mandate to capture from, along with required notifications details.

JSON representation 
{
  "mandateId": string,
  "upcomingTransactionNotificationId": string
}
Fields
mandateId

string

REQUIRED: The Google generated mandate ID that was sent during the createMandate call.
upcomingTransactionNotificationId

string

REQUIRED: The requestId of the upcomingTransactionNotification call, that was made to pre notify about this transaction.

CaptureContext

This object provides context about how the capture was requested.

JSON representation 
{
  "userIpAddress": string
}
Fields
userIpAddress

string

OPTIONAL: This is the IP address of the user's device if the purchase was made by a user in session. If the user was not in session this will empty. If the particular contract doesn't stipulate the need for this field it will always be empty.

CaptureResultCode

Result codes for capture.

Enums
UNKNOWN_RESULT Do not ever set this default value!
SUCCESS Successful capture, deliver the goods.
CHARGE_EXCEEDS_TRANSACTION_LIMIT This capture request's amount exceeds per-transaction limit. If this code is used populate the transactionLimit field for user messaging purposes.
CHARGE_EXCEEDS_DAILY_LIMIT This account cannot be used for purchases right now as it has exceeded its daily limits.
CHARGE_EXCEEDS_MONTHLY_LIMIT This account cannot be used for purchases right now as it has exceeded its monthly limits.
CHARGE_UNDER_LIMIT This capture request's amount does not meet the minimum transaction amount.
INSUFFICIENT_FUNDS This account does not have sufficient funds to guarantee this capture.
ACCOUNT_DOES_NOT_SUPPORT_CURRENCY This account does not support the requested currency.
ACCOUNT_CLOSED

The user's account held with the integrator has been closed.

Returning this value will cause the user's instrument to be closed with Google. The user will be forced to add a new instrument by going through the association flow again.
ACCOUNT_CLOSED_ACCOUNT_TAKEN_OVER

The user's account with the integrator has been closed, suspected account take over.

Returning this value will cause the user's instrument to be closed with Google. The user will be forced to add a new instrument by going through the association flow again.
ACCOUNT_ON_HOLD The account is on hold.
ACCOUNT_CLOSED_FRAUD

The user's account held with the integrator has been closed because of fraud.

Returning this value will cause the user's instrument to be closed with Google. The user will be forced to add a new instrument by going through the association flow again.
GOOGLE_PAYMENT_TOKEN_INVALIDATED_BY_USER

The account is active, but the GPT has been invalidated by the user on the integrator's side.

Returning this value will cause the user's instrument to be closed with Google. The user will be forced to add a new instrument by going through the association flow again.
TOKEN_REFRESH_REQUIRED Returning this requires the user to go through a refresh flow.
OTP_NOT_MATCHED OTP did not match what the integrator sent.
OTP_ALREADY_USED OTP was already used.
RISK_DECLINED

The transaction was declined due to a risk check on the integrator's side.

This is a permanent failure for this payment, but does not cause the user's instrument to be closed at Google.
NO_GOOD_FUNDING_SOURCE_AVAILABLE The user does not have any working funding source configured on their account that is able to pay for the transaction.
FUNDING_SOURCE_UNAVAILABLE

The underlying issuer or source of funds is unavailable and retrying this exist payment will not succeed if retried.

Google will retry payments that when a 4xx or 5xx response code is returned by an partner. Because of this, partners should normally return one of those response codes if a retry of this same payment may succeed when the underlying source of funds is again available. But, if there are technical reasons where Google retrying the payment will continue to fail, the partner can return "FUNDING_SOURCE_UNAVAILABLE" as a way to tell Google that it should not retry this same payment.

Note: Google still may retry this payment, but just with a different requestId, but this payment request will be marked as Declined.
MANDATE_NOT_ACTIVE The mandate used for this capture is no longer active. This return value will cause the user's mandate instrument to be closed with Google.
UPCOMING_TRANSACTION_NOTIFICATION_EXPIRED The notification that was sent to the user for a recurring mandate payment was expired.