Method: authenticate

Initiates the authentication of a user for a card to make a purchase. This can be accomplished in multiple ways that may or may not be supported for the specified card. The payment integrator attempts to authenticate using all specified methods that are supported by the card.

If NATIVE_OTP is specified within the supportedAuthenticationTypes, the issuer should immediately send an OTP to the cardholder, using the information already on file.

If the endpoint encounters an error while processing the request, the response body from this endpoint should be of type ErrorResponse.

An example request using a physical card looks like:


{
  "requestHeader": {
    "protocolVersion": {
      "major": 1
    },
    "requestId": "G112YZH4XPDV88J",
    "requestTimestamp": {
      "epochMillis": "1481907920000"
    },
    "paymentIntegratorAccountId": "SpeedyPaymentsIndia_INR"
  },
  "accountDetails": {
    "card": {
      "accountNumber": "4123456789101112",
      "nameOnCard": "Example Customer",
      "expiryMonth": "01",
      "expiryYear": "20",
      "cvn": "123"
    }
  },
  "amount": {
    "amountMicros": "728000000",
    "currencyCode": "INR"
  },
  "requestedAuthenticationTypes": {
    "redirectUrl": {
      "callbackUrl": "https://example.google.com/return/url/"
    },
    "nativeOtp": {
      "deviceInformation": {
        "userAgent": "Mozilla/5.0 (WindowsNT10.0)",
        "userIpAddress": "2001:4860:4860::8888"
      }
    }
  }
}

An example request using a tokenized card looks like:


{
  "requestHeader": {
    "protocolVersion": {
      "major": 1
    },
    "requestId": "G112YZH4XPDV88J",
    "requestTimestamp": {
      "epochMillis": "1481907920000"
    },
    "paymentIntegratorAccountId": "SpeedyPaymentsIndia_INR"
  },
  "accountDetails": {
    "paymentToken": {
      "nameOnCard": "Example Customer",
      "paymentTokenAccountNumber": "4123456789101112",
      "expiryMonth": "01",
      "expiryYear": "20",
      "cryptogram": "12345"
    }
  },
  "amount": {
    "amountMicros": "728000000",
    "currencyCode": "INR"
  },
  "requestedAuthenticationTypes": {
    "redirectUrl": {
      "callbackUrl": "https://example.google.com/return/url/"
    },
    "nativeOtp": {
      "deviceInformation": {
        "userAgent": "Mozilla/5.0 (WindowsNT10.0)",
        "userIpAddress": "2001:4860:4860::8888"
      }
    }
  }
}

An example response looks like:


{
  "responseHeader": {
    "responseTimestamp": {
      "epochMillis": 1481907920760
    }
  },
  "paymentIntegratorAuthenticationId": "36be1a5d-ff21-455d-8dba-e3c4306e193e",
  "cvnResult": "CVN_RESULT_NOT_DETERMINED",
  "redirectUrlResultCase": {
    "redirectUrlResult": {
      "getMethod": {
        "url": "https://example.paymentintegratordomain.com/authenitcate/G112YZH4XPDV88J"
      }
    }
  },
  "nativeOtpResultCase": {
    "nativeOtpNotSupported": {
      "nativeOtpNotSupportedReason": {
        "notSupportedByIssuer": {}
      }
    }
  }
}

HTTP request

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

Request body

The request body contains data with the following structure:

JSON representation 
{
  "requestHeader": {
    object (RequestHeader)
  },
  "accountDetails": {
    object (AccountDetails)
  },
  "amount": {
    object (Amount)
  },
  "requestedAuthenticationTypes": {
    object (AuthenticationType)
  }
}
Fields
requestHeader

object (RequestHeader)

REQUIRED: Common header for all requests.
accountDetails

object (AccountDetails)

REQUIRED: Data about the user's payment card.
amount

object (Amount)

REQUIRED: The amount of the purchase if the authentication is successful.
requestedAuthenticationTypes

object (AuthenticationType)

REQUIRED: The types of authentication methods being requested.

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

object (ErrorResponse)

AuthenticationType

Defines the possible ways of authenticating a user. At least one type must be requested.

JSON representation 
{
  "redirectUrl": {
    object (RedirectUrl)
  },
  "nativeOtp": {
    object (NativeOtp)
  }
}
Fields
redirectUrl

object (RedirectUrl)

OPTIONAL: Used when requesting authentication by redirect url.
nativeOtp

object (NativeOtp)

OPTIONAL: Used when requesting authentication by native otp.

RedirectUrl

JSON representation 
{
  "callbackUrl": string,
  "deviceInformation": {
    object (DeviceInformation)
  }
}
Fields
callbackUrl

string

REQUIRED: This is the callback URL the user is sent to after completion of the redirect.
deviceInformation

object (DeviceInformation)

OPTIONAL: This is the information about the user's browser that will be loading the url sent in the RedirectUrlResult. If this information is provided it can be used in generating the redirectUrl. For instance, the userAgent can be used to custimize a page that matches the user's browser and the ipAddress can be used to verify that the correct user is being redirected.

DeviceInformation

Contains information about the user's device. It is sent when available and required in the current context. For example, it can be used to provide a better user experience by redirecting the user to a URL optimized for their device.

JSON representation 
{
  "userAgent": string,
  "userIpAddress": string
}
Fields
userAgent

string

REQUIRED: The browser's user agent.
userIpAddress

string

OPTIONAL: This is the IP address of the user's device if the purchase was made by a user in session. This can be either IPv4 or IPv6 version. If the particular contract doesn't stipulate the need for this field, it will always be empty.

NativeOtp

JSON representation 
{
  "smsMatchingToken": string,
  "deviceInformation": {
    object (DeviceInformation)
  }
}
Fields
smsMatchingToken

string

OPTIONAL: A string to be included with the SMS, if possible, so that the device can automatically ingest the token.
deviceInformation

object (DeviceInformation)

OPTIONAL: This is the information about the user's device where this transaction was initiated. This field is present only when it is required for generating the OTP. If the particular contract does not stipulate the need for this field, it will always be empty.

AuthenticateResponse

Response object for the payment integrator hosted authenticate method.

JSON representation 
{
  "responseHeader": {
    object (ResponseHeader)
  },
  "paymentIntegratorAuthenticationId": string,
  "cvnResult": enum (CvnResult),
  "redirectUrlResultCase": {
    object (RedirectUrlResultCase)
  },
  "nativeOtpResultCase": {
    object (NativeOtpResultCase)
  }
}
Fields
responseHeader

object (ResponseHeader)

REQUIRED: Common header for all responses.
paymentIntegratorAuthenticationId

string

OPTIONAL: This identifier is specific to the integrator and is generated by the integrator. The integrator identifies this authentication attempt in their system by this identifier.
cvnResult

enum (CvnResult)

REQUIRED: The result of verifying the CVN sent in the request. If the CVN was not set on the request, this value should be NOT_SENT.
redirectUrlResultCase

object (RedirectUrlResultCase)

REQUIRED A container for the result of the redirectUrl request.
nativeOtpResultCase

object (NativeOtpResultCase)

REQUIRED A container for the result of the nativeOtp request.

RedirectUrlResultCase

JSON representation 
{

  // Union field redirect_url_result_case can be only one of the following:
  "redirectUrlNotRequested": {
    object (RedirectUrlNotRequested)
  },
  "redirectUrlNotSupported": {
    object (RedirectUrlNotSupported)
  },
  "redirectUrlResult": {
    object (RedirectDetails)
  }
  // End of list of possible types for union field redirect_url_result_case.
}
Fields

Union field redirect_url_result_case.

redirect_url_result_case can be only one of the following:
redirectUrlNotRequested

object (RedirectUrlNotRequested)

Google did not request authentication by redirectUrl so nothing could be done.
redirectUrlNotSupported

object (RedirectUrlNotSupported)

Google requested authentication by redirectUrl but it is not supported.
redirectUrlResult

object (RedirectDetails)

Google requested authentication by redirectUrl and this is the result.

RedirectUrlNotRequested

This is used when a redirectUrl was not requested.

JSON representation 
{
  "redirectUrlSupport": {
    object (RedirectUrlSupport)
  }
}
Fields
redirectUrlSupport

object (RedirectUrlSupport)

REQUIRED: This is used to indicated if a redirectUrl would have been supported if it had been requested.

RedirectUrlSupport

This is used to specify if a redirectUrl would have been supported for a particular request.

JSON representation 
{

  // Union field redirect_url_support can be only one of the following:
  "notSupportedByPaymentIntegrator": {
    object (Empty)
  },
  "notSupportedByNetwork": {
    object (Empty)
  },
  "notSupportedByIssuer": {
    object (Empty)
  },
  "notEnrolled": {
    object (Empty)
  },
  "supported": {
    object (Empty)
  }
  // End of list of possible types for union field redirect_url_support.
}
Fields

Union field redirect_url_support.

redirect_url_support can be only one of the following:
notSupportedByPaymentIntegrator

object (Empty)

The payment integrator can not support a redirectUrl for this request.
notSupportedByNetwork

object (Empty)

The network can not support a redirectUrl for this request.
notSupportedByIssuer

object (Empty)

The issuer can not support a redirectUrl for this request.
notEnrolled

object (Empty)

A redirectUrl is not supported for this request because the card has not been enrolled.
supported

object (Empty)

A redirectUrl is supported for this request.

RedirectUrlNotSupported

This is used when a redirectUrl was requested but it is unsupported for this request.

JSON representation 
{
  "reason": {
    object (RedirectUrlNotSupportedReason)
  }
}
Fields
reason

object (RedirectUrlNotSupportedReason)

REQUIRED: Authentication by redirectUrl was requested, but it could not be performed for the following reason.

RedirectUrlNotSupportedReason

JSON representation 
{

  // Union field redirect_url_not_supported_reason can be only one of the
  // following:
  "notSupportedByPaymentIntegrator": {
    object (Empty)
  },
  "notSupportedByNetwork": {
    object (Empty)
  },
  "notSupportedByIssuer": {
    object (Empty)
  },
  "notEnrolled": {
    object (Empty)
  },
  "doNotHonor": {
    object (Empty)
  },
  "invalidExpiry": {
    object (Empty)
  }
  // End of list of possible types for union field
  // redirect_url_not_supported_reason.
}
Fields

Union field redirect_url_not_supported_reason.

redirect_url_not_supported_reason can be only one of the following:
notSupportedByPaymentIntegrator

object (Empty)

The integrator could not support redirectUrl for this request.
notSupportedByNetwork

object (Empty)

The network could not support redirectUrl for this request.
notSupportedByIssuer

object (Empty)

The issuer could not support redirectUrl for this request. This would include international cards that don't support the redirectUrl authentication flow.
notEnrolled

object (Empty)

The user is not enrolled to support redirectUrl for this request. This is used for cases where a redirectUrl would have been supported but the user has not yet completed the necessary steps to enable it as a valid option.
doNotHonor

object (Empty)

The issuer returned a DO_NOT_HONOR for this request.
invalidExpiry

object (Empty)

The expiry date for this request is invalid.

RedirectDetails

This contains the result of the redirectUrl request when it is supported.

JSON representation 
{

  // Union field redirect_details can be only one of the following:
  "getMethod": {
    object (GetRequest)
  },
  "postFormMethod": {
    object (PostFormRequest)
  }
  // End of list of possible types for union field redirect_details.
}
Fields
Union field redirect_details. Specifies the type of redirect that will be used. redirect_details can be only one of the following:
getMethod

object (GetRequest)

The user's browser should be redirected using an HTTPS GET.
postFormMethod

object (PostFormRequest)

The user's browser should be redirected using an HTTPS POST with content time x-www-form-urlencoded.

GetRequest

This contains details for redirecting the user's browser using an HTTPS GET.

JSON representation 
{
  "url": string
}
Fields
url

string

REQUIRED: The URL that the user's browser should be redirected to with a GET request. Should not exceed 2048 characters in length.

PostFormRequest

This contains details for redirecting the user's browser using an HTTPS POST.

JSON representation 
{
  "url": string,
  "body": [
    {
      object (BodyPair)
    }
  ],
  "bodyEncoding": enum (BodyEncoding)
}
Fields
url

string

REQUIRED: The url the user will be redirected to. Should not exceed 2048 characters in length.
body[]

object (BodyPair)

REQUIRED: Data for the body of the POST for the redirect.

This list represents the HTTPS POST body. For example:

[ "myParammy": "Val", "otherParam": "otherVal", "repeatedParam": "val1", "repeatedParam": "val2" ]

Would be formatted as this in the POST body:

myParam=myVal&otherParam=otherVal&repeatedParam=val1&repeatedParam= val2

.
bodyEncoding

enum (BodyEncoding)

REQUIRED: The character set used for the body. UTF-8 is recommended.

BodyPair

JSON representation 
{
  "name": string,
  "value": string
}
Fields
name

string

REQUIRED: Name of the parameter.
value

string

REQUIRED: Value of the parameter.

BodyEncoding

Enums
BODY_ENCODING_UNSPECIFIED DO NOT USE
BODY_ENCODING_ISO_8859_1 ISO-8859-1 character set for the POST body
BODY_ENCODING_UTF_8 UTF-8 character set for the POST body
BODY_ENCODING_US_ASCII US-ASCII character set for the POST body

NativeOtpResultCase

JSON representation 
{

  // Union field native_otp_result_case can be only one of the following:
  "nativeOtpNotRequested": {
    object (NativeOtpNotRequested)
  },
  "nativeOtpNotSupported": {
    object (NativeOtpNotSupported)
  },
  "nativeOtpResult": {
    object (NativeOtpResult)
  }
  // End of list of possible types for union field native_otp_result_case.
}
Fields

Union field native_otp_result_case.

native_otp_result_case can be only one of the following:
nativeOtpNotRequested

object (NativeOtpNotRequested)

Google did not request authentication by nativeOtp so nothing could be done.
nativeOtpNotSupported

object (NativeOtpNotSupported)

Google requested authentication by nativeOtp but native OTP is not supported.
nativeOtpResult

object (NativeOtpResult)

Google requested authentication by nativeOtp and this is the result.

NativeOtpNotRequested

This is used when a nativeOtp was not requested.

JSON representation 
{
  "nativeOtpSupport": {
    object (NativeOtpSupport)
  }
}
Fields
nativeOtpSupport

object (NativeOtpSupport)

REQUIRED: If authentication by nativeOtp was requested, the following support would have been available.

NativeOtpSupport

JSON representation 
{

  // Union field native_otp_support can be only one of the following:
  "notSupportedByPaymentIntegrator": {
    object (Empty)
  },
  "notSupportedByNetwork": {
    object (Empty)
  },
  "notSupportedByIssuer": {
    object (Empty)
  },
  "notEnrolled": {
    object (Empty)
  },
  "supported": {
    object (Empty)
  },
  "invalidExpiry": {
    object (Empty)
  }
  // End of list of possible types for union field native_otp_support.
}
Fields

Union field native_otp_support.

native_otp_support can be only one of the following:
notSupportedByPaymentIntegrator

object (Empty)

The payment integrator can not support a nativeOtp for this request.
notSupportedByNetwork

object (Empty)

The network can not support a nativeOtp for this request.
notSupportedByIssuer

object (Empty)

The issuer can not support a nativeOtp for this request.
notEnrolled

object (Empty)

A nativeOtp is not supported for this request because the card has not been enrolled.
supported

object (Empty)

A nativeOtp is supported for this request.
invalidExpiry

object (Empty)

The expiry date for this request is invalid.

NativeOtpNotSupported

This is used when a nativeOtp was requested but it is not supported for this request.

JSON representation 
{
  "nativeOtpNotSupportedReason": {
    object (NativeOtpNotSupportedReason)
  }
}
Fields
nativeOtpNotSupportedReason

object (NativeOtpNotSupportedReason)

REQUIRED: Authentication by nativeOtp was requested, but it could not be performed for the following reason.

NativeOtpNotSupportedReason

JSON representation 
{

  // Union field native_otp_not_supported_reason can be only one of the
  // following:
  "notSupportedByPaymentIntegrator": {
    object (Empty)
  },
  "notSupportedByNetwork": {
    object (Empty)
  },
  "notSupportedByIssuer": {
    object (Empty)
  },
  "notEnrolled": {
    object (Empty)
  },
  "doNotHonor": {
    object (Empty)
  }
  // End of list of possible types for union field
  // native_otp_not_supported_reason.
}
Fields

Union field native_otp_not_supported_reason.

native_otp_not_supported_reason can be only one of the following:
notSupportedByPaymentIntegrator

object (Empty)

The integrator could not support nativeOtp for this request.
notSupportedByNetwork

object (Empty)

The network could not support nativeOtp for this request.
notSupportedByIssuer

object (Empty)

The issuer could not support nativeOtp for this request. This would include international cards that don't support the redirectUrl authentication flow.
notEnrolled

object (Empty)

The user is not enrolled to support nativeOtp for this request. This is used for cases where a nativeOtp would have been supported but the user has not yet completed the necessary steps to enable it as a valid option.
doNotHonor

object (Empty)

The issuer returned a DO_NOT_HONOR for this request.

NativeOtpResult

This is used when a nativeOtp was requested and is supported.

JSON representation 
{
  "result": {
    object (NativeOtpResultCode)
  }
}
Fields
result

object (NativeOtpResultCode)

REQUIRED: The result of requesting that an OTP be sent to the user.

NativeOtpResultCode

JSON representation 
{

  // Union field native_otp_result_code can be only one of the following:
  "otpSent": {
    object (Empty)
  }
  // End of list of possible types for union field native_otp_result_code.
}
Fields
Union field native_otp_result_code. Result codes for NativeOtpResult. native_otp_result_code can be only one of the following:
otpSent

object (Empty)

An OTP has successfully be sent to the user using by the issuer using information they had stored.