- HTTP request
- Request body
- Response body
- ReserveFundsContext
- Address
- ReserveFundsResponse
- ReserveFundsResultCode
- InstallmentPlan
- InstallmentPlanType
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 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 (cancelFundsReservation
, captureFundsReservation
) populate the requestId
value in their reserveFundsRequestId
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 looks like:
{
"requestHeader": {
"protocolVersion": {
"major": 1,
"minor": 0,
"revision": 0
},
"requestId": "bWVyY2hhbnQgdHJhbnNhY3Rpb24gaWQ",
"requestTimestamp": "1502220196077"
},
"paymentIntegratorAccountId": "InvisiCashUSA_USD",
"googlePaymentToken": "ZXhhbXBsZSB1bmlxdWUgcGF5bWVudCB0b2tlbiB2YWx1ZQ",
"transactionDescription": "Google - Music",
"currencyCode": "INR",
"amount": "728000000",
"reserveFundsContext": {
"userIpAddress":"2001:4860:4860::8888",
"shippingAddress": {
"name": "Example Customer",
"addressLine": ["123 Main St"],
"localityName": "Springfield",
"administrativeAreaName": "CO",
"postalCodeNumber": "80309",
"countryCode": "US"
}
}
}
An example response looks like:
{
"responseHeader": {
"responseTimestamp": "1481900013178"
},
"result": "SUCCESS",
"paymentIntegratorTransactionId": "aW50ZWdyYXRvciB0cmFuc2FjdGlvbiBpZA",
"expirationTimestamp": "1481900033178",
"installmentPlan": {
"installmentPlanType": "PAY_IN_3_INSTALLMENTS"
}
}
HTTP request
POST https://www.integratorhost.example.com/integrator-base-path/redirect-payment-token-v1/reserveFunds
Request body
The request body contains data with the following structure:
JSON representation |
---|
{ "requestHeader": { object ( |
Fields | |
---|---|
request |
REQUIRED: Common header for all requests. |
payment |
REQUIRED: This is the payment integrator account identifier that identifies contractual constraints around this transaction. |
google |
REQUIRED: This is the token that both companies will use to identify the account for purchases between each other. |
transaction |
REQUIRED: This is the description of the transaction that can be put on the customer's statement. Localized to the userLocale found in the |
currency |
REQUIRED: ISO 4217 3-letter currency code |
amount |
REQUIRED: The amount of the purchase, in micros of the currency unit. |
reserve |
REQUIRED: Context about this funds reservation. |
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 |
|
ReserveFundsContext
This object provides context about how the funds reservation was requested.
JSON representation |
---|
{
"userIpAddress": string,
"shippingAddress": {
object ( |
Fields | |
---|---|
user |
OPTIONAL: This is the IP address of the user's device if the purchase was made by a user in session. If the user was not in session this will empty. If the particular contract doesn't stipulate the need for this field it will always be empty. |
shipping |
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 |
OPTIONAL: Customer's full name. |
address |
OPTIONAL: This holds unstructured Address text. |
locality |
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. |
administrative |
OPTIONAL: Top-level administrative subdivision of this country" Examples: US state, IT region, CN province, JP prefecture." |
postal |
OPTIONAL: Despite the name, postalCodeNumber values are frequently alphanumeric. Examples: "94043", "SW1W", "SW1W 9TQ". |
country |
OPTIONAL: Customer address country code, expected to be ISO-3166-1 Alpha-2. |
ReserveFundsResponse
Response object for the funds reservation method.
JSON representation |
---|
{ "responseHeader": { object ( |
Fields | |
---|---|
response |
REQUIRED: Common header for all responses. |
payment |
REQUIRED: This identifier is specific to the integrator and is generated by the integrator. This is the identifier that the integrator knows this transaction by. |
result |
REQUIRED: Result of this funds reservation. |
raw |
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 This value is required if the |
transaction |
OPTIONAL: If Result is This must be a limit relative to the |
expiration |
REQUIRED: The expiration timestamp for this funds reservation represented as milliseconds since epoch. |
installment |
OPTIONAL: Information about the installment plan that this funds reservation is associated with. This field is required if the funds reservation is associated with an installment or financing plan. This information may be used to calculate processor fees. |
ReserveFundsResultCode
Result codes for funds reservation.
Enums | |
---|---|
RESERVE_FUNDS_RESULT_CODE_UNSPECIFIED |
Do not ever set this default value! |
SUCCESS |
Successful reservation. |
CHARGE_EXCEEDS_TRANSACTION_LIMIT |
This reservation request's amount exceeds per-transaction limit. If this code is used populate the transactionLimit field for user messaging purposes. |
CHARGE_EXCEEDS_DAILY_LIMIT |
This account cannot be used for purchases right now as it has exceeded its daily limits. |
CHARGE_EXCEEDS_MONTHLY_LIMIT |
This account cannot be used for purchases right now as it has exceeded its monthly limits. |
CHARGE_UNDER_LIMIT |
This reservation request's amount does not meet the minimum transaction amount. |
INSUFFICIENT_FUNDS |
This account does not have sufficient funds to guarantee this reservation. |
ACCOUNT_DOES_NOT_SUPPORT_CURRENCY |
This account does not support the requested currency. |
ACCOUNT_CLOSED |
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. |
ACCOUNT_CLOSED_ACCOUNT_TAKEN_OVER |
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. |
ACCOUNT_ON_HOLD |
The account is on hold. |
ACCOUNT_CLOSED_FRAUD |
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. |
GOOGLE_PAYMENT_TOKEN_INVALIDATED_BY_USER |
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. |
TOKEN_REFRESH_REQUIRED |
Returning this requires the user to go through a refresh flow. |
RISK_DECLINED |
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. |
InstallmentPlan
Information about an installment plan.
JSON representation |
---|
{
"installmentPlanType": enum ( |
Fields | |
---|---|
installment |
REQUIRED: The installment plan type. |
InstallmentPlanType
The type of the installment plan
Enums | |
---|---|
INSTALLMENT_PLAN_TYPE_UNSPECIFIED |
Do not ever set this default value! |
TERM_LOAN_24_MONTHS |
A 24 month long term loan |
PAY_IN_3_INSTALLMENTS |
An installment plan paid in 3 installments |
PAY_IN_4_INSTALLMENTS |
An installment plan paid in 4 installments |
PAY_IN_6_INSTALLMENTS |
An installment plan paid in 6 installments |
PAY_IN_9_INSTALLMENTS |
An installment plan paid in 9 installments |
PAY_IN_12_INSTALLMENTS |
An installment plan paid in 12 installments |
PAY_IN_18_INSTALLMENTS |
An installment plan paid in 18 installments |
PAY_IN_36_INSTALLMENTS |
An installment plan paid in 36 installments |
PAY_NOW |
A one-installment plan paid immediately |
PAY_30_DAYS_LATER |
A one-installment plan paid 30 days later |