Method: 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 requestId within the header 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",
      "threeDsServerTransactionId": "40c52a12-31e1-463e-ab0e-89d9f6189b79",
      "transStatus": "Y"
    },
    "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",
      "threeDsServerTransactionId": "40c52a12-31e1-463e-ab0e-89d9f6189b79",
      "transStatus": "Y"
    },
    "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-korea-cards-api/reserveFunds

Request body

The request body contains data with the following structure:

JSON representation 
{
  "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)

AccountDetails

Contains data related to the user's payment card.

JSON representation 
{

  // Union field account_representation can be only one of the following:
  "card": {
    object (Card)
  },
  "paymentToken": {
    object (PaymentToken)
  }
  // End of list of possible types for union field account_representation.
}
Fields
Union field account_representation. REQUIRED: The card details. account_representation can be only one of the following:
card

object (Card)

Representation of a card in its physical format (i.e. the FPAN).
paymentToken

object (PaymentToken)

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

PaymentToken

The representation of a card after it has been tokenized by the network.

JSON representation 
{
  "nameOnCard": string,
  "paymentTokenAccountNumber": string,
  "expiryMonth": string,
  "expiryYear": string,
  "cryptogram": string
}
Fields
nameOnCard

string

REQUIRED: The customer's name as it appears on the card.
paymentTokenAccountNumber

string

REQUIRED: The account number for the payment token.
expiryMonth

string

OPTIONAL: Expiration month, formatted MM.
expiryYear

string

OPTIONAL: Expiration year, formatted YY.
cryptogram

string

OPTIONAL: The single-use key generated by the token provider for the transaction.

AdditionalTransactionProcessingOptions

Contains additional information relevant to processing the payment.

JSON representation 
{

  // Union field processing_network_type can be only one of the following:
  "userSelectedProcessingNetworkType": enum (UserSelectedProcessingNetworkType),
  "userSelectedProcessingNetworkTypeNotApplicable": {
    object (Empty)
  }
  // End of list of possible types for union field processing_network_type.

  // Union field electronic_commerce_indicator_option can be only one of the
  // following:
  "electronicCommerceIndicator": string,
  "electronicCommerceIndicatorNotApplicable": {
    object (Empty)
  }
  // End of list of possible types for union field
  // electronic_commerce_indicator_option.

  // Union field authentication_details can be only one of the following:
  "threeDSecureAuthenticationDetails": {
    object (ThreeDSecureAuthenticationData)
  },
  "threeDSecureNotAppplicable": {
    object (Empty)
  }
  // End of list of possible types for union field authentication_details.

  // Union field stored_credentials can be only one of the following:
  "storedCredentialTransactionInformation": {
    object (StoredCredentialTransactionInformation)
  },
  "storedCredentialTransactionInformationNotApplicable": {
    object (Empty)
  }
  // End of list of possible types for union field stored_credentials.

  // Union field pin_option can be only one of the following:
  "pin": string,
  "pinNotApplicable": {
    object (Empty)
  }
  // End of list of possible types for union field pin_option.

  // Union field connecting_information_option can be only one of the following:
  "connectingInformation": string,
  "connectingInformationNotApplicable": {
    object (Empty)
  }
  // End of list of possible types for union field connecting_information_option.

  // Union field date_of_birth_option can be only one of the following:
  "dateOfBirth": string,
  "dateOfBirthNotApplicable": {
    object (Empty)
  }
  // End of list of possible types for union field date_of_birth_option.

  // Union field business_identifier_option can be only one of the following:
  "businessIdentifier": string,
  "businessIdentifierNotApplicable": {
    object (Empty)
  }
  // End of list of possible types for union field business_identifier_option.

  // Union field sca_exemption_type can be only one of the following:
  "scaExemptionNotApplicable": {
    object (Empty)
  },
  "scaLowValueTransaction": {
    object (Empty)
  },
  "scaTransactionRiskAnalysis": {
    object (Empty)
  }
  // End of list of possible types for union field sca_exemption_type.
}
Fields
Union field processing_network_type. REQUIRED: Indicates the user's preference on which network type the payment should be processed. processing_network_type can be only one of the following:
userSelectedProcessingNetworkType

enum (UserSelectedProcessingNetworkType)

User-provided preference for network type.
userSelectedProcessingNetworkTypeNotApplicable

object (Empty)

User selection not relevant to this card or transaction.
Union field electronic_commerce_indicator_option. REQUIRED: The numeric ECI value to be sent to the network. electronic_commerce_indicator_option can be only one of the following:
electronicCommerceIndicator

string

The Electronic Commerce Indicator representing a numeric value defined by the card network. This should be sent to the network with the transaction.
electronicCommerceIndicatorNotApplicable

object (Empty)

An ECI is not used for this transaction.
Union field authentication_details. REQUIRED: This union contains the authentication details of the payment processed. authentication_details can be only one of the following:
threeDSecureAuthenticationDetails

object (ThreeDSecureAuthenticationData)

Proof of a successful 3DS2 authentication.
threeDSecureNotAppplicable

object (Empty)

3DS2 was not performed for this transaction.
Union field stored_credentials. REQUIRED: Information pertaining to the usage of stored credentials. stored_credentials can be only one of the following:
storedCredentialTransactionInformation

object (StoredCredentialTransactionInformation)

Information pertaining to the usage of stored credentials within the CIT/MIT framework.
storedCredentialTransactionInformationNotApplicable

object (Empty)

Stored credential information is not applicable for this payment.
Union field pin_option. REQUIRED: This union contains the PIN associated with the specified payment. pin_option can be only one of the following:
pin

string

The PIN associated with this transaction.
pinNotApplicable

object (Empty)

This transaction does not have an associated PIN.
Union field connecting_information_option. REQUIRED: This union contains the connecting information associated with the specified payment. It is used to satisfy the I-PIN requirements for transactions in Korea. connecting_information_option can be only one of the following:
connectingInformation

string

The connecting information (CI) that should be associated with this transaction.
connectingInformationNotApplicable

object (Empty)

3DS2 was not performed for this transaction.
Union field date_of_birth_option. REQUIRED: This union contains the date of birth of the user associated with the account making the payment. date_of_birth_option can be only one of the following:
dateOfBirth

string

Date of birth in 'YYYY-MM-DD' format.
dateOfBirthNotApplicable

object (Empty)

The account holder's date of birth is not necessary for this transaction.
Union field business_identifier_option. REQUIRED: This union contains the business identifier associated with the specified payment. business_identifier_option can be only one of the following:
businessIdentifier

string

The business identifier associated with this payment.
businessIdentifierNotApplicable

object (Empty)

The business identifier is not applicable for this payment.
Union field sca_exemption_type. OPTIONAL: Provides information about the type of SCA exemption that is requested for this transaction from the issuer. sca_exemption_type can be only one of the following:
scaExemptionNotApplicable

object (Empty)

No exemption is requested for this transaction.
scaLowValueTransaction

object (Empty)

A low value exemption is requested for this transaction.
scaTransactionRiskAnalysis

object (Empty)

A low risk exemption is requested for this transaction.

UserSelectedProcessingNetworkType

Used to indicate the desired network type for the transaction to be processed on.

Enums
PROCESSING_NETWORK_TYPE_UNSPECIFIED Do not ever set this default value!
CREDIT The payment should be processed on a credit network.
DEBIT The payment should be processed on a debit network.

ThreeDSecureAuthenticationData

Contains 3-D Secure v2 Authentication details relavent to payment processing.

JSON representation 
{
  "directoryServerTransactionId": string,
  "cavv": string,
  "threeDsVersion": string,
  "threeDsServerTransactionId": string,
  "transStatus": string
}
Fields
directoryServerTransactionId

string

REQUIRED: Unique transaction identifier assigned and returned by the directory server as a part of successful authentication result. As per the EMVCo 3-D Secure spec v2, this is a UUID following IETF RFC 4122.
cavv

string

REQUIRED: Cardholder Authentication Verification Value, the proof of authentication, returned by the ACS and is in Base64 format.
threeDsVersion

string

REQUIRED: The version of 3DS v2 used to process the authentication. The field is populated with the value returned by the ACS.
threeDsServerTransactionId

string

OPTIONAL: Universally unique transaction identifier assigned by the 3DS Server to identify a single transaction.
transStatus

string

OPTIONAL: The final status of the 3DS flow which resulted in the cardholder authentication information associated with this request. Refer to EMVCo's 3DS specifications for additional details.

ReserveFundsResponse

Response object for the payment integrator hosted korea-cards-v1.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)
  },
  "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 korea-cards-v1.asynchronousCaptureFundsReservation is called after this timestamp, a CaptureFundsReservationResultNotification must be sent to Google with the code RESERVATION_OF_FUNDS_EXPIRED

If korea-cards-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.

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 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.
CARD_CANCELLED The card is no longer valid.