3DS authentication

3D Secure authentication service API (1.0.0)

This is an API reference for the 3D Secure authentication service.

Download OpenAPI description

three-d-secure-authentication.json

three-d-secure-authentication.yaml

Servers

Production environment

https://api-services.pxp.io/api/v1/

Sandbox environment

https://api-services.test.pxp.io/api/v1/

Standalone authentication

Operations

Integrated authentication

Operations

Pre-initiate an integrated authentication request

Request

Pre-initiates an integrated 3D Secure authentication request for a transaction. In integrated mode, PXP processes the transaction in a separate initiate transaction request using the 3D Secure supplied data. This step ensures that all required data is gathered and validated before the full authentication process, facilitating a smoother and more secure transaction flow.

Bodyapplication/json

amountobject(authenticationAmounts)

Details about the authenticated transaction's amount.

fingerprintCallbackUrlstringnon-emptyrequired

The fingerprint callback URL.

acquirerProfileIdstring[ 0 .. 36 ] charactersrequired

The unique identifier for the acquirer's profile.

Example: "acquirer_123456"

providerIdstring[ 0 .. 36 ] charactersrequired

The unique identifier for the provider.

Example: "provider_123456"

requestorAuthenticationIndicatorstring or null[ 0 .. 2 ] characters

Indicator used to specify the type of authentication request, such as payment authentication or account verification.

Possible values:

01: Payment transaction
02: Initial Recurring Transaction
03: Initial Card-on-file transaction for subsequent MITs
04: Initial Card-on-file transaction for subsequent CITs
05: Store card details without purchase (card verification)
06: Instalment transaction
07: Billing agreement
08: Split shipment
09: Delayed shipment
10: Split payment

Example: {"PaymentTransaction":{"value":1}}

sitestring[ 0 .. 10 ] charactersrequired

cardDataCard (object) or Gateway token (object) or Scheme token (object) or Scheme token (external) (object)(preinitiationCardData)

Details related to the card used for 3D Secure authentication. You can provide card details directly, use a stored gateway token, or use a scheme token.

One of:

Use full card details for authentication. This option requires the primary account number, expiry date, cardholder name, and optionally, the card verification code (CVC).

curl -i -X POST \
  https://api-services.pxp.io/api/v1/threedsecure/integrated/authentications \
  -H 'Content-Type: application/json' \
  -d '{
    "amount": {
      "transactionValue": 0.1,
      "currencyCode": "EUR"
    },
    "fingerprintCallbackUrl": "string",
    "acquirerProfileId": "acquirer_123456",
    "providerId": "provider_123456",
    "requestorAuthenticationIndicator": {
      "PaymentTransaction": {
        "value": 1
      }
    },
    "site": "string",
    "cardData": {
      "card": {
        "primaryAccountNumber": "4111111111111111",
        "holderName": "string",
        "expiryMonth": "03",
        "expiryYear": "2025",
        "cardVerificationCode": "123"
      }
    }
  }'

Responses

Bodyapplication/json

authenticationIdstring or null

A unique reference provided by PXP for the authentication request, represented as a GUID.

Example: "550e8400-e29b-41d4-a716-446655440000"

statestring or null

Current state of the authentication request, indicating the status of the pre-initiation process.

Enum"PendingClientData""AuthenticationSuccessful""AuthenticationFailed""AuthenticationRejected""AuthenticationError""PendingCustomerChallenge"

scaMandatedboolean

Indicates whether Strong Customer Authentication (SCA) is mandated for this transaction.

Example: true

applicableExemptionsstring or null

Specifies any exemptions that apply to the transaction from SCA requirements.

Enum"LVP""TRA"

threeDSecureVersionstring or null

The version of the 3D Secure protocol being used for the authentication.

Example: "2.1.0"

threeDSecureFingerprintUrlstring or null

The URL to which the 3D Secure method data should be sent.

Example: "https://example.com/3ds-method"

threeDSecureFingerprintDatastring or null

Data required for the 3D Secure method, typically a base64 encoded string.

Example: "eyJ0aHJlZURTU2VjdXJlTWV0aG9kRGF0YSI6IlhYWiJ9"

threeDSecureSupportedboolean

Indicates whether 3D Secure authentication is supported for this transaction.

Example: true

recommendedChallengeIndicatorstring or null

Response

application/json

{
  "authenticationId": "550e8400-e29b-41d4-a716-446655440000",
  "state": "PendingClientData",
  "scaMandated": true,
  "applicableExemptions": "LVP",
  "threeDSecureVersion": "2.1.0",
  "threeDSecureFingerprintUrl": "https://example.com/3ds-method",
  "threeDSecureFingerprintData": "eyJ0aHJlZURTU2VjdXJlTWV0aG9kRGF0YSI6IlhYWiJ9",
  "threeDSecureSupported": true,
  "recommendedChallengeIndicator": "string"
}

Initiate an integrated authentication request

Request

Authenticates an integrated 3D Secure transaction request. In integrated mode, PXP processes the transaction in conjunction with the 3D Secure authentication data. This ensures that the transaction is authenticated securely, leveraging the full authentication data collected during the pre-initiation phase. 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.

Path

authenticationIdstringrequired

The authentication ID.

Bodyapplication/json

fingerprintNotificationstring or null

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

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"

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

Example: {"500x600":{"value":3}}

requestorChallengeIndicatorstring[ 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

Example: {"NoPreference":{"value":1}}

challengeCallbackUrlstring(uri)[ 1 .. 256 ] charactersrequired

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(recurringData)

Details related to recurring transactions for 3D Secure authentication.

billingAddressobject(browserAuthenticationAddressRequest)

Details of the address used in browser-based authentication.

shippingAddressobject(browserAuthenticationAddressRequest)

Details of the address used in browser-based authentication.

browserDataobject(browserAuthenticationBrowserInformationRequest)required

Information about the browser used in the authentication process.

browserData.acceptHeaderstring[ 0 .. 2048 ] charactersrequired

The Accept HTTP header field from the browser.

Example: "text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,*/*;q=0.8"

browserData.colorDepthinteger(int32)required

The color depth of the browser's screen, measured in bits per pixel.

Example: 24

browserData.ipAddressstring or null[ 0 .. 45 ] characters

The IP address of the device running the browser, if available.

Example: "192.168.1.1"

browserData.javaEnabledbooleanrequired

Indicates whether the browser has Java enabled.

Example: true

browserData.javaScriptEnabledbooleanrequired

Indicates whether the browser has JavaScript enabled.

Example: true

browserData.languagestring[ 0 .. 8 ] charactersrequired

IETF BCP 47 language tag is used

Example: "en-US"

browserData.screenHeightinteger(int32)required

The height of the browser's screen in pixels.

Example: 1080

browserData.screenWidthinteger(int32)required

The width of the browser's screen in pixels.

Example: 1920

browserData.timeZoneOffsetInMinutesinteger(int32)required

The difference, in minutes, between UTC and the local time of the browser.

Example: -420

browserData.userAgentstring[ 0 .. 2048 ] charactersrequired

The User-Agent string of the browser.

Example: "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/91.0.4472.124 Safari/537.36"

shopperobject(browserAuthenticationCardholderInformationRequest)required

Details about the shopper involved in the authentication.

shopper.emailstring or null[ 0 .. 254 ] characters

The email address of the shopper.

Example: "johndoe@example.com"

shopper.homePhoneNumberstring or null^\d{1,3}-\d{1,15}$

The home phone number of the shopper.

Example: "+1234567890"

shopper.mobilePhoneNumberstring or null^\d{1,3}-\d{1,15}$

The mobile phone number of the shopper.

Example: "+0987654321"

shopper.workPhoneNumberstring or null^\d{1,3}-\d{1,15}$

The work phone number of the shopper.

Example: "+1123456789"

curl -i -X PUT \
  'https://api-services.pxp.io/api/v1/threedsecure/integrated/authentications/{authenticationId}/browser-authentication' \
  -H 'Content-Type: application/json' \
  -d '{
    "fingerprintNotification": "string",
    "merchantCountryNumericCode": "840",
    "merchantLegalName": "ACME ltd",
    "challengeWindowSize": {
      "500x600": {
        "value": 3
      }
    },
    "requestorChallengeIndicator": {
      "NoPreference": {
        "value": 1
      }
    },
    "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

uniqueIdstring or null

statestring or null

Current state of the authentication request, indicating the status of the authentication process.

Enum"PendingClientData""AuthenticationSuccessful""AuthenticationFailed""AuthenticationRejected""AuthenticationError""PendingCustomerChallenge"

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

Example: {"AuthenticationVerificationSuccessful":{"value":"Y"}}

electronicCommerceIndicatorstring or null

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

Example: "05"

exemptionGrantedboolean

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

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(stateDataResponse)

Details about the state.

cardholderInfostring or null

Text provided by the ACS/Issuer to the Cardholder during a transaction.

Response

application/json

{
  "uniqueId": "string",
  "state": "PendingClientData",
  "transactionStatus": {
    "AuthenticationVerificationSuccessful": { … }
  },
  "electronicCommerceIndicator": "05",
  "exemptionGranted": true,
  "exemptionGrantedByIssuer": {
    "TransactionRiskAnalysisExemption": { … }
  },
  "acsUrl": "https://acs.example.com/challenge",
  "challengeData": "eyJjaGFsbGVuZ2VEYXRhIjoiQUJDIn0=",
  "stateData": {
    "code": "string",
    "reason": "string"
  },
  "cardholderInfo": "string"
}

3D Secure authentication service API (1.0.0)

Standalone authentication

Integrated authentication

Pre-initiate an integrated authentication request

Request

Responses

Was this helpful?

Initiate an integrated authentication request

Request

Responses

Was this helpful?

3D Secure authentication service API (1.0.0)

Standalone authentication

Integrated authentication

Pre-initiate an integrated authentication request

RequestExpand all

Responses

Was this helpful?

Initiate an integrated authentication request

RequestExpand all

Responses

Was this helpful?

Request

Request