Page Summary
-
The API allows reserving funds on a user's card without an immediate transfer, holding the reservation until captured, canceled, or expired.
-
Idempotency is maintained using
requestIdandpaymentIntegratorAccountIdfor reliable transaction processing. -
The API provides endpoints for reserving funds (
POST /reserveFunds) and returns comprehensive responses including reservation details or error information. -
Data structures such as
AccountDetails,PaymentToken, andAdditionalTransactionProcessingOptionsare used to manage user card data, tokenization, and transaction-specific configurations. -
The
ReserveFundsResponseobject provides details about the reservation outcome, including the reservation ID, card network results, and expiration timestamp.
- HTTP request
- Request body
- Response body
- AccountDetails
- PaymentToken
- AdditionalTransactionProcessingOptions
- UserSelectedProcessingNetworkType
- ThreeDSecureAuthenticationData
- ReserveFundsResponse
- 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 , an asynchronousCaptureFundsReservation or until the reservation has reached the asynchronousCancelFundsReservationreservationExpirationTimestamp specified in the ReserveFundsResponse. The requestId within the header is the idempotency key and uniquely identifies this transaction. All mutations on this transaction (, asynchronousCancelFundsReservation) populate the asynchronousCaptureFundsReservationrequestId 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",
"tokenTypeMerchantToken": {}
}
},
"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 successful response looks like:
{
"responseHeader": {
"responseTimestamp": "1481899950236"
},
"paymentIntegratorFundsReservationId":
"2eec3ece-66cf-4d0e-90ea-0933a0079753",
"cardNetworkResult": {
"passThroughResponseCodes": {
"iso8583V1987ResponseCode": {
"responseCode": "00",
"responseCodeDescription": "Approved"
}
},
"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"
}
}
}
An example declined response looks like:
{
"responseHeader": {
"responseTimestamp": "1481899950236"
},
"paymentIntegratorFundsReservationId":
"2eec3ece-66cf-4d0e-90ea-0933a0079753",
"cardNetworkResult": {
"passThroughResponseCodes": {
"iso8583V1987ResponseCode": {
"responseCode": "05",
"responseCodeDescription": "Do not honor"
},
"merchantAdviceCode": {
"responseCode": "03",
"responseCodeDescription": "Do not try again"
}
}
},
"addressVerificationResult": {
"result": {
"rawAvsResult": "M",
"addressLine": "MATCH",
"localityName": "MATCH",
"administrativeAreaName": "MATCH",
"postalCodeNumber": "MATCH",
"countryCode": "MATCH",
"nameOnCard": "MATCH"
}
},
"cvnResult": "MATCH",
"result": "DO_NOT_HONOR",
"reservationExpirationTimestamp": "1482460769503",
"cardMetadata": {
"issuerName": "exampleissuer",
"issuingCountryCode": "IN",
"networks": ["MASTERCARD"],
"cardType": "CREDIT_CARD"
},
"additionalTransactionProcessingResult": {
"storedCredentialInformationUnsupported": {}
}
}
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 ( |
| Fields | |
|---|---|
requestHeader |
REQUIRED: Common header for all requests. |
paymentIntegratorAccountId |
REQUIRED: This is the payment integrator account identifier that identifies contractual constraints around this transaction. |
accountDetails |
REQUIRED: Data about the user's payment card. |
currencyCode |
REQUIRED: ISO 4217 3-letter currency code. |
amount |
REQUIRED: The amount of the purchase, in micros of the currency unit. |
transactionDescription |
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. |
addressVerificationData |
OPTIONAL: The user's address to be verified by AVS. |
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. |
| REQUIRED: The option for providing the merchant category code. The following is a list of mutually exclusive fields. At most one of the fields will be set in a response: | |
merchantCategoryCode |
This is the ISO 18245 merchant category code (MCC) identifying the type of goods/services being purchased by the user. |
merchantCategoryCodeNotPresent |
Indicates that the merchant category code is not present. This option is used specifically for certain regions (such as Korea) or cases where MCC is not required by the payment integrator. |
| End of mutually exclusive fields. | |
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 |
|
| HTTP 4XX / 5XX Status |
|
| End of mutually exclusive fields. | |
AccountDetails
Contains data related to the user's payment card.
| JSON representation |
|---|
{ // The following is a list of mutually exclusive fields. At most one of the // fields will be set in a response: "card": { object ( |
| Fields | |
|---|---|
| REQUIRED: The card details. The following is a list of mutually exclusive fields. At most one of the fields will be set in a response: | |
card |
Representation of a card in its physical format (i.e. the FPAN). |
paymentToken |
Representation of a card that has been tokenized by the network. |
| End of mutually exclusive fields. | |
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, // The following is a list of mutually exclusive fields. At most one of the // fields will be set in a response: "tokenTypeDeviceToken": { object ( |
| Fields | |
|---|---|
nameOnCard |
REQUIRED: The customer's name as it appears on the card. |
paymentTokenAccountNumber |
REQUIRED: The account number for the payment token. |
expiryMonth |
OPTIONAL: Expiration month, formatted |
expiryYear |
OPTIONAL: Expiration year, formatted |
cryptogram |
OPTIONAL: The single-use key generated by the token provider for the transaction. |
| REQUIRED: The type of token. The following is a list of mutually exclusive fields. At most one of the fields will be set in a response: | |
tokenTypeDeviceToken |
The token is bound to a device. It is represented by a DPAN and was generated by the user going through a SCA (Strong Customer Authentication) / Step Up flow. |
tokenTypeMerchantToken |
The token is bound to a merchant. It could be used while the user is offline and might be accompanied by additional, transaction time authentication details, such as 3DS2. |
tokenTypeUnsupported |
Unsupported token type. |
tokenTypeNotApplicable |
Payment token type is not applicable. Not passed in the request. |
| End of mutually exclusive fields. | |
AdditionalTransactionProcessingOptions
Contains additional information relevant to processing the payment.
| JSON representation |
|---|
{ // The following is a list of mutually exclusive fields. At most one of the // fields will be set in a response: "userSelectedProcessingNetworkType": enum ( |
| Fields | |
|---|---|
| REQUIRED: Indicates the user's preference on which network type the payment should be processed. The following is a list of mutually exclusive fields. At most one of the fields will be set in a response: | |
userSelectedProcessingNetworkType |
User-provided preference for network type. |
userSelectedProcessingNetworkTypeNotApplicable |
User selection not relevant to this card or transaction. |
| End of mutually exclusive fields. | |
| REQUIRED: The numeric ECI value to be sent to the network. The following is a list of mutually exclusive fields. At most one of the fields will be set in a response: | |
electronicCommerceIndicator |
The Electronic Commerce Indicator representing a numeric value defined by the card network. This should be sent to the network with the transaction. |
electronicCommerceIndicatorNotApplicable |
An ECI is not used for this transaction. |
| End of mutually exclusive fields. | |
| REQUIRED: This union contains the authentication details of the payment processed. The following is a list of mutually exclusive fields. At most one of the fields will be set in a response: | |
threeDSecureAuthenticationDetails |
Proof of a successful 3DS2 authentication. |
threeDSecureNotAppplicable |
3DS2 was not performed for this transaction. |
| End of mutually exclusive fields. | |
| REQUIRED: Information pertaining to the usage of stored credentials. The following is a list of mutually exclusive fields. At most one of the fields will be set in a response: | |
storedCredentialTransactionInformation |
Information pertaining to the usage of stored credentials within the CIT/MIT framework. |
storedCredentialTransactionInformationNotApplicable |
Stored credential information is not applicable for this payment. |
| End of mutually exclusive fields. | |
| REQUIRED: This union contains the PIN associated with the specified payment. The following is a list of mutually exclusive fields. At most one of the fields will be set in a response: | |
pin |
The PIN associated with this transaction. |
pinNotApplicable |
This transaction does not have an associated PIN. |
| End of mutually exclusive fields. | |
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. The following is a list of mutually exclusive fields. At most one of the fields will be set in a response: |
|
connectingInformation |
The connecting information (CI) that should be associated with this transaction. |
connectingInformationNotApplicable |
3DS2 was not performed for this transaction. |
| End of mutually exclusive fields. | |
| REQUIRED: This union contains the date of birth of the user associated with the account making the payment. The following is a list of mutually exclusive fields. At most one of the fields will be set in a response: | |
dateOfBirth |
Date of birth in 'YYYY-MM-DD' format. |
dateOfBirthNotApplicable |
The account holder's date of birth is not necessary for this transaction. |
| End of mutually exclusive fields. | |
| REQUIRED: This union contains the business identifier associated with the specified payment. The following is a list of mutually exclusive fields. At most one of the fields will be set in a response: | |
businessIdentifier |
The business identifier associated with this payment. |
businessIdentifierNotApplicable |
The business identifier is not applicable for this payment. |
| End of mutually exclusive fields. | |
| OPTIONAL: Provides information about the type of SCA exemption that is requested for this transaction from the issuer. The following is a list of mutually exclusive fields. At most one of the fields will be set in a response: | |
scaExemptionNotApplicable |
No exemption is requested for this transaction. |
scaLowValueTransaction |
A low value exemption is requested for this transaction. |
scaTransactionRiskAnalysis |
A low risk exemption is requested for this transaction. |
| End of mutually exclusive fields. | |
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 |
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 |
REQUIRED: Cardholder Authentication Verification Value, the proof of authentication, returned by the ACS and is in Base64 format. |
threeDsVersion |
REQUIRED: The version of 3DS v2 used to process the authentication. The field is populated with the value returned by the ACS. |
threeDsServerTransactionId |
OPTIONAL: Universally unique transaction identifier assigned by the 3DS Server to identify a single transaction. |
transStatus |
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 ( |
| Fields | |
|---|---|
responseHeader |
REQUIRED: Common header for all responses. |
paymentIntegratorFundsReservationId |
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 |
REQUIRED: The result of issuing the authorization on the card network. |
addressVerificationResult |
REQUIRED: The result of verifying the address fields sent in the request. |
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 |
result |
REQUIRED: Result of this call. |
reservationExpirationTimestamp |
OPTIONAL: Timestamp of the expiration of this reservation of funds represented as milliseconds since epoch. If If |
cardMetadata |
REQUIRED: Optional metadata about the card that may be useful for future processing and debugging. |
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. |
PIN_MISMATCH |
The PIN on the card did not match the one provided in the request. |
DOB_OR_BRN_MISMATCH |
The date of birth or business registration number did not match. |