Method: createMandateResultNotification

Notify Google of the result of a mandate creation after a createMandateWithOptionalInstantPayment method call has been made.

The createMandateResult value is idempotent for this createMandateRequestId, so its value cannot be changed by a subsequent call to this method.

If the endpoint encounters an error while processing the request, the endpoint will return HTTP 4xx or 5xx and the HTTP body will either be of type ErrorResponse or contain a generic error (e.g. a message similar to "There was an error. Please try again later.").

The generic error is used in situations where an ErrorResponse with a clear description could be used to help an attacker understand the payment integrator account identifier of other integrators. In these situations, where either the signing key doesn't match, the payment integrator identifier was not found, or the encryption key was unknown, this method will return a generic error. If the request signature could be verified, additional information regarding the error will be returned in an ErrorResponse.

An example request looks like:


{
  "requestHeader": {
    "protocolVersion": {
      "major": 1,
      "minor": 0,
      "revision": 0
    },
    "requestId": "bWVyY2hhbnQgdHJhbnNhY3Rpb24gaWQ",
    "requestTimestamp": "1502220196078"
  },
  "paymentIntegratorAccountId": "InvisiCashIN_INR",
  "paymentIntegratorTransactionId": "5243098752039874502983745",
  "createMandateRequestId": "zXCbyY2hhbnQgdHJhbnNhY3Rpb49qaAH",
  "instantPaymentInfo": {
    "referenceNumber": "referenceNumber",
    "paymentTimestamp": {
      "epochMillis": "1521855969203"
    },
    "paidAmount": {
      "amountMicros": "728000000",
      "currencyCode": "USD"
    }
  },
  "payerInfo": {
    "payerTaxInfo": {
      "brazil": {
        "cnpj": "66818021000127"
      }
    },
    "payerBankAccountIdentifier": {
      "brazilBankAccount": {
        "bankCode": "12345678",
        "branchCode": "1234567890",
        "accountNumber": "1234567890123456"
      }
    }
  },
  "createMandateResult" : {
    "success" : {}
  }
}

An example response looks like:


{
  "responseHeader": {
    "responseTimestamp": "1481900013178"
  },
  "result": {
    "success": {}
  }
}

HTTP request

POST https://vgw.googleapis.com/gsp/refundable-one-time-payment-code-v1/createMandateResultNotification/:PIAID

Request body

The request body contains data with the following structure:

JSON representation 
{
  "requestHeader": {
    object (RequestHeader)
  },
  "paymentIntegratorAccountId": string,
  "paymentIntegratorTransactionId": string,
  "createMandateRequestId": string,
  "instantPaymentInfo": {
    object (InstantPaymentInfo)
  },
  "payerInfo": {
    object (PayerInfo)
  },
  "createMandateResult": {
    object (CreateMandateResult)
  },

  // Union field end_to_end_network_identifier can be only one of the following:
  "pixEndToEndId": string
  // End of list of possible types for union field end_to_end_network_identifier.
}
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.
paymentIntegratorTransactionId

string

OPTIONAL: This identifier is specific to the integrator and is generated by the integrator. This is the identifier by which the integrator knows this transaction.

For convenience, this identifier is included when the payment integrator requests remittanceStatementDetails.
createMandateRequestId

string

REQUIRED: The unique identifier for the mandate that is being created. This is the requestId generated by Google during the createMandateWithOptionalInstantPayment call which this mandate is associated with.

This is a string with a max length of 100 characters and contains only the characters "a-z", "A-Z", "0-9", ":", "-", and "_".
instantPaymentInfo

object (InstantPaymentInfo)

OPTIONAL: Details about the instant payment, if one was made. This field is required only if an instant payment was part of the mandate creation.
payerInfo

object (PayerInfo)

OPTIONAL: Details about the person making the payment. This may include tax information, bank account details, etc.

Providing this information enhances our ability to detect and prevent fraudulent activity by adding Risk checks, making the payment system more secure for one-time payment code form of payment. If this information is not provided, the payment system will still function normally but may not be as secure.
createMandateResult

object (CreateMandateResult)

REQUIRED: The result of this mandate creation.
Union field end_to_end_network_identifier. OPTIONAL: Identifier specific for a newwork. end_to_end_network_identifier can be only one of the following:
pixEndToEndId

string

This ID is created by Banco Central do Brasil (BCB) for the Brazilian instant payment ecosystem (Pix). This ID is used to identify the operation on a transaction, either a payment or a refund.

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 (CreateMandateResultNotificationResponse)
HTTP 4XX / 5XX Status

object (ErrorResponse)

InstantPaymentInfo

Details about an instant payment made during mandate creation.

JSON representation 
{
  "referenceNumber": string,
  "paymentTimestamp": {
    object (Timestamp)
  },
  "paidAmount": {
    object (Amount)
  }
}
Fields
referenceNumber

string

REQUIRED: The reference number associated with the instant payment, if one was made. This field is required only if an instant payment was part of the mandate creation.

For legacy integrations, this is the referenceNumber of the generateReferenceNumber call for this transaction.

For new integrations, this is the printableString of the generateReferenceNumber call for this transaction. If the generateReferenceNumber call doesn't contain printableString, use the barcodeContents of the generateReferenceNumber call instead.
paymentTimestamp

object (Timestamp)

REQUIRED: The timestamp recorded by the integrator when the user paid this reference number (represented as milliseconds since epoch). This field is required only if an instant payment was part of the mandate creation.
paidAmount

object (Amount)

REQUIRED: The amount actually paid by the user when initiating the mandate. The user should not be allowed to pay a different amount than the instant payment amount sent in the createMandate call, and any cases of the amount mismatching will be treated as a bug requiring investigation. This field supports accurate accounting of how much the user actually paid, independent of what the user should have paid.

CreateMandateResult

Information about the final result of a create mandate.

JSON representation 
{

  // Union field result can be only one of the following:
  "success": {
    object (Empty)
  },
  "userDeclinedMandate": {
    object (UserDeclinedMandate)
  },
  "accountDoesNotSupportMandate": {
    object (AccountDoesNotSupportMandate)
  },
  "createMandateRequestExpired": {
    object (CreateMandateRequestExpired)
  },
  "suspectedFraud": {
    object (SuspectedFraud)
  },
  "accountClosed": {
    object (AccountClosed)
  },
  "accountClosedAccountTakenOver": {
    object (AccountClosedAccountTakenOver)
  },
  "accountClosedFraud": {
    object (AccountClosedFraud)
  },
  "accountOnHold": {
    object (AccountOnHold)
  },
  "insufficientFunds": {
    object (InsufficientFunds)
  },
  "invalidPin": {
    object (InvalidPin)
  },
  "mandateExceedsCountLimit": {
    object (MandateExceedsCountLimit)
  },
  "declinedByIssuer": {
    object (DeclinedByIssuer)
  },
  "osLockFailed": {
    object (OsLockFailed)
  },
  "pinEntryAttemptsExhausted": {
    object (PinEntryAttemptsExhausted)
  },
  "userExitedPaymentFlow": {
    object (UserExitedPaymentFlow)
  },
  "riskDeclined": {
    object (RiskDeclined)
  },
  "mandateCreationFailedChargeSucceeded": {
    object (MandateCreationFailedChargeSucceeded)
  }
  // End of list of possible types for union field result.
}
Fields
Union field result. REQUIRED: The result must contain exactly one of these messages. result can be only one of the following:
success

object (Empty)

The mandate is active and could be used for transactions.
userDeclinedMandate

object (UserDeclinedMandate)

The mandate is declined by the user.
accountDoesNotSupportMandate

object (AccountDoesNotSupportMandate)

User's account held with the integrator is not supported for mandate creation.
createMandateRequestExpired

object (CreateMandateRequestExpired)

The create mandate request has expired. Google will treat this decline as a final state, so the integrator must ensure that the creation doesn't succeed later or that the mandate gets automatically revoked if the creation ends up being successful.
suspectedFraud

object (SuspectedFraud)

The integrator has reason to suspect that this transaction is fraudulent.
accountClosed

object (AccountClosed)

User's account held with the integrator has been closed. This return value will cause the user's instrument to be closed with Google. The user will be forced to add a new instrument.
accountClosedAccountTakenOver

object (AccountClosedAccountTakenOver)

User's account with the integrator has been closed, suspected account take over. This return value will cause the user's instrument to be closed with Google. The user will be forced to add a new instrument.
accountClosedFraud

object (AccountClosedFraud)

User's account held with the integrator has been closed because of fraud. This return value will cause the user's instrument to be closed with Google. The user will be forced to add a new instrument.
accountOnHold

object (AccountOnHold)

User's account is on hold.
insufficientFunds

object (InsufficientFunds)

This account does not have sufficient funds needed to create this mandate.
invalidPin

object (InvalidPin)

The user supplied an invalid PIN.
mandateExceedsCountLimit

object (MandateExceedsCountLimit)

User's account cannot be used to create a mandate right now as it has exceeded its limit for the number of mandates.
declinedByIssuer

object (DeclinedByIssuer)

This decline code should never be used in steady-state. It is meant as a temporary catch-all code to use when the integrator encounters an unknown decline code from the underlying issuer of the user's instrument. This result code can be used while the integrator determines a more appropriate result code to use or negotiates the addition of a new result code to this specification.

Importantly, this decline code is very much a real decline. It is a permanent decline as far as Google is concerned. If the integrator returns this, it is up to them to track down what the issuer's code really means and refund the user if it turns out the code actually meant SUCCESS.

If this decline code is used for the same underlying decline code for more than a certain number of days, Google will treat it as a bug and track it accordingly with respect to any contractual penalties around fixing bugs.
osLockFailed

object (OsLockFailed)

This payment flow requires an OS lock challenge and the user failed to unlock the device.
pinEntryAttemptsExhausted

object (PinEntryAttemptsExhausted)

This payment flow requires user PIN entry. The user failed PIN entry enough times that they ran out of retries.
userExitedPaymentFlow

object (UserExitedPaymentFlow)

User canceled the whole payment attempt (either at the OS lock or at the PIN entry screen).
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.
mandateCreationFailedChargeSucceeded

object (MandateCreationFailedChargeSucceeded)

This decline code is for the case when the mandate creation failed but the instant payment associated with the mandate succeeded.

UserDeclinedMandate

This mandate is declined by the user.

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

object (RawResult)

OPTIONAL: Raw result of this event. 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.

AccountDoesNotSupportMandate

This account does not support mandate creation.

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

object (RawResult)

OPTIONAL: Raw result of this event. 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.

CreateMandateRequestExpired

The create mandate request has expired. Google will treat this decline as a final state, so the integrator must ensure that the creation doesn't succeed later or that the mandate gets automatically revoked if the creation ended up succeeding.

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

object (RawResult)

OPTIONAL: Raw result of this event. 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 rawcode. 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.

SuspectedFraud

The integrator has reason to suspect that this transaction is fraudulent.

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

object (RawResult)

OPTIONAL: Raw result of this event. 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 rawcode. 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

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

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

object (RawResult)

OPTIONAL: Raw result of this event. 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

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

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

object (RawResult)

OPTIONAL: Raw result of this event. 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

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

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

object (RawResult)

OPTIONAL: Raw result of this event. 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

The account is on hold.

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

object (RawResult)

OPTIONAL: Raw result of this event. 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.

InsufficientFunds

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

JSON representation 
{
  "rawResult": {
    object (RawResult)
  },
  "currentBalance": {
    object (Amount)
  },
  "remedyMethod": {
    object (RemedyMethod)
  }
}
Fields
rawResult

object (RawResult)

OPTIONAL: Raw result of this event. 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.
currentBalance

object (Amount)

OPTIONAL: This is the current available balance for the account. If provided, this value will be included in user-facing messaging.
remedyMethod

object (RemedyMethod)

OPTIONAL: This is the remedy method to be applied for the user to help with the insufficient funds issue.

RemedyMethod

Remedy method for InsufficientFunds.

JSON representation 
{

  // Union field remedy_method can be only one of the following:
  "topUp": {
    object (Empty)
  }
  // End of list of possible types for union field remedy_method.
}
Fields
Union field remedy_method. REQUIRED: Oneof remedy method for InsufficientFunds. remedy_method can be only one of the following:
topUp

object (Empty)

This account does not have sufficient funds to guarantee this transfer. The user should be recommended to top-up.

InvalidPin

The user supplied an invalid PIN.

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

object (RawResult)

OPTIONAL: Raw result of this event. 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 rawcode. 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.

MandateExceedsCountLimit

User's account cannot be used to create a mandate right now as it has exceeded its limit for the number of mandates.

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

object (RawResult)

OPTIONAL: Raw result of this event. 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 rawcode. 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.

DeclinedByIssuer

This decline code should never be used in steady-state. It is meant as a temporary catch-all code to use when the integrator encounters an unknown decline code from the underlying issuer of the user's instrument. This result code can be used while the integrator determines a more appropriate result code to use or negotiates the addition of a new result code to this specification.

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

object (RawResult)

OPTIONAL: Raw result of this event. 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 rawcode. 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.

OsLockFailed

This payment flow requires an OS lock challenge and the user failed to unlock the device.

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

object (RawResult)

OPTIONAL: Raw result of this event. 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 rawcode. 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.

PinEntryAttemptsExhausted

This payment flow requires user PIN entry. The user failed PIN entry enough times that they ran out of retries.

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

object (RawResult)

OPTIONAL: Raw result of this event. 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 rawcode. 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.

UserExitedPaymentFlow

User canceled the whole payment attempt.

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

object (RawResult)

OPTIONAL: Raw result of this event. 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 rawcode. 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

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

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

object (RawResult)

OPTIONAL: Raw result of this event. 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.

MandateCreationFailedChargeSucceeded

Mandate creation failed but the instant payment associated with the mandate succeeded.

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

object (RawResult)

OPTIONAL: Raw result of this event. 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.

CreateMandateResultNotificationResponse

Response object for the createMandateResultNotification method.

JSON representation 
{
  "responseHeader": {
    object (ResponseHeader)
  },
  "result": {
    object (CreateMandateResultNotificationResult)
  }
}
Fields
responseHeader

object (ResponseHeader)

REQUIRED: Common header for all responses.
result

object (CreateMandateResultNotificationResult)

REQUIRED: Result of this call.

CreateMandateResultNotificationResult

Result codes for the createMandateResultNotification method.

JSON representation 
{

  // Union field result can be only one of the following:
  "success": {
    object (Empty)
  }
  // End of list of possible types for union field result.
}
Fields
Union field result. REQUIRED: The result must contain exactly one of these messages. result can be only one of the following:
success

object (Empty)

Create mandate result notification was successfully processed.