Method: preNotifyUser

Notifies a user of pending transaction for a recurring payment.

This informs the user that a new charge on an existing mandate is pending. This notification must be performed before a new charge and each charge is tied to one notification.

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
    },
    "requestId": "cmVxdWVzdDE",
    "requestTimestamp": {
      "epochMillis": "1481899949606"
    },
    "paymentIntegratorAccountId": "SpeedyPaymentsIndia_INR"
  },
  "notificationNumber": "AdWords1234",
  "notificationDisplayNumber": "Adwords1234",
  "customerReferenceId": "customer57",
  "recurringPaymentReferenceId": "subscription201",
  "mandateId": "MA061B00045154",
  "notificationDate": {
    "year":2021,
    "month":2,
    "day":21
  },
  "dueDate": {
    "year":2021,
    "month":2,
    "day":22
  },
  "debitDate": {
    "year":2021,
    "month":2,
    "day":22
  },
  "amount": {
    "amountMicros": "728000000",
    "currencyCode": "INR"
  },
  "netAmount": {
    "amountMicros": "728000000",
    "currencyCode": "INR"
  },
  "description": "Google TV subscription"
}

An example response looks like:


{
  "responseHeader": {
    "responseTimestamp": {
      "epochMillis": "1481899949611"
    }
  },
  "result": {
    "success": {
      "paymentIntegratorNotificationId": "invoiceid1234"
      }
  }
}

HTTP request

POST https://www.integratorhost.example.com/integrator-base-path/v1/payment-integrator-authenticated-card-fop-api/preNotifyUser

Request body

The request body contains data with the following structure:

JSON representation 
{
  "requestHeader": {
    object (RequestHeader)
  },
  "notificationNumber": string,
  "notificationDisplayNumber": string,
  "customerReferenceId": string,
  "recurringPaymentReferenceId": string,
  "mandateId": string,
  "notificationDate": {
    object (Date)
  },
  "dueDate": {
    object (Date)
  },
  "debitDate": {
    object (Date)
  },
  "amount": {
    object (Amount)
  },
  "netAmount": {
    object (Amount)
  },
  "description": string
}
Fields
requestHeader

object (RequestHeader)

REQUIRED: Common header for all requests.
notificationNumber

string

REQUIRED: A number to associate with the notification for this payment.
notificationDisplayNumber

string

REQUIRED: This number is associated with the notification and can be displayed to the user.`.
customerReferenceId

string

REQUIRED: The Google generated customer reference ID that is associated with the mandate for this recurring payment. It is the same ID that is provided when the mandate creation is requested and is unique to that mandate.
recurringPaymentReferenceId

string

REQUIRED: The Google generated recurring payment ID. It is the same ID that is provided when the mandate creation is requested and is unique to that mandate.
mandateId

string

REQUIRED: The payment integrator generated ID that represents the mandate for this recurring payment. This is returned in the capture call when the recurring payment is first set up.
notificationDate

object (Date)

REQUIRED: Date of when this notification was generated.
dueDate

object (Date)

REQUIRED: Date of when the payment is due.
debitDate

object (Date)

REQUIRED: Date of when the payment will be debited.
amount

object (Amount)

REQUIRED: The amount of the pending payment.
netAmount

object (Amount)

REQUIRED: The current net amount of the payment, including any discount or late payment penalties, if applicable.
description

string

REQUIRED: A brief description of the payment.

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

object (ErrorResponse)

PreNotifyUserResponse

Response object for the payment integrator hosted india-cards-v1.preNotifyUser method.

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

object (ResponseHeader)

REQUIRED: Common header for all responses.
result

object (PreNotifyUserResult)

REQUIRED: Result of this request

PreNotifyUserResult

The result of the PreNotifyUserResponse.

JSON representation 
{

  // Union field pre_notify_user_result_code can be only one of the following:
  "success": {
    object (Success)
  },
  "preNotificationFailed": {
    object (PreNotificationFailed)
  },
  "mandateNotActive": {
    object (Empty)
  },
  "mandateAmountExceeded": {
    object (MandateAmountExceeded)
  },
  "mandateInstrumentNotValid": {
    object (Empty)
  }
  // End of list of possible types for union field pre_notify_user_result_code.
}
Fields
Union field pre_notify_user_result_code. Result codes for preNotifyUser. pre_notify_user_result_code can be only one of the following:
success

object (Success)

The user was or will be notified and the scheduled payment can occur.
preNotificationFailed

object (PreNotificationFailed)

The user could not be notified and a payment should not occur.
mandateNotActive

object (Empty)

The specified mandate is not currently active and can not be used for payments.
mandateAmountExceeded

object (MandateAmountExceeded)

The mandate's amount limit is lower than the proposed charge.
mandateInstrumentNotValid

object (Empty)

The instrument associated with the mandate on the integrator side is not valid. For example, when a mandate is created on card which is not migrated to a cloud token and deleted from the integrator's end.

Success

An object to represent a successful preNotifyUserRequest.

JSON representation 
{
  "paymentIntegratorNotificationId": string
}
Fields
paymentIntegratorNotificationId

string

REQUIRED: A payment integretor created ID for this notification. It will be supplied with the related payment when that payment is made.

PreNotificationFailed

Object used to convey error responses for when the pre notification failed.

JSON representation 
{
  "errorCode": string,
  "errorType": string,
  "errorDescription": string
}
Fields
errorCode

string

REQUIRED: Error code.
errorType

string

REQUIRED: Error type.
errorDescription

string

REQUIRED: Error description.

MandateAmountExceeded

Object used to convey information about a mandate's charge amount if the preNotifyUser was attempting to charge more than the mandate supports.

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

object (Amount)

OPTIONAL: The maximum amount that can be used to charge this mandate.