Method: reserveFunds

Reserve funds on a token.

This call synchronously attempts to reserve funds from a previously tokenized account. 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 a captureFundsReservation, a cancelFundsReservation, or until the reservation has reached the reservation_expiration_timestamp 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 (cancelFundsReservation, captureFundsReservation) populate the requestId value in their reserveFundsRequestId field.

An example request looks like:


{
  "requestHeader": {
    "protocolVersion": {
      "major": 2
    },
    "requestId": "bWVyY2hhbnQgdHJhbnNhY3Rpb24gaWQ",
    "requestTimestamp": {
      "epochMillis": "1502220196077"
    },
    "paymentIntegratorAccountId": "SpeedyPaymentsIndia_INR"
  },
  "googlePaymentToken": {
    "issuerId": {
      "value": "InvisiCashUSA"
    },
    "token": "ZXhhbXBsZSB1bmlxdWUgcGF5bWVudCB0b2tlbiB2YWx1ZQ"
  },
  "transactionDescription": "Google - Music",
  "amount": {
    "amountMicros": "728000000",
    "currencyCode": "INR"
  },
  "tax": {
    "amountMicros": "27300000",
    "currencyCode": "INR"
  },
  "reserveFundsContext": {
    "shippingAddress": {
      "name": "Example Customer",
      "addressLine": ["123 Main St"],
      "localityName": "Springfield",
      "administrativeAreaName": "CO",
      "postalCodeNumber": "80309",
      "countryCode": "US"
    }
  }
}

An example response looks like:


{
  "responseHeader": {
    "responseTimestamp": {
      "epochMillis": "1481907920760"
    },
    "requestId": "bWVyY2hhbnQgdHJhbnNhY3Rpb24gaWQ"
  },
  "expirationTimestamp": {
    "epochMillis": "1481907930760"
  },
  "result": {
    "success": {}
  }
}

HTTP request

POST https://www.integratordomain.com/v2/reserveFunds

Request body

The request body contains data with the following structure:

JSON representation
{
  "requestHeader": {
    object (RequestHeader)
  },
  "googlePaymentToken": {
    object (GooglePaymentToken)
  },
  "transactionDescription": string,
  "amount": {
    object (Amount)
  },
  "tax": {
    object (Amount)
  },
  "reserveFundsContext": {
    object (ReserveFundsContext)
  }
}
Fields
requestHeader

object (RequestHeader)

REQUIRED: Common header for all requests.

googlePaymentToken

object (GooglePaymentToken)

REQUIRED: This is the token that both companies will use to identify the account for purchases between each other.

transactionDescription

string

REQUIRED: This is the description of the transaction that can be put on the customer's statement. Localized to the userLocale found in the requestHeader. This format can be changed without notice and must never be parsed.

amount

object (Amount)

REQUIRED: The amount of the purchase.

tax

object (Amount)

REQUIRED: The amount of the purchase the buyer is paying in taxes.

reserveFundsContext

object (ReserveFundsContext)

REQUIRED: Context about this funds reservation.

Response body

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

Response object for the funds reservation method.

JSON representation
{
  "responseHeader": {
    object (ResponseHeader)
  },
  "result": {
    object (ReserveFundsResult)
  },
  "expirationTimestamp": {
    object (Timestamp)
  }
}
Fields
responseHeader

object (ResponseHeader)

REQUIRED: Common header for all responses.

result

object (ReserveFundsResult)

REQUIRED: Result of this funds reservation.

expirationTimestamp

object (Timestamp)

REQUIRED: The expiration timestamp for this funds reservation.

ReserveFundsContext

This object provides context about how the funds reservation was requested.

JSON representation
{
  "shippingAddress": {
    object (Address)
  }
}
Fields
shippingAddress

object (Address)

OPTIONAL: This is the shipping address for a physical goods order. If the particular contract doesn't stipulate the need for this field it will always be empty.

Address

Structure holding information about an address.

JSON representation
{
  "name": string,
  "addressLine": [
    string
  ],
  "localityName": string,
  "administrativeAreaName": string,
  "postalCodeNumber": string,
  "countryCode": string
}
Fields
name

string

OPTIONAL: Customer's full name.

addressLine[]

string

OPTIONAL: This holds unstructured Address text.

localityName

string

OPTIONAL: This is something of a fuzzy term, but it generally refers to the city/town portion of an address. In regions of the world where localities are not well defined or do not fit into this structure well (for example, Japan and China), leave localityName empty and use addressLine.

Examples: US city, IT comune, UK post town.

administrativeAreaName

string

OPTIONAL: Top-level administrative subdivision of this country" Examples: US state, IT region, CN province, JP prefecture."

postalCodeNumber

string

OPTIONAL: Despite the name, postalCodeNumber values are frequently alphanumeric. Examples: "94043", "SW1W", "SW1W 9TQ".

countryCode

string

OPTIONAL: Customer address country code, expected to be ISO-3166-1 Alpha-2.

ReserveFundsResult

JSON representation
{

  // Union field result can be only one of the following:
  "success": {
    object (Empty)
  },
  "chargeExceedsTransactionLimit": {
    object (ChargeExceedsTransactionLimit)
  },
  "chargeExceedsDailyLimit": {
    object (ChargeExceedsDailyLimit)
  },
  "chargeExceedsMonthlyLimit": {
    object (ChargeExceedsMonthlyLimit)
  },
  "chargeUnderLimit": {
    object (ChargeUnderLimit)
  },
  "insufficientFunds": {
    object (InsufficientFunds)
  },
  "accountDoesNotSupportCurrency": {
    object (AccountDoesNotSupportCurrency)
  },
  "accountClosed": {
    object (AccountClosed)
  },
  "accountClosedAccountTakenOver": {
    object (AccountClosedAccountTakenOver)
  },
  "accountOnHold": {
    object (AccountOnHold)
  },
  "accountClosedFraud": {
    object (AccountClosedFraud)
  },
  "googlePaymentTokenInvalidatedByUser": {
    object (GooglePaymentTokenInvalidatedByUser)
  },
  "tokenRefreshRequired": {
    object (TokenRefreshRequired)
  },
  "riskDeclined": {
    object (RiskDeclined)
  }
  // End of list of possible types for union field result.
}
Fields

Union field result.

result can be only one of the following:

success

object (Empty)

Successful reservation.

chargeExceedsTransactionLimit

object (ChargeExceedsTransactionLimit)

This reservation request's amount exceeds per-transaction limit.

chargeExceedsDailyLimit

object (ChargeExceedsDailyLimit)

This account cannot be used for purchases right now as it has exceeded its daily limits.

chargeExceedsMonthlyLimit

object (ChargeExceedsMonthlyLimit)

This account cannot be used for purchases right now as it has exceeded its monthly limits.

chargeUnderLimit

object (ChargeUnderLimit)

This reservation request's amount does not meet the minimum transaction amount.

insufficientFunds

object (InsufficientFunds)

This account does not have sufficient funds to guarantee this reservation.

accountDoesNotSupportCurrency

object (AccountDoesNotSupportCurrency)

This account does not support the requested currency.

accountClosed

object (AccountClosed)

The user's account held with the integrator has been closed.

Returning this value will cause the user's instrument to be closed with Google. The user will be forced to add a new instrument by going through the association flow again.

accountClosedAccountTakenOver

object (AccountClosedAccountTakenOver)

The user's account with the integrator has been closed, suspected account take over.

Returning this value will cause the user's instrument to be closed with Google. The user will be forced to add a new instrument by going through the association flow again.

accountOnHold

object (AccountOnHold)

The account is on hold.

accountClosedFraud

object (AccountClosedFraud)

The user's account held with the integrator has been closed because of fraud.

Returning this value will cause the user's instrument to be closed with Google. The user will be forced to add a new instrument by going through the association flow again.

googlePaymentTokenInvalidatedByUser

object (GooglePaymentTokenInvalidatedByUser)

The account is active, but the GPT has been invalidated by the user on the integrator's side.

Returning this value will cause the user's instrument to be closed with Google. The user will be forced to add a new instrument by going through the association flow again.

tokenRefreshRequired

object (TokenRefreshRequired)

Returning this requires the user to go through a refresh flow.

riskDeclined

object (RiskDeclined)

The transaction was declined due to a risk check on the integrator's side.

This is a permanent failure for this payment, but does not cause the user's instrument to be closed at Google.

ChargeExceedsTransactionLimit

JSON representation
{
  "rawResult": {
    object (RawResult)
  },
  "transactionLimit": {
    object (Amount)
  }
}
Fields
rawResult

object (RawResult)

OPTIONAL: Raw result of this reservation. Used to help inform Google's risk engine and analytics. In decline code–mapping situations, data is sometimes lost. The integrator can choose to give Google a raw code. For example, a credit card gateway (the integrator) may use this field to communicate to Google the exact decline code that was received from the VISA network. In that case, the scope would be "visa" and the rawCode would be whatever the VISA network returned.

transactionLimit

object (Amount)

REQUIRED: This is the maximum amount the user could spend on a transaction. This is used for structured, user facing messaging and decline rate analysis.

ChargeExceedsDailyLimit

JSON representation
{
  "rawResult": {
    object (RawResult)
  }
}
Fields
rawResult

object (RawResult)

OPTIONAL: Raw result of this reservation. Used to help inform Google's risk engine and analytics. In decline code–mapping situations, data is sometimes lost. The integrator can choose to give Google a raw code. For example, a credit card gateway (the integrator) may use this field to communicate to Google the exact decline code that was received from the VISA network. In that case, the scope would be "visa" and the rawCode would be whatever the VISA network returned.

ChargeExceedsMonthlyLimit

JSON representation
{
  "rawResult": {
    object (RawResult)
  }
}
Fields
rawResult

object (RawResult)

OPTIONAL: Raw result of this reservation. Used to help inform Google's risk engine and analytics. In decline code–mapping situations, data is sometimes lost. The integrator can choose to give Google a raw code. For example, a credit card gateway (the integrator) may use this field to communicate to Google the exact decline code that was received from the VISA network. In that case, the scope would be "visa" and the rawCode would be whatever the VISA network returned.

ChargeUnderLimit

JSON representation
{
  "rawResult": {
    object (RawResult)
  },
  "minimumTransactionLimit": {
    object (Amount)
  }
}
Fields
rawResult

object (RawResult)

OPTIONAL: Raw result of this reservation. Used to help inform Google's risk engine and analytics. In decline code–mapping situations, data is sometimes lost. The integrator can choose to give Google a raw code. For example, a credit card gateway (the integrator) may use this field to communicate to Google the exact decline code that was received from the VISA network. In that case, the scope would be "visa" and the rawCode would be whatever the VISA network returned.

minimumTransactionLimit

object (Amount)

REQUIRED: This is the minimum amount the user could spend on a transaction.

InsufficientFunds

JSON representation
{
  "rawResult": {
    object (RawResult)
  }
}
Fields
rawResult

object (RawResult)

OPTIONAL: Raw result of this reservation. Used to help inform Google's risk engine and analytics. In decline code–mapping situations, data is sometimes lost. The integrator can choose to give Google a raw code. For example, a credit card gateway (the integrator) may use this field to communicate to Google the exact decline code that was received from the VISA network. In that case, the scope would be "visa" and the rawCode would be whatever the VISA network returned.

AccountDoesNotSupportCurrency

JSON representation
{
  "rawResult": {
    object (RawResult)
  }
}
Fields
rawResult

object (RawResult)

OPTIONAL: Raw result of this reservation. Used to help inform Google's risk engine and analytics. In decline code–mapping situations, data is sometimes lost. The integrator can choose to give Google a raw code. For example, a credit card gateway (the integrator) may use this field to communicate to Google the exact decline code that was received from the VISA network. In that case, the scope would be "visa" and the rawCode would be whatever the VISA network returned.

AccountClosed

JSON representation
{
  "rawResult": {
    object (RawResult)
  }
}
Fields
rawResult

object (RawResult)

OPTIONAL: Raw result of this reservation. Used to help inform Google's risk engine and analytics. In decline code–mapping situations, data is sometimes lost. The integrator can choose to give Google a raw code. For example, a credit card gateway (the integrator) may use this field to communicate to Google the exact decline code that was received from the VISA network. In that case, the scope would be "visa" and the rawCode would be whatever the VISA network returned.

AccountClosedAccountTakenOver

JSON representation
{
  "rawResult": {
    object (RawResult)
  }
}
Fields
rawResult

object (RawResult)

OPTIONAL: Raw result of this reservation. Used to help inform Google's risk engine and analytics. In decline code–mapping situations, data is sometimes lost. The integrator can choose to give Google a raw code. For example, a credit card gateway (the integrator) may use this field to communicate to Google the exact decline code that was received from the VISA network. In that case, the scope would be "visa" and the rawCode would be whatever the VISA network returned.

AccountOnHold

JSON representation
{
  "rawResult": {
    object (RawResult)
  }
}
Fields
rawResult

object (RawResult)

OPTIONAL: Raw result of this reservation. Used to help inform Google's risk engine and analytics. In decline code–mapping situations, data is sometimes lost. The integrator can choose to give Google a raw code. For example, a credit card gateway (the integrator) may use this field to communicate to Google the exact decline code that was received from the VISA network. In that case, the scope would be "visa" and the rawCode would be whatever the VISA network returned.

AccountClosedFraud

JSON representation
{
  "rawResult": {
    object (RawResult)
  }
}
Fields
rawResult

object (RawResult)

OPTIONAL: Raw result of this reservation. Used to help inform Google's risk engine and analytics. In decline code–mapping situations, data is sometimes lost. The integrator can choose to give Google a raw code. For example, a credit card gateway (the integrator) may use this field to communicate to Google the exact decline code that was received from the VISA network. In that case, the scope would be "visa" and the rawCode would be whatever the VISA network returned.

GooglePaymentTokenInvalidatedByUser

JSON representation
{
  "rawResult": {
    object (RawResult)
  }
}
Fields
rawResult

object (RawResult)

OPTIONAL: Raw result of this reservation. Used to help inform Google's risk engine and analytics. In decline code–mapping situations, data is sometimes lost. The integrator can choose to give Google a raw code. For example, a credit card gateway (the integrator) may use this field to communicate to Google the exact decline code that was received from the VISA network. In that case, the scope would be "visa" and the rawCode would be whatever the VISA network returned.

TokenRefreshRequired

JSON representation
{
  "rawResult": {
    object (RawResult)
  }
}
Fields
rawResult

object (RawResult)

OPTIONAL: Raw result of this reservation. Used to help inform Google's risk engine and analytics. In decline code–mapping situations, data is sometimes lost. The integrator can choose to give Google a raw code. For example, a credit card gateway (the integrator) may use this field to communicate to Google the exact decline code that was received from the VISA network. In that case, the scope would be "visa" and the rawCode would be whatever the VISA network returned.

RiskDeclined

JSON representation
{
  "rawResult": {
    object (RawResult)
  }
}
Fields
rawResult

object (RawResult)

OPTIONAL: Raw result of this reservation. Used to help inform Google's risk engine and analytics. In decline code–mapping situations, data is sometimes lost. The integrator can choose to give Google a raw code. For example, a credit card gateway (the integrator) may use this field to communicate to Google the exact decline code that was received from the VISA network. In that case, the scope would be "visa" and the rawCode would be whatever the VISA network returned.