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)
  },
  "additionalAuthenticationContext": {
    object (AdditionalAuthenticationContext)
  }
}
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.
additionalAuthenticationContext

object (AdditionalAuthenticationContext)

OPTIONAL: Contains additional information relevant to processing the authentication.

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

Redirect URL authentication information.

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.

NativeOtp

Native OTP authentication information.

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.

AdditionalAuthenticationContext

Contains additional authentication information required at the time of authentication.

JSON representation 
{
  "installmentData": {
    object (InstallmentData)
  }
}
Fields
installmentData

object (InstallmentData)

REQUIRED: Contains the installment data for the payment for which authentication is being attempted.

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

A container for the result of the redirectUrl request.

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. REQUIRED: The result of the redirectUrl request. 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. REQUIRED: Whether a redirectUrl would have been supported for this request, or the reason it would not have been supported. 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

The reasons why redirectUrl could not be performed.

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. REQUIRED: The reason redirectUrl could not be performed. 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. REQUIRED: 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

Data for the body of the POST for the redirect.

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

string

REQUIRED: Name of the parameter.
value

string

REQUIRED: Value of the parameter.

BodyEncoding

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

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

A container for the result of the nativeOtp request.

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. REQUIRED: The result of the nativeOtp request. 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

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

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. REQUIRED: Whether a nativeOtp would have been supported for this request, or the reason it would not have been supported. 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

The reasons why nativeOtp could not be performed.

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. REQUIRED: The reason nativeOtp could not be performed. 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

Result codes for NativeOtpResult.

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. REQUIRED: The result of requesting that an OTP be sent to the user. 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.