Method: payment-integrator-authenticated-card-fop-api.capture

Captures funds from a user's card.

This call synchronously attempts to capture funds from a user's card. The response to this message will return the result of that attempt. The combination of requestId within the header and paymentIntegratorAccountId is the idempotency key and uniquely identifies this transaction. All mutations on this transaction populate the requestId value in their 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 of a standard payment request looks like:


{
  "requestHeader": {
    "protocolVersion": {
      "major": 1
    },
    "requestId": "G112YZH4XPDV88J",
    "requestTimestamp": {
      "epochMillis": "1481907920000"
    },
    "paymentIntegratorAccountId": "SpeedyPaymentsIndia_INR"
  },
  "accountDetails": {
    "card": {
      "accountNumber": "4123456789101112",
      "nameOnCard": "Example Customer",
      "expiryMonth": "01",
      "expiryYear": "20",
      "cvn": "123"
    }
  },
  "amount": {
    "amountMicros": "728000000",
    "currencyCode": "INR"
  },
  "transactionDescription": "Movie ACB",
  "merchantCategoryCode": "5815",
  "addressVerificationData": {
    "addressLine": ["2 Inner Ring Road"],
    "localityName": "Bangalore",
    "administrativeAreaName": "Karnataka",
    "postalCodeNumber": "560071",
    "countryCode": "IN"
  },
  "authenticationNotAttempted" : {}
}

An example of a standard payment response looks like:


{
  "responseHeader": {
    "responseTimestamp": {
      "epochMillis": 1481907920760
    }
  },
  "paymentIntegratorCaptureId": "36be1a5d-ff21-455d-8dba-e3c4306e193e",
  "cardNetworkResult": {
    "rawResult": {
      "scope": "VISA",
      "rawCode": "00"
    },
    "authorizationCode": "123456"
  },
  "addressVerificationResult": {
    "result": {
      "rawAvsResult": "M",
      "addressLine": "MATCH",
      "localityName": "MATCH",
      "administrativeAreaName": "MATCH",
      "postalCodeNumber": "MATCH",
      "countryCode": "MATCH",
      "nameOnCard": "MATCH"
    }
  },
  "cvnResult": "MATCH",
  "result": "SUCCESS",
  "cardMetadata": {
    "issuerName": "exampleissuer",
    "issuingCountryCode": "IN",
    "networks": ["VISA"],
    "cardType": "CREDIT_CARD"
  }
}

An example of a recurring payment with mandate creation looks like:


{
  "requestHeader": {
    "protocolVersion": {
      "major": 1
    },
    "requestId": "G112YZH4XPDV88J",
    "requestTimestamp": {
      "epochMillis": "1481907920000"
    },
    "paymentIntegratorAccountId": "SpeedyPaymentsIndia_INR"
  },
  "authenticateRequestId": "G13478DFHKE123HG74",
  "amount": {
    "amountMicros": "728000000",
    "currencyCode": "INR"
  },
  "transactionDescription": "Movie ACB",
  "merchantCategoryCode": "5815",
  "addressVerificationData": {
    "addressLine": ["2 Inner Ring Road"],
    "localityName": "Bangalore",
    "administrativeAreaName": "Karnataka",
    "postalCodeNumber": "560071",
    "countryCode": "IN"
  },
  "authenticationWasSuccessful" : {
    "paymentIntegratorAuthenticationId": "6e77bd35-3fca-4b03-9cbb-6586c31def72",
    "recurringPaymentDetails": {
      "customerReferenceId": "customer57",
      "recurringPaymentReferenceId": "subscription201",
      "recurringPaymentDescription": "Google TV",
      "startDate": {
        "year": 2021,
        "month": 1,
        "day": 21
      },
      "endDate": {
        "year": 2099,
        "month": 12,
        "day": 31
      },
      "frequency": "MONTHLY",
      "fixedAmount": {
        "amountMicros": "728000000",
        "currencyCode": "INR"
      }
    }
  }
}

An example of a recurring payment with mandate creation response looks like:


{
  "responseHeader": {
    "responseTimestamp": {
      "epochMillis": 1481907920760
    }
  },
  "paymentIntegratorCaptureId": "36be1a5d-ff21-455d-8dba-e3c4306e193e",
  "cardNetworkResult": {
    "rawResult": {
      "scope": "VISA",
      "rawCode": "00"
    },
    "authorizationCode": "123456"
  },
  "addressVerificationResult": {
    "result": {
      "rawAvsResult": "M",
      "addressLine": "MATCH",
      "localityName": "MATCH",
      "administrativeAreaName": "MATCH",
      "postalCodeNumber": "MATCH",
      "countryCode": "MATCH",
      "nameOnCard": "MATCH"
    }
  },
  "cvnResult": "MATCH",
  "result": "SUCCESS",
  "cardMetadata": {
    "issuerName": "exampleissuer",
    "issuingCountryCode": "IN",
    "networks": ["VISA"],
    "cardType": "CREDIT_CARD"
  },
  "recurringMandateDetails": {
    "mandateId": "MA061B00045154",
    "mandateStatus": "ACTIVE",
    "mandateCreationDetails" : {
      "integratorPaymentToken" : {}
    }
  }
}

An example of a recurring payment request using a mandate looks like:


{
  "requestHeader": {
    "protocolVersion": {
      "major": 1
    },
    "requestId": "G112YZH4XPDV88J",
    "requestTimestamp": {
      "epochMillis": "1481907920000"
    },
    "paymentIntegratorAccountId": "SpeedyPaymentsIndia_INR"
  },
  "recurringPaymentMandate": {
    "mandateId": "MA061B00045154",
    "recurringPaymentReferenceId": "subscription201",
    "paymentIntegratorNotificationId": "invoiceid1234"
  },
  "amount": {
    "amountMicros": "728000000",
    "currencyCode": "INR"
  },
  "transactionDescription": "N/A",
  "merchantCategoryCode": "N/A",
  "authenticationNotAttempted" : {}
}

An example of a recurring payment response using a mandate looks like:


{
  "responseHeader": {
    "responseTimestamp": {
      "epochMillis": 1481907920760
    }
  },
  "paymentIntegratorCaptureId": "36be1a5d-ff21-455d-8dba-e3c4306e193e",
  "cardNetworkResult": {
    "rawResult": {
      "scope": "VISA",
      "rawCode": "00"
    },
    "authorizationCode": "123456"
  },
  "addressVerificationResult": {
    "notSent": {
      "support": "SUPPORTED"
    }
  },
  "cvnResult": "NOT_SENT_SUPPORTED",
  "result": "SUCCESS",
  "cardMetadata": {
    "issuerName": "exampleissuer",
    "issuingCountryCode": "IN",
    "networks": ["VISA"],
    "cardType": "CREDIT_CARD"
  }
}

HTTP request

POST https://www.integratorhost.example.com/v1/payment-integrator-authenticated-card-fop-api/capture

Request body

The request body contains data with the following structure:

JSON representation 
{
  "requestHeader": {
    object (RequestHeader)
  },
  "amount": {
    object (Amount)
  },
  "transactionDescription": string,
  "merchantCategoryCode": string,
  "addressVerificationData": {
    object (AddressVerificationData)
  },

  // Union field account_details_source can be only one of the following:
  "accountDetails": {
    object (AccountDetails)
  },
  "authenticateRequestId": string,
  "recurringPaymentMandate": {
    object (RecurringPaymentMandate)
  },
  "inPlaceTokenizedCardPayment": {
    object (InPlaceTokenizedCardPayment)
  }
  // End of list of possible types for union field account_details_source.

  // Union field authentication_attempted can be only one of the following:
  "authenticationNotAttempted": {
    object (Empty)
  },
  "authenticationWasSuccessful": {
    object (AuthenticationDetails)
  },
  "authenticationWasAttempted": {
    object (AuthenticationDetails)
  }
  // End of list of possible types for union field authentication_attempted.
}
Fields
requestHeader

object (RequestHeader)

REQUIRED: Common header for all requests.
amount

object (Amount)

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

string

REQUIRED: This is the description of the transaction that can be put on the customer's statement. The format can be changed without notice and therefore this value must never be parsed.

This field will always be sent, however it is understood that not all issuers or networks support it. In those cases it does not have to be used. This field is classified as SPII because it can contain sensitive information, for example one-time password.
merchantCategoryCode

string

REQUIRED: This is the ISO 18245 merchant category code (MCC) identifying the type of goods/services being purchased by the user.
addressVerificationData

object (AddressVerificationData)

OPTIONAL: The user's billing address to be verified by AVS.
Union field account_details_source. REQUIRED: The source of the details about the card the user is paying with. account_details_source can be only one of the following:
accountDetails

object (AccountDetails)

Data about the user's payment card.
authenticateRequestId

string

The requestId from the AuthenticateRequest request that authenticated the user for this payment. If this option is used, the accountDetails were sent in that request.
recurringPaymentMandate

object (RecurringPaymentMandate)

The payment is a recurring payment and can be made with an existing mandate.
inPlaceTokenizedCardPayment

object (InPlaceTokenizedCardPayment)

A card was passed to AuthenticateRequest with the intent to make a purchase and create a paymentToken. The new paymentToken is passed with the requestId for the AuthenticateRequest so a capture can be attempted on the paymentToken.
Union field authentication_attempted. REQUIRED: This is used to specify whether an attempt was made to authenticate the user with an authenticateRequest. authentication_attempted can be only one of the following:
authenticationNotAttempted

object (Empty)

An attempt was not made to authenticate the user. This typically means the request was system initiated.
authenticationWasSuccessful

object (AuthenticationDetails)

There was a successful call to authenticateRequest to authenticate the user for this purchase.
authenticationWasAttempted

object (AuthenticationDetails)

An inconclusive attempt was made to authenticate the user.

Response body

Response object for the payment integrator hosted payment-integrator-authenticated-card-fop-api.capture method.

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

JSON representation 
{
  "responseHeader": {
    object (ResponseHeader)
  },
  "paymentIntegratorCaptureId": string,
  "cardNetworkResult": {
    object (CardNetworkResult)
  },
  "addressVerificationResult": {
    object (AddressVerificationResult)
  },
  "cvnResult": enum (CvnResult),
  "result": enum (CaptureResultCode),
  "cardMetadata": {
    object (CardMetadata)
  },

  // Union field recurring_mandate_result can be only one of the following:
  "recurringMandateDetails": {
    object (RecurringMandateDetails)
  },
  "recurringMandateNotRequired": {
    object (Empty)
  },
  "recurringMandateNotSupported": {
    object (Empty)
  },
  "recurringMandateNotRequested": {
    object (Empty)
  }
  // End of list of possible types for union field recurring_mandate_result.
}
Fields
responseHeader

object (ResponseHeader)

REQUIRED: Common header for all responses.
paymentIntegratorCaptureId

string

OPTIONAL: This identifier is specific to the integrator and is generated by the integrator. The integrator identifies this capture in their system by this identifier.

For convenience, this identifier is included with in the remittance details
cardNetworkResult

object (CardNetworkResult)

REQUIRED: The result of issuing the capture on the card network.
addressVerificationResult

object (AddressVerificationResult)

REQUIRED: The result of verifying the address fields sent in the request.
cvnResult

enum (CvnResult)

REQUIRED: The result of verifying the CVN sent in the request. If the CVN was not set on the request, this value should be NOT_SENT.
result

enum (CaptureResultCode)

REQUIRED: Result of this call.
cardMetadata

object (CardMetadata)

REQUIRED: Optional metadata about the card that may be useful for future processing and debugging.
Union field recurring_mandate_result. OPTIONAL: Details about a recurring mandate, if applicable. recurring_mandate_result can be only one of the following:
recurringMandateDetails

object (RecurringMandateDetails)

The creation of a recurring mandate was requested and successful.
recurringMandateNotRequired

object (Empty)

The creation of a recurring mandate was requested, but it is not required for this transaction, e.g. because it is an international card that is out of scope.
recurringMandateNotSupported

object (Empty)

The creation of a recurring mandate was requested, but it is not currently supported for this transaction, e.g. the issuer does not yet support mandates. This differs from recurringMandateNotRequired, which is used for cards that are not in scope of requiring a mandate. recurringMandateNotSupported is used for cards that are in scope but can not currently support mandate creation.
recurringMandateNotRequested

object (Empty)

The creation of a recurring mandate was not requested.

RecurringPaymentMandate

Object to represent info related to a recurring payment mandate that can be used to make a purchase.

JSON representation 
{
  "mandateId": string,
  "recurringPaymentReferenceId": string,
  "paymentIntegratorNotificationId": string
}
Fields
mandateId

string

REQUIRED: The mandate ID associated with this recurring payment.
recurringPaymentReferenceId

string

REQUIRED: The reference ID associated with this recurring payment.
paymentIntegratorNotificationId

string

REQUIRED: The payment integrator generated ID for the notification that was sent to the user. This is returned from the related preNotifyUser call.

InPlaceTokenizedCardPayment

This object is used to pass details when payment-integrator-authenticated-card-fop-api.authenticate was called with a card and the card was then tokenized. The new paymentToken is passed with the requestId for the AuthenticateRequest so a capture can be attempted on the paymentToken.

JSON representation 
{
  "paymentToken": {
    object (PaymentToken)
  },
  "authenticateRequestId": string
}
Fields
paymentToken

object (PaymentToken)

Representation of a card that has been tokenized by the network.
authenticateRequestId

string

The requestId from the AuthenticateRequest request that authenticated the user for this payment using card details.

AuthenticationDetails

Contains details about the authentication that was performed.

JSON representation 
{
  "paymentIntegratorAuthenticationId": string,
  "recurringPaymentDetails": {
    object (RecurringPaymentDetails)
  }
}
Fields
paymentIntegratorAuthenticationId

string

OPTIONAL: This identifier is specific to the integrator and is generated by the integrator. The integrator identifies this authentication attempt in their system by this identifier. This will be populated when it was included in the authenticateResponse.
recurringPaymentDetails

object (RecurringPaymentDetails)

OPTIONAL: If present, a recurring payment is being configured. This contains details about those payments so a mandate can be created.

RecurringPaymentDetails

Object used to pass details needed for the creation of a recurring payment mandate that can be used to make future payments.

JSON representation 
{
  "customerReferenceId": string,
  "recurringPaymentReferenceId": string,
  "recurringPaymentDescription": string,
  "startDate": {
    object (Date)
  },
  "endDate": {
    object (Date)
  },
  "frequency": enum (Frequency),

  // Union field recurring_payment_amount can be only one of the following:
  "fixedAmount": {
    object (Amount)
  },
  "maximumAmount": {
    object (Amount)
  }
  // End of list of possible types for union field recurring_payment_amount.
}
Fields
customerReferenceId

string

REQUIRED: Google generated ID to reference this customer.
recurringPaymentReferenceId

string

REQUIRED: Google generated ID to reference this recurring payment.
recurringPaymentDescription

string

REQUIRED: Description of the recurring payment.
startDate

object (Date)

REQUIRED: Date of when the recurring payment began.
endDate

object (Date)

REQUIRED: Date of when this recurring payment ends. If the subscription does not have an end date, this will be set to a day far in the future, such as 31st Dec, 2099.
frequency

enum (Frequency)

REQUIRED: The expected frequency of the recurring payment.
Union field recurring_payment_amount. REQUIRED: The amount of the recurring payment, in micros of the currency unit. recurring_payment_amount can be only one of the following:
fixedAmount

object (Amount)

The recurring payment is for a fixed amount.
maximumAmount

object (Amount)

The recurring payment is for a variable amount up to this value.

Frequency

The expected frequency of the recurring payment.

Enums
FREQUENCY_UNSPECIFIED Do not ever set this default value!
WEEKLY Weekly payments are expected.
MONTHLY Monthly payments are expected.
BI_MONTHLY A payment is expected twice a month.
QUARTERLY Quarterly payments are expected.
BI_ANNUALLY Payments will occur twice a year.
YEARLY Yearly payments are expected.
ADHOC Payments do not have a set frequency.

CaptureResultCode

Result codes for the capture method.

Enums
CAPTURE_RESULT_CODE_UNSPECIFIED Do not ever set this default value!
SUCCESS payment-integrator-authenticated-card-fop-api.capture notification was successfully processed.
CARD_ACTIVITY_EXCEEDS_AMOUNT_LIMIT The recent activity on the user's card has exceeded the total amount allowed by the issuer.
CARD_ACTIVITY_EXCEEDS_COUNT_LIMIT The recent activity on the user's card has exceeded the number of transactions allowed by the issuer.
CARD_AUTHENTICATION_FAILED The network specified that the card authentication failed.
CARD_EXPIRATION_DATE_INVALID The expiration date on the card was invalid.
CARD_EXPIRED The card has expired.
CARD_LOST_OR_STOLEN The card has been lost or stolen. This includes 'Pickup' responses from the network.
CARD_NOT_ACTIVATED The card has not been activated. Also referred to as ’Blocked, first used’.
CARD_NUMBER_INVALID The card number is invalid.
CARD_REQUIRES_RESERVE_CAPTURE This card does not support the Funds Transfer (single message) protocol. Instead use use the Reserve payment-integrator-authenticated-card-fop-api.capture (dual message) service.
CUSTOMER_INFO_INVALID The provided customer info is invalid.
CVN_MISMATCH The transaction was declined because the CVN did not match.
DO_NOT_HONOR The network returned "Do not honor".
INSUFFICIENT_FUNDS Insufficient funds on the user's account.
ISSUER_DECLINED The transaction was declined by the issuer.
REVOCATION_OF_AUTHORIZATION The network returned "Revocation of authorization order".
STOP_PAYMENT The network returned "stop payment".
SUSPECTED_FRAUD The issuer suspects that this transaction is fraud.
TRANSACTION_COULD_NOT_BE_ROUTED The Network could not route this transaction for processing.
TRANSACTION_UNDER_AMOUNT_LIMIT Requested amount does not meet the minimum per-transaction amount.
TRANSACTION_EXCEEDS_AMOUNT_LIMIT Requested amount exceeds the maximum per-transaction limit.
TRANSACTION_INVALID The transaction is invalid.
TRANSACTION_NOT_ALLOWED This transaction is not allowed in this context (e.g. country).
TRANSACTION_PENDING The transaction is currently pending. This should not be treated as a successful payment.
RECURRING_PAYMENT_NOT_SUPPORTED An attempt was made to charge for a recurring transaction, but it is not supported.
NETWORK_TIMEOUT There was a timeout while attempting to process the card.
RESTRICTED_CARD The card is restricted from making this type of purchase.
CARD_AUTHENTICATION_EXPIRED The card authentication has expired.
MANDATE_CREATION_FAILED The creation of the mandate failed.
MANDATE_NOT_ACTIVE The specified mandate is not active to accept payments.
MANDATE_REQUIRED_BUT_NOT_PRESENT A mandate is required for this transaction but one was not specified.
CHARGE_CANCELED_BY_USER The user rejected this charge after receiving the notification for it.
DUPLICATE_REQUEST This request is a duplicate of another.
INTERNAL_ERROR An API processing error.
INVALID_ISSUER_RESPONSE The issuer has given an invalid response.
INVALID_REQUEST The card or request is invalid.
ISSUER_UNAVAILABLE The issuer is unavailible.
NOTIFICATION_NOT_SENT A notification was not sent to the user before a recurring mandate was used for payment.
NOTIFICATION_NOT_VALID The notification that was sent to the user for a recurring mandate payment was invalid.
NOT_PERMITTED The transaction is not permitted to the cardholder.
CHARGE_NOT_APPROVED_BY_USER The charge has not been approved by the user.
MANDATE_INSTRUMENT_NOT_VALID The instrument associated with the mandate on the integrator side is not valid. For example, when a mandate is created on card which is not migrated to a cloud token and deleted from the integrator's end.

RecurringMandateDetails

Details about the recurring mandate that was created.

JSON representation 
{
  "mandateId": string,
  "mandateStatus": enum (MandateStatus),
  "mandateCreationDetails": {
    object (MandateCreationDetails)
  }
}
Fields
mandateId

string

** REQUIRED **: The ID that represents the mandate created for this recurring mandate.
mandateStatus

enum (MandateStatus)

** REQUIRED **: The current status of the mandate.
mandateCreationDetails

object (MandateCreationDetails)

** REQUIRED **: Details pertaining to this mandate's creation. Set this when there is specific information that needs to be supplied regarding how the mandate was created.

MandateStatus

The status of the mandate that was created.

Enums
MANDATE_STATUS_UNSPECIFIED Do not ever set this default value!
PENDING The mandate is initiated but awaiting confirmation.
ACTIVE The mandate is active and can accept charges.
REJECTED The mandate was rejected by the payment provider or issuer.
DELETED The mandate was deleted by the customer or merchant.

MandateCreationDetails

Details pertaining to mandate creation.

JSON representation 
{

  // Union field source_of_mandate can be only one of the following:
  "integratorPaymentToken": {
    object (Empty)
  },
  "googlePaymentToken": {
    object (Empty)
  }
  // End of list of possible types for union field source_of_mandate.
}
Fields
Union field source_of_mandate. ** REQUIRED **: Source of the payment-token on which the mandate was created. source_of_mandate can be only one of the following:
integratorPaymentToken

object (Empty)

Signifies that the mandate was created on integrator's payment-token.
googlePaymentToken

object (Empty)

Signifies that the mandate was created on Google's payment-token.