Method: createMandateWithOptionalInstantPayment

Initiates a mandate creation on the user's account with the integrator. An instant payment is optional, but if the instant payment amount is provided in the request, the payment must be successfully completed to activate the mandate.

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": "InvisiCashUSA_USD",
  "mandateName": "Google - Music",
  "mandateDescription": "Monthly subscription for Google - Music",
  "startDate": {
    "epochMillis": "1502220194077"
  },
  "endDate": {
    "epochMillis": "1502220196000"
  },
  "maximumAmount": {
    "amountMicros": "728000000",
    "currencyCode": "USD"
  },
  "firstPaymentDetails": {
    "instantPaymentAmount": {
      "amountMicros": "728000000",
      "currencyCode": "USD"
    }
  },
  "frequency": "MONTHLY",
  "userInfo": {
    "brazilUserInfo": {
      "fullName": "John Doe",
      "legalAddress": {
        "addressLine": [
          "123 Main St"
        ],
        "localityName": "San Francisco",
        "administrativeAreaName": "CA",
        "postalCodeNumber": "94105",
        "countryCode": "US"
      },
      "cpf": "12345678909"
    }
  }
}

An example response looks like:


{
  "responseHeader": {
    "responseTimestamp": "1481900013178"
  },
  "displayableReferenceNumber": {
    "barcodeWithPrintableString": {
      "printableString": "1122334455",
      "barcodeContents": "aW50ZWdyYXRvciB0cmFuc2FjdGlvbiBpZA"
    }
  },
  "result": {
    "acknowledged": {}
  }
}

HTTP request

POST https://www.integratorhost.example.com/integrator-base-path/refundable-one-time-payment-code-v1/createMandateWithOptionalInstantPayment

Request body

The request body contains data with the following structure:

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

  // 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.
}
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.
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)

OPTIONAL: 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 If provided, the mandate will expire on this date. If not provided, the mandate will not have a specific expiration date.
firstPaymentDetails

object (FirstPaymentDetails)

OPTIONAL: Details about the first payment for the mandate. If this field is provided, an initial payment must be made to activate the mandate.
frequency

enum (Frequency)

REQUIRED: The frequency at which the mandate will be executed.
userInfo

object (UserInfo)

REQUIRED: Information about the user making the request.
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.

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

object (ErrorResponse)

Timestamp

A timestamp object representing a point on the ISO timeline in milliseconds since the Unix epoch.

JSON representation 
{
  "epochMillis": string
}
Fields
epochMillis

string (Int64Value format)

REQUIRED: Milliseconds since the Unix epoch

FirstPaymentDetails

Details about the first payment for the mandate.

JSON representation 
{
  "instantPaymentAmount": {
    object (Amount)
  }
}
Fields
instantPaymentAmount

object (Amount)

OPTIONAL: The amount of the instant payment that the user must pay at the time of mandate creation. This amount is immediately payable and will be processed as part of the mandate setup. If not provided, it's assumed that no instant payment is required.

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!
WEEKLY Mandate will be executed once every week.
MONTHLY Mandate will be executed once every month.
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.

CreateMandateWithOptionalInstantPaymentResponse

Response object for the create mandate with optional instant payment method.

JSON representation 
{
  "responseHeader": {
    object (ResponseHeader)
  },
  "displayableReferenceNumber": {
    object (DisplayableReferenceNumber)
  },
  "result": {
    object (CreateMandateWithOptionalInstantPaymentResult)
  }
}
Fields
responseHeader

object (ResponseHeader)

REQUIRED: Common header for all responses.
displayableReferenceNumber

object (DisplayableReferenceNumber)

REQUIRED: Reference number created by the integrator.
result

object (CreateMandateWithOptionalInstantPaymentResult)

REQUIRED: The result of the create mandate call.

CreateMandateWithOptionalInstantPaymentResult

Result codes for createMandateWithOptionalInstantPayment.create method call.

JSON representation 
{

  // Union field result can be only one of the following:
  "acknowledged": {
    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:
acknowledged

object (Empty)

The mandate creation has been requested and the integrator will do additional steps to determine if the mandate creation was successful or declined. Once the integrator knows the result of the creation, they will inform Google of the result by calling the createMandateResultNotification API.