Method: createMandate

Initiates a mandate creation on the user's account with the integrator.

The requestId within the header is the idempotency key and uniquely identifies this transaction. All subsequent operations on this mandate will populate the mandateId field from the request.

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": "GWVyY2hhbnQgdHJhbnNhY3Rpb24gaWQ",
    "requestTimestamp": "1502220196077"
  },
  "paymentIntegratorAccountId": "InvisiCashIN_INR",
  "googlePaymentToken": "ZXhhbXBsZSB1bmlxdWUgcGF5bWVudCB0b2tlbiB2YWx1ZQ",
  "mandateId": "Gbsdfju4bnQgdHJXPFWSDhgdka4",
  "mandateName": "Google - Music",
  "mandateDescription": "Monthly subscription for Google - Music",
  "startDate": {
    "epochMillis": "1502220194077"
  },
  "endDate": {
    "epochMillis": "1502220196000"
  },
  "maximumAmount": {
    "amountMicros": "728000000",
    "currencyCode": "INR"
  },
  "frequency": "MONTHLY",
  "otpVerification": {
    "sendOtpRequestId" : "G112YZH4bnQgdHJXPdV88J",
    "otp": "1234"
  }
}

An example response looks like:


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

HTTP request

POST https://www.integratorhost.example.com/integrator-base-path/e-wallets-v1/createMandate

Request body

The request body contains data with the following structure:

JSON representation 
{
  "requestHeader": {
    object (RequestHeader)
  },
  "paymentIntegratorAccountId": string,
  "mandateId": string,
  "mandateName": string,
  "mandateDescription": string,
  "startDate": {
    object (Timestamp)
  },
  "endDate": {
    object (Timestamp)
  },
  "frequency": enum (Frequency),

  // Union field fopDetails can be only one of the following:
  "googlePaymentToken": string
  // End of list of possible types for union field fopDetails.

  // Union field mandate_amount can be only one of the following:
  "fixedAmount": {
    object (Amount)
  },
  "maximumAmount": {
    object (Amount)
  }
  // End of list of possible types for union field mandate_amount.

  // Union field account_verification can be only one of the following:
  "otpVerification": {
    object (OtpVerification)
  }
  // End of list of possible types for union field account_verification.
}
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.
mandateId

string

REQUIRED: The mandate id that will represent this mandate for all future operations.
mandateName

string

REQUIRED: The name of the mandate to be displayed to the user. This could be treated like a title of the mandate for the user. This format can be changed without notice and must never be parsed.
mandateDescription

string

REQUIRED: A description of the mandate that can be displayed to the user. This would be an informative explanation of the mandate for the user. This format can be changed without notice and must never be parsed.
startDate

object (Timestamp)

REQUIRED: The start date of the mandate to be created. This is represented as a Timestamp.

This is the first millisecond of the day (in UTC) of the mandate start, 00:00:00.000
endDate

object (Timestamp)

REQUIRED: The end date of the mandate to be created. This is represented as a Timestamp.

This is the first millisecond of the day (in UTC) of the mandate end, 00:00:00.000
frequency

enum (Frequency)

REQUIRED: The frequency at which the mandate will be executed.
Union field fopDetails. REQUIRED: Details regarding the form of payment for which the mandate needs to be created. fopDetails can be only one of the following:
googlePaymentToken

string

This is the token that both companies will use to identify the account for purchases between each other.
Union field mandate_amount. REQUIRED: The amount for which the mandate needs to be created. mandate_amount can be only one of the following:
fixedAmount

object (Amount)

A fixed amount that would be deducted on every recurrence. Every subsequent transaction on this mandate will be for this amount.
maximumAmount

object (Amount)

A maximum amount up to which can be deducted on every recurrence. Subsequent transactions on this mandate could be of any amount less than or equal to this amount.
Union field account_verification. OPTIONAL: Verification mechanism for this mandate creation. account_verification can be only one of the following:
otpVerification

object (OtpVerification)

Data necessary to verify an OTP generated from sendOtp. This is only present if the user went through the sendOtp path.

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

object (ErrorResponse)

Frequency

This is the frequency which governs the recurrence of the mandate. The mandate should be expected to be executed according to this schedule.

Enums
FREQUENCY_UNSPECIFIED Do not ever set this default value!
DAILY Mandate will be executed once every day.
WEEKLY Mandate will be executed once every week.
BIWEEKLY Mandate will be executed once every two weeks.
MONTHLY Mandate will be executed once every month.
BIMONTHLY Mandate will be executed once every two months.
QUARTERLY Mandate will be executed once every three months.
HALF_YEARLY Mandate will be executed once every 6 months.
YEARLY Mandate will be executed once every year.
AD_HOC Mandate will be executed whenever the payee requests. Also called "as-presented" for some networks.

CreateMandateResponse

Response object for the create mandate method.

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

object (ResponseHeader)

REQUIRED: Common header for all responses.
result

enum (CreateMandateResultCode)

REQUIRED: The result of the create mandate call.

CreateMandateResultCode

Result codes for createMandate.create method call.

Enums
CREATE_MANDATE_RESULT_CODE_UNSPECIFIED Do not ever set this default value!
SUCCESS The mandate is active and could be used for transactions.
ACCOUNT_DOES_NOT_SUPPORT_MANDATE User's account held with the integrator is not supported for mandate creation.
OTP_NOT_MATCHED OTP did not match what the integrator sent.
OTP_ALREADY_USED OTP was already used.
OTP_LIMIT_REACHED User has requested or tried to verify too many OTPs.
OTP_EXPIRED OTP has already expired.
SUSPECTED_FRAUD The integrator has reason to suspect that this transaction is fraudulent.
ACCOUNT_CLOSED 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.
ACCOUNT_CLOSED_ACCOUNT_TAKEN_OVER 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.
ACCOUNT_CLOSED_FRAUD 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.
ACCOUNT_ON_HOLD User's account is on hold.
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.