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

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.

An example request looks like:


{
  "requestHeader": {
    "protocolVersion": {
      "major": 1
    },
    "requestId": "G1MQ0YERJ0Q7LPM",
    "requestTimestamp": {
      "epochMillis": 1481899949606
    },
  "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 response looks like:


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

HTTP request

POST https://www.integratordomain.com/v1/payment-integrator-authenticated-card-fop-api/reserveFunds

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
  // End of list of possible types for union field account_details_source.

  // Union field AuthenticationAttempted can be only one of the following:
  "authenticationNotAttempted": {
    object (Empty)
  },
  "authenticationWasSuccessful": {
    object (Empty)
  }
  // End of list of possible types for union field AuthenticationAttempted.
}
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.

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.

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.

Union field AuthenticationAttempted. REQUIRED: This is used to specify whether an attempt was made to authenticate the user with an authenticateRequest. AuthenticationAttempted 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 (Empty)

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

Response body

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

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

JSON representation
{
  "responseHeader": {
    object (ResponseHeader)
  },
  "paymentIntegratorFundsReservationId": string,
  "cardNetworkResult": {
    object (CardNetworkResult)
  },
  "addressVerificationResult": {
    object (AddressVerificationResult)
  },
  "cvnResult": enum (CvnResult),
  "result": enum (ReserveFundsResultCode),
  "reservationExpirationTimestamp": string,
  "cardMetadata": {
    object (CardMetadata)
  }
}
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.

The integrator should automatically cancel this reservation of funds once this timestamp has passed and send a CancelFundsReservationResultNotification to Google with the code SUCCESS once the automatic cancel is successful.

If payment-integrator-authenticated-card-fop-api.asynchronousCaptureFundsReservation is called after this timestamp, a CaptureFundsReservationResultNotification must be sent to Google with the code RESERVATION_OF_FUNDS_EXPIRED

If payment-integrator-authenticated-card-fop-api.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.

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 payment-integrator-authenticated-card-fop-api.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).
TRANSACTION_PENDING The transaction is currently pending. This should not be treated as a successful payment.