Method: reserveFunds

HTTP request
Request body
- JSON representation
Response body
ReserveFundsResponse
- JSON representation
ReserveFundsResultCode

Reserve funds on a user's card.

This call synchronously attempts to reserve funds from a user's card. The response to this message will return the result of that attempt. No money is directly moved as the result of this call. The requested amount of funds should be reserved until an asynchronousCaptureFundsReservation, an asynchronousCancelFundsReservation or until the reservation has reached the reservationExpirationTimestamp specified in the ReserveFundsResponse. The combination of requestId within the header and paymentIntegratorAccountId is the idempotency key and uniquely identifies this transaction. All mutations on this transaction (asynchronousCancelFundsReservation, asynchronousCaptureFundsReservation) populate the requestId value in their reservationRequestId 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 using a physical card looks like:


{
  "requestHeader": {
    "protocolVersion": {
      "major": 1,
      "minor": 0,
      "revision": 0
    },
    "requestId": "G1MQ0YERJ0Q7LPM",
    "requestTimestamp": "1481899949606"
  },
  "paymentIntegratorAccountId": "SpeedyPaymentsIndia_INR",
  "accountDetails": {
    "card": {
      "accountNumber": "4123456789101112",
      "nameOnCard": "Example Customer",
      "expiryMonth": "01",
      "expiryYear": "20",
      "cvn": "123"
    }
  },
  "currencyCode": "INR",
  "amount": "728000000",
  "transactionDescription": "Movie ACB",
  "merchantCategoryCode": "5815",
  "addressVerificationData": {
    "addressLine": [
      "2 Inner Ring Road"
    ],
    "localityName": "Bangalore",
    "administrativeAreaName": "Karnataka",
    "postalCodeNumber": "560071",
    "countryCode": "IN"
  },
  "additionalTransactionProcessingOptions": {
    "userSelectedProcessingNetworkTypeNotApplicable": {},
    "electronicCommerceIndicator": "05",
    "threeDSecureAuthenticationDetails": {
      "directoryServerTransactionId": "c5b808e7-1de1-4069-a17b-f70d3b3b1640",
      "cavv": "123ABCCAVVAA",
      "threeDsVersion": "2.2.0"
    },
    "storedCredentialTransactionInformation": {
      "merchantInitiated": {
        "transactionIntentClassification": "RECURRING",
        "instrumentStorageType": "STORED",
        "previousTransactionInformation": {
          "storedCredentialTransactionId": "c7e2d54b-aa12-4aea-9ce6-fb6f1e4df2b4",
          "originalTransactionAmount": "728000000"
        }
      }
    }
  }
}

An example request using a tokenized card looks like:


{
  "requestHeader": {
    "protocolVersion": {
      "major": 1,
      "minor": 0,
      "revision": 0
    },
    "requestId": "G1MQ0YERJ0Q7LPM",
    "requestTimestamp": "1481899949606"
  },
  "paymentIntegratorAccountId": "SpeedyPaymentsIndia_INR",
  "accountDetails": {
    "paymentToken": {
      "nameOnCard": "Example Customer",
      "paymentTokenAccountNumber": "4123456789101112",
      "expiryMonth": "01",
      "expiryYear": "20",
      "cryptogram": "12345"
    }
  },
  "currencyCode": "INR",
  "amount": "728000000",
  "transactionDescription": "Movie ACB",
  "merchantCategoryCode": "5815",
  "addressVerificationData": {
    "addressLine": ["2 Inner Ring Road"],
    "localityName": "Bangalore",
    "administrativeAreaName": "Karnataka",
    "postalCodeNumber": "560071",
    "countryCode": "IN"
  },
  "additionalTransactionProcessingOptions": {
    "userSelectedProcessingNetworkTypeNotApplicable": {},
    "electronicCommerceIndicator": "05",
    "threeDSecureAuthenticationDetails": {
      "directoryServerTransactionId": "c5b808e7-1de1-4069-a17b-f70d3b3b1640",
      "cavv": "123ABCCAVVAA",
      "threeDsVersion": "2.2.0"
    },
    "storedCredentialTransactionInformation": {
      "merchantInitiated": {
        "transactionIntentClassification": "RECURRING",
        "instrumentStorageType": "STORED",
        "previousTransactionInformation": {
          "storedCredentialTransactionId": "c7e2d54b-aa12-4aea-9ce6-fb6f1e4df2b4",
          "originalTransactionAmount": "728000000"
        }
      }
    }
  }
}

An example response looks like:


{
  "responseHeader": {
    "responseTimestamp": "1481899950236"
  },
  "paymentIntegratorFundsReservationId":
    "2eec3ece-66cf-4d0e-90ea-0933a0079753",
  "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",
  "reservationExpirationTimestamp": "1482460769503",
  "cardMetadata": {
    "issuerName": "exampleissuer",
    "issuingCountryCode": "IN",
    "networks": ["VISA"],
    "cardType": "CREDIT_CARD"
  },
  "additionalTransactionProcessingResult": {
    "storedCredentialInformationSuccessful": {
      "networkTransactionIdentifier": "cdf04f0d-44a8-4b5d-bf63-440e9194db33"
    }
  }
}

HTTP request

POST https://www.integratorhost.example.com/integrator-base-path/v1/payment-integrator-card-fop-api/reserveFunds

Request body

The request body contains data with the following structure:

JSON representation

JSON representation
{ "requestHeader": { object (`RequestHeader`) }, "paymentIntegratorAccountId": string, "accountDetails": { object (`AccountDetails`) }, "currencyCode": string, "amount": string, "transactionDescription": string, "merchantCategoryCode": string, "addressVerificationData": { object (`AddressVerificationData`) }, "additionalTransactionProcessingOptions": { object (`AdditionalTransactionProcessingOptions`) } }

{
  "requestHeader": {
    object (RequestHeader)
  },
  "paymentIntegratorAccountId": string,
  "accountDetails": {
    object (AccountDetails)
  },
  "currencyCode": string,
  "amount": string,
  "transactionDescription": string,
  "merchantCategoryCode": string,
  "addressVerificationData": {
    object (AddressVerificationData)
  },
  "additionalTransactionProcessingOptions": {
    object (AdditionalTransactionProcessingOptions)
  }
}

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.
`accountDetails`	`object (AccountDetails)` REQUIRED: Data about the user's payment card.
`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.
`transactionDescription`	`string` REQUIRED: This is the description of the transaction that can be put on the customer's statement. This format can be changed without notice and must never be parsed. 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 address to be verified by AVS.
`additionalTransactionProcessingOptions`	`object (AdditionalTransactionProcessingOptions)` REQUIRED: Used to specify additional details about a transaction that might not apply to every region or situation. This is used to enable particular features, such as 3DS, specify details about how a transaction should be processed, or provide additional information that can be used to authenticate the transaction. If these fields are specified then they should be applied for the transaction.

Response body

This method supports multiple return types. For additional information about what 4XX or 5XX HTTP status code to return with an ErrorResponse, consult the ErrorResponse object and HTTP status codes documentation.

Possible response messages
HTTP 200 Status	`object (ReserveFundsResponse)`
HTTP 4XX / 5XX Status	`object (ErrorResponse)`

ReserveFundsResponse

Response object for the payment integrator hosted card-fop-v1.reserveFunds method.

JSON representation

JSON representation
{ "responseHeader": { object (`ResponseHeader`) }, "paymentIntegratorFundsReservationId": string, "cardNetworkResult": { object (`CardNetworkResult`) }, "addressVerificationResult": { object (`AddressVerificationResult`) }, "cvnResult": enum (`CvnResult`), "result": enum (`ReserveFundsResultCode`), "reservationExpirationTimestamp": string, "cardMetadata": { object (`CardMetadata`) }, "additionalTransactionProcessingResult": { object (`AdditionalTransactionProcessingResult`) } }

{
  "responseHeader": {
    object (ResponseHeader)
  },
  "paymentIntegratorFundsReservationId": string,
  "cardNetworkResult": {
    object (CardNetworkResult)
  },
  "addressVerificationResult": {
    object (AddressVerificationResult)
  },
  "cvnResult": enum (CvnResult),
  "result": enum (ReserveFundsResultCode),
  "reservationExpirationTimestamp": string,
  "cardMetadata": {
    object (CardMetadata)
  },
  "additionalTransactionProcessingResult": {
    object (AdditionalTransactionProcessingResult)
  }
}

Fields
`responseHeader`	`object (ResponseHeader)` REQUIRED: Common header for all responses.
`paymentIntegratorFundsReservationId`	`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
`cardNetworkResult`	`object (CardNetworkResult)` REQUIRED: The result of issuing the authorization 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 (ReserveFundsResultCode)` REQUIRED: Result of this call.
`reservationExpirationTimestamp`	`string (int64 format)` OPTIONAL: Timestamp of the expiration of this reservation of funds represented as milliseconds since epoch. If `card-fop-v1.asynchronousCaptureFundsReservation` is called after this timestamp, a `CaptureFundsReservationResultNotification` must be sent to Google with the code `RESERVATION_OF_FUNDS_EXPIRED` If `card-fop-v1.asynchronousCancelFundsReservation` is called after this timestamp and the integrator has already issued an automatic cancel, a `CancelFundsReservationResultNotification` must be sent to Google with the code `SUCCESS`. If the integrator has not issued an automatic cancel, the request must be processed normally and the reservation of funds must be canceled.
`cardMetadata`	`object (CardMetadata)` REQUIRED: Optional metadata about the card that may be useful for future processing and debugging.
`additionalTransactionProcessingResult`	`object (AdditionalTransactionProcessingResult)` REQUIRED: Information resulting from additional processing options sent in the request. Note: This field will transition to be required.

ReserveFundsResultCode

Result codes for the reserveFunds method.

Enums
`RESERVE_FUNDS_RESULT_CODE_UNSPECIFIED`	Do not ever set this default value!
`SUCCESS`	Reserve funds 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_FUNDS_TRANSFER`	This card does not support the Reserve card-fop-v1.capture (dual message) protocol. Instead use use the Funds Transfer (single 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 network returned invalid transaction.
`TRANSACTION_NOT_ALLOWED`	This transaction is not allowed in this context (e.g. country).
`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.
`STRONG_CUSTOMER_AUTHENTICATION_REQUIRED`	The customer must complete Strong Customer Authentication (SCA), and the proof of authentication must be provided along with the payment authorization request, for this transaction to succeed.