Initiate standalone authentication requests

Complete the 3D Secure authentication process by providing detailed transaction and browser data.

Initiate a standalone authentication request

PUT

/v1/threedsecure/standalone/authentications/{authenticationId}/browser-authentication

Request example

Use this request to initiates the browser-based authentication phase of a standalone 3D Secure authentication request. The response will indicate whether additional customer challenges are required or if the authentication is complete.

The more data points are submitted, the better chances the cardholder has for a frictionless authentication.

curl -i -X PUT \
  'https://api-services.pxp.io/api/v1/threedsecure/standalone/authentications/550e8400-e29b-41d4-a716-446655440000/browser-authentication' \
  -H 'Content-Type: application/json' \
  -d '{
    "fingerprintNotification": "eyJ0aHJlZURTTWV0aG9kTm90aWZpY2F0aW9uVVJMIjoiaHR0cHM6Ly9leGFtcGxlLmNvbS8zZHMtbm90aWZpY2F0aW9uIiwidGhyZWVEU1NlcnZlclRyYW5zSUQiOiIxMjM0NTY3OC05YWJjIn0=",
    "merchantCategoryCode": "5411",
    "merchantCountryNumericCode": "840",
    "merchantLegalName": "ACME Ltd",
    "acquirerMerchantId": "ACME_MERCHANT_001",
    "challengeWindowSize": 3,
    "requestorChallengeIndicator": "01",
    "challengeCallbackUrl": "https://example-merchant.com/3ds-challenge-callback",
    "recurring": {
      "expirationDate": "2024-12-31T23:59:59Z",
      "frequencyInDays": 30
    },
    "billingAddress": {
      "city": "San Francisco",
      "countryNumericCode": "840",
      "line1": "123 Market St",
      "line2": "Apt 456",
      "line3": "Building B",
      "postalCode": "94105",
      "stateCode": "CA"
    },
    "shippingAddress": {
      "city": "San Francisco",
      "countryNumericCode": "840",
      "line1": "123 Market St",
      "line2": "Apt 456",
      "line3": "Building B",
      "postalCode": "94105",
      "stateCode": "CA"
    },
    "browserData": {
      "acceptHeader": "text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,*/*;q=0.8",
      "colorDepth": 24,
      "ipAddress": "192.168.1.1",
      "javaEnabled": true,
      "javaScriptEnabled": true,
      "language": "en-US",
      "screenHeight": 1080,
      "screenWidth": 1920,
      "timeZoneOffsetInMinutes": -420,
      "userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/91.0.4472.124 Safari/537.36"
    },
    "shopper": {
      "email": "johndoe@example.com",
      "homePhoneNumber": "+1234567890",
      "mobilePhoneNumber": "+0987654321",
      "workPhoneNumber": "+1123456789"
    }
  }'

Path parameters

Parameter	Description
`authenticationId` string required	The authentication ID from the pre-initiation step.

Body parameters

Parameter	Description
`fingerprintNotification` string	URL for notifying the fingerprinting result. Base64 encoded string containing threeDSMethodNotificationURL and threeDSServerTransID.
`merchantCategoryCode` string (4 characters)	The four-digit Merchant Category Code (MCC) assigned to the merchant.
`merchantCountryNumericCode` string (3 characters) required	The three-digit country code of the merchant, in ISO 3166-1 format.
`merchantLegalName` string (≤ 40 characters) required	The legal name of the merchant.
`acquirerMerchantId` string (≤ 35 characters) required	The acquirer merchant ID.
`challengeWindowSize` integer required	The desired size of the challenge window. Possible values: `1`: 250x400 `2`: 390x400 `3`: 500x600 `4`: 600x400 `5`: FullScreen
`requestorChallengeIndicator` string required	Indicator of whether a challenge is requested. Possible values: `01`: `NoPreference` `02`: `NoChallengeRequested` `03`: `ChallengeRequested3dsRequestorPreference` `04`: `ChallengeRequestedMandate` `05`: `NoChallengeRequestedTRAPerformed` `06`: `NoChallengeRequestedDataShareOnly` `07`: `NoChallengeRequestedStrongConsumerAuthentication` `08`: `NoChallengeRequestedTrustListExemption` `09`: `ChallengeRequestedTrustListPrompt` `10`: `NoChallengeRequestedLowValueExemption` `11`: `NoChallengeRequestedSecureCorporatePayment` `12`: `ChallengeRequestedDeviceBindingPrompt` `13`: `ChallengeRequestedIssuerRequested` `14`: `ChallengeRequestedMerchantInitiatedTransactions`
`challengeCallbackUrl` string (≤ 256 characters) required	The fully qualified URL that receives the CRes message or Error Message.
`recurring` object	Details related to recurring transactions.
`recurring.expirationDate` string	The expiration date of the recurring transaction plan, in ISO 8601 format.
`recurring.frequencyInDays` integer	The frequency of the recurring transactions in days.
`billingAddress` object	Billing address details.
`billingAddress.city` string (≤ 50 characters)	The city of the address.
`billingAddress.countryNumericCode` string (3 characters)	The numeric country code following ISO 3166-1 numeric standard.
`billingAddress.line1` string (≤ 50 characters)	The first line of the address, typically street address or PO Box.
`billingAddress.line2` string (≤ 50 characters)	The second line of the address for additional information.
`billingAddress.line3` string (≤ 50 characters)	The third line of the address for additional information.
`billingAddress.postalCode` string (≤ 16 characters)	The postal code of the address.
`billingAddress.stateCode` string (≤ 3 characters)	The state or province of the address.
`shippingAddress` object	Shipping address details.
`shippingAddress.city` string (≤ 50 characters)	The city of the address.
`shippingAddress.countryNumericCode` string (3 characters)	The numeric country code following ISO 3166-1 numeric standard.
`shippingAddress.line1` string (≤ 50 characters)	The first line of the address, typically street address or PO Box.
`shippingAddress.line2` string (≤ 50 characters)	The second line of the address for additional information.
`shippingAddress.line3` string (≤ 50 characters)	The third line of the address for additional information.
`shippingAddress.postalCode` string (≤ 16 characters)	The postal code of the address.
`shippingAddress.stateCode` string (≤ 3 characters)	The state or province of the address.
`browserData` object required	Information about the browser used in the authentication process.
`browserData.acceptHeader` string (≤ 2048 characters) required	The Accept HTTP header field from the browser.
`browserData.colorDepth` integer required	The color depth of the browser's screen, measured in bits per pixel.
`browserData.ipAddress` string (≤ 45 characters)	The IP address of the device running the browser.
`browserData.javaEnabled` boolean required	Indicates whether the browser has Java enabled.
`browserData.javaScriptEnabled` boolean required	Indicates whether the browser has JavaScript enabled.
`browserData.language` string (≤ 8 characters) required	IETF BCP 47 language tag.
`browserData.screenHeight` integer required	The height of the browser's screen in pixels.
`browserData.screenWidth` integer required	The width of the browser's screen in pixels.
`browserData.timeZoneOffsetInMinutes` integer required	The difference, in minutes, between UTC and the local time of the browser.
`browserData.userAgent` string (≤ 2048 characters) required	The User-Agent string of the browser.
`shopper` object required	Details about the shopper involved in the authentication.
`shopper.email` string (≤ 254 characters)	The email address of the shopper.
`shopper.homePhoneNumber` string	The home phone number of the shopper.
`shopper.mobilePhoneNumber` string	The mobile phone number of the shopper.
`shopper.workPhoneNumber` string	The work phone number of the shopper.

Response example

If your request is successful, you'll receive a 200 response.

{
  "state": "AuthenticationSuccessful",
  "transactionStatus": "Y",
  "electronicCommerceIndicator": "05",
  "cardholderAuthenticationVerificationValue": "CAVV1234567890",
  "exemptionGranted": false,
  "exemptionGrantedByIssuer": "",
  "acsUrl": "https://acs.issuerbank.com/challenge",
  "challengeData": "eyJjaGFsbGVuZ2VEYXRhIjoiQUJDIn0=",
  "stateData": {
    "code": "01",
    "reason": "Authentication completed successfully"
  },
  "cardholderInfo": "Authentication successful - no additional verification required"
}

Response parameters

Parameter	Description
`state` string	The current state of the authentication request. Possible values: `PendingClientData` `AuthenticationSuccessful` `AuthenticationFailed` `AuthenticationRejected` `AuthenticationError` `PendingCustomerChallenge`
`transactionStatus` string	The status of the transaction. Possible values: `Y`: `AuthenticationVerificationSuccessful` `N`: `NotAuthenticated_NotVerified` `U`: `AuthenticationCouldNotBePerformed` `A`: `AttemptsProcessingPerformed` `C`: `ChallengeRequired` `R`: `AuthenticationRejected` `I`: `InformationalOnly`
`electronicCommerceIndicator` string	The indicator used to signify the level of security used in the authentication, often used in electronic commerce transactions.
`cardholderAuthenticationVerificationValue` string	A value generated during the authentication process to verify the cardholder's identity (CAVV).
`exemptionGranted` boolean	Whether an exemption from Strong Customer Authentication (SCA) was granted.
`exemptionGrantedByIssuer` string	Specifies if the exemption was granted by the issuer. Possible values: `05`: `TransactionRiskAnalysisExemption` `08`: `TrustListExemption` `10`: `LowValueExemption` `11`: `SecureCorporatePaymentsExemption` `79`: `NoExemptionApplied`
`acsUrl` string	The URL of the Access Control Server (ACS) where the cardholder is redirected for challenge authentication.
`challengeData` string	Data required for the challenge authentication process, typically a base64 encoded string.
`stateData` object	Details about the state.
`stateData.code` string	The state code. Possible values include numbers from 01 to 30.
`stateData.reason` string	The state reason.
`cardholderInfo` string	The text provided by the ACS/issuer to the cardholder during a transaction.