Initiate a standalone authentication request

Request

Initiates a standalone 3D Secure authentication request for a transaction. This endpoint is for merchants who use PXP's service solely for authentication purposes. The process involves verifying the cardholder's identity through a browser-based interaction. The request payload must include comprehensive details about the transaction, card information, merchant information, and additional contextual data necessary for the 3D Secure authentication flow. This ensures a secure and efficient authentication process.

Path

authenticationIdstringrequired

The authentication ID.

Bodyapplication/json

fingerprintNotificationstring or null

The URL for notifying the fingerprinting result. Base64 of {"threeDSMethodNotificationURL":"method url value","threeDSServerTransID":"transaction id value"}.

merchantCategoryCodestring or null, = 4 characters

The four-digit Merchant Category Code (MCC) assigned to the merchant.

Example:"5411"

merchantCountryNumericCodestring, = 3 charactersrequired

The three-digit country code of the merchant, following ISO 3166-1 numeric standard.

Example:"840"

merchantLegalNamestring, [ 0 .. 40 ] charactersrequired

The legal name of the merchant.

Example:"ACME Ltd"

acquirerMerchantIdstring, [ 0 .. 35 ] charactersrequired

The acquirer merchant ID.

challengeWindowSizeinteger, (int32), [ 1 .. 5 ]required

The desired size of the challenge window displayed to the cardholder during authentication.

Possible values:

1: 250x400
2: 390x400
3: 500x600
4: 600x400
5: FullScreen

requestorChallengeIndicatorstring or null, [ 0 .. 2 ] charactersrequired

Indicator of whether a challenge is requested for this transaction.

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

challengeCallbackUrlstring, (uri), [ 1 .. 256 ] charactersrequired

The fully qualified URL of the system that receives the CRes message or error message. The CRes message is posted by the ACS through the Cardholder Browser at the end of the challenge and receipt of the RRes message.

recurringobject

Details related to recurring transactions for 3D Secure authentication.

billingAddressobject

Details of the address used in browser-based authentication.

shippingAddressobject

Details of the address used in browser-based authentication.

browserDataobjectrequired

Information about the browser used in the authentication process.

shopperobjectrequired

Details about the shopper involved in the authentication.

curl -i -X PUT \
  'https://api-services.pxp.io/api/v1/threedsecure/standalone/authentications/{authenticationId}/browser-authentication' \
  -H 'Content-Type: application/json' \
  -d '{
    "fingerprintNotification": "string",
    "merchantCategoryCode": "5411",
    "merchantCountryNumericCode": "840",
    "merchantLegalName": "ACME Ltd",
    "acquirerMerchantId": "string",
    "challengeWindowSize": 1,
    "requestorChallengeIndicator": "st",
    "challengeCallbackUrl": "http://example.com",
    "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"
    }
  }'

Responses

Bodyapplication/json

statestring or null

The current state of the authentication request. PendingClientData isn't returned during initiation.

Enum:"AuthenticationSuccessful""AuthenticationFailed""AuthenticationRejected""AuthenticationError""PendingCustomerChallenge"

directoryServerTransactionIdstring or null

The Directory Server transaction ID.

Example:"98ec7e22-04f6-47e9-ab45-5c5d20441935"

transactionStatusstring or null

The status of the transaction.

Possible values include:

Y: AuthenticationVerificationSuccessful
N: NotAuthenticated_NotVerified
U: AuthenticationCouldNotBePerformed
A: AttemptsProcessingPerformed
C: ChallengeRequired
R: AuthenticationRejected
I: InformationalOnly

Enum:"Y""N""U""A""C""R""I"

electronicCommerceIndicatorstring or null

The indicator used to signify the level of security used in the authentication, often used in electronic commerce transactions.

Example:"05"

cardholderAuthenticationVerificationValuestring or null

A value generated during the authentication process to verify the cardholder's identity.

Example:"CAVV1234567890"

exemptionGrantedboolean

Whether an exemption from Strong Customer Authentication (SCA) was granted.

Example:true

exemptionGrantedByIssuerstring or null

Specifies if the exemption was granted by the issuer.

Possible values:

05: TransactionRiskAnalysisExemption
08: TrustListExemption
10: LowValueExemption
11: SecureCorporatePaymentsExemption
79: NoExemptionApplied

Example:

{
  "TransactionRiskAnalysisExemption": {
    "value": 5
  }
}

acsUrlstring or null

The URL of the Access Control Server (ACS) where the cardholder is redirected for challenge authentication.

Example:"https://acs.example.com/challenge"

challengeDatastring or null

Data required for the challenge authentication process, typically a base64 encoded string.

Example:"eyJjaGFsbGVuZ2VEYXRhIjoiQUJDIn0="

stateDataobject

Details about the state. This is returned only when the transactionStatus is different from Y or A.

cardholderInfostring or null

The text provided by the ACS/issuer to the cardholder during a transaction.

Response

{
  "state": "AuthenticationSuccessful",
  "directoryServerTransactionId": "98ec7e22-04f6-47e9-ab45-5c5d20441935",
  "transactionStatus": "Y",
  "electronicCommerceIndicator": "05",
  "cardholderAuthenticationVerificationValue": "CAVV1234567890",
  "exemptionGranted": false,
  "exemptionGrantedByIssuer": "79",
  "cardholderInfo": "Additional authentication information"
}