- HTTP request
- Request body
- Response body
- AuthenticationType
- RedirectUrl
- DeviceInformation
- NativeOtp
- AuthenticateResponse
- RedirectUrlResultCase
- RedirectUrlNotRequested
- RedirectUrlSupport
- RedirectUrlNotSupported
- RedirectUrlNotSupportedReason
- RedirectDetails
- GetRequest
- PostFormRequest
- BodyPair
- BodyEncoding
- NativeOtpResultCase
- NativeOtpNotRequested
- NativeOtpSupport
- NativeOtpNotSupported
- NativeOtpNotSupportedReason
- NativeOtpResult
- NativeOtpResultCode
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 ( |
Fields | |
---|---|
requestHeader |
REQUIRED: Common header for all requests. |
accountDetails |
REQUIRED: Data about the user's payment card. |
amount |
REQUIRED: The amount of the purchase if the authentication is successful. |
requestedAuthenticationTypes |
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 |
|
HTTP 4XX / 5XX Status |
|
AuthenticationType
Defines the possible ways of authenticating a user. At least one type must be requested.
JSON representation |
---|
{ "redirectUrl": { object ( |
Fields | |
---|---|
redirectUrl |
OPTIONAL: Used when requesting authentication by redirect url. |
nativeOtp |
OPTIONAL: Used when requesting authentication by native otp. |
RedirectUrl
JSON representation |
---|
{
"callbackUrl": string,
"deviceInformation": {
object ( |
Fields | |
---|---|
callbackUrl |
REQUIRED: This is the callback URL the user is sent to after completion of the redirect. |
deviceInformation |
OPTIONAL: This is the information about the user's browser that will be loading the |
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 |
REQUIRED: The browser's user agent. |
userIpAddress |
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 ( |
Fields | |
---|---|
smsMatchingToken |
OPTIONAL: A string to be included with the SMS, if possible, so that the device can automatically ingest the token. |
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 ( |
Fields | |
---|---|
responseHeader |
REQUIRED: Common header for all responses. |
paymentIntegratorAuthenticationId |
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 |
REQUIRED: The result of verifying the CVN sent in the request. If the CVN was not set on the request, this value should be |
redirectUrlResultCase |
REQUIRED A container for the result of the |
nativeOtpResultCase |
REQUIRED A container for the result of the |
RedirectUrlResultCase
JSON representation |
---|
{ // Union field |
Fields | |
---|---|
Union field
|
|
redirectUrlNotRequested |
Google did not request authentication by |
redirectUrlNotSupported |
Google requested authentication by |
redirectUrlResult |
Google requested authentication by |
RedirectUrlNotRequested
This is used when a redirectUrl
was not requested.
JSON representation |
---|
{
"redirectUrlSupport": {
object ( |
Fields | |
---|---|
redirectUrlSupport |
REQUIRED: This is used to indicated if a |
RedirectUrlSupport
This is used to specify if a redirectUrl
would have been supported for a particular request.
JSON representation |
---|
{ // Union field |
Fields | |
---|---|
Union field
|
|
notSupportedByPaymentIntegrator |
The payment integrator can not support a |
notSupportedByNetwork |
The network can not support a |
notSupportedByIssuer |
The issuer can not support a |
notEnrolled |
A |
supported |
A |
RedirectUrlNotSupported
This is used when a redirectUrl
was requested but it is unsupported for this request.
JSON representation |
---|
{
"reason": {
object ( |
Fields | |
---|---|
reason |
REQUIRED: Authentication by |
RedirectUrlNotSupportedReason
JSON representation |
---|
{ // Union field |
Fields | |
---|---|
Union field
|
|
notSupportedByPaymentIntegrator |
The integrator could not support |
notSupportedByNetwork |
The network could not support |
notSupportedByIssuer |
The issuer could not support |
notEnrolled |
The user is not enrolled to support |
doNotHonor |
The issuer returned a |
invalidExpiry |
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 |
Fields | |
---|---|
Union field redirect_details . Specifies the type of redirect that will be used. redirect_details can be only one of the following: |
|
getMethod |
The user's browser should be redirected using an HTTPS GET. |
postFormMethod |
The user's browser should be redirected using an HTTPS POST with content time |
GetRequest
This contains details for redirecting the user's browser using an HTTPS GET.
JSON representation |
---|
{ "url": string } |
Fields | |
---|---|
url |
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 ( |
Fields | |
---|---|
url |
REQUIRED: The url the user will be redirected to. Should not exceed 2048 characters in length. |
body[] |
REQUIRED: Data for the body of the POST for the redirect. This list represents the HTTPS POST body. For example:
Would be formatted as this in the POST body:
. |
bodyEncoding |
REQUIRED: The character set used for the body. UTF-8 is recommended. |
BodyPair
JSON representation |
---|
{ "name": string, "value": string } |
Fields | |
---|---|
name |
REQUIRED: Name of the parameter. |
value |
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 |
Fields | |
---|---|
Union field
|
|
nativeOtpNotRequested |
Google did not request authentication by |
nativeOtpNotSupported |
Google requested authentication by |
nativeOtpResult |
Google requested authentication by |
NativeOtpNotRequested
This is used when a nativeOtp
was not requested.
JSON representation |
---|
{
"nativeOtpSupport": {
object ( |
Fields | |
---|---|
nativeOtpSupport |
REQUIRED: If authentication by |
NativeOtpSupport
JSON representation |
---|
{ // Union field |
Fields | |
---|---|
Union field
|
|
notSupportedByPaymentIntegrator |
The payment integrator can not support a |
notSupportedByNetwork |
The network can not support a |
notSupportedByIssuer |
The issuer can not support a |
notEnrolled |
A |
supported |
A |
invalidExpiry |
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 ( |
Fields | |
---|---|
nativeOtpNotSupportedReason |
REQUIRED: Authentication by |
NativeOtpNotSupportedReason
JSON representation |
---|
{ // Union field |
Fields | |
---|---|
Union field
|
|
notSupportedByPaymentIntegrator |
The integrator could not support |
notSupportedByNetwork |
The network could not support |
notSupportedByIssuer |
The issuer could not support |
notEnrolled |
The user is not enrolled to support |
doNotHonor |
The issuer returned a |
NativeOtpResult
This is used when a nativeOtp
was requested and is supported.
JSON representation |
---|
{
"result": {
object ( |
Fields | |
---|---|
result |
REQUIRED: The result of requesting that an OTP be sent to the user. |
NativeOtpResultCode
JSON representation |
---|
{ // Union field |
Fields | |
---|---|
Union field native_otp_result_code . Result codes for NativeOtpResult . native_otp_result_code can be only one of the following: |
|
otpSent |
An OTP has successfully be sent to the user using by the issuer using information they had stored. |