Skip to content
3DS authentication
/
/
Get 3DS authentication by...

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
Languages
Servers
Production environment
https://api-services.pxp.io/api/v1/
Sandbox environment
https://api-services.test.pxp.io/api/v1/

Standalone authentication

Operations

Pre-initiate a standalone authentication request

Request

Pre-initiates a stand-alone 3D Secure authentication request for a transaction. This endpoint is for merchants who use PXP's service solely for authentication purposes. The pre-initiation step gathers necessary information and ensures that all required data is available and valid before proceeding with the actual authentication request. This process helps to streamline the authentication process and enhance security.

Bodyapplication/json

Request payload for pre-initiating a standalone authentication.

amountobject(authenticationAmounts)

Details about the authenticated transaction's amount.

fingerprintCallbackUrlstringnon-emptyrequired

The fingerprint callback URL.

acquirerProfileIdstring[ 0 .. 20 ] charactersrequired

The unique identifier for the acquirer's profile.

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}}
merchantGroupstring[ 0 .. 10 ] charactersrequired

The merchant group.

cardCard (object) or Gateway token (object) or Scheme token (object) or Scheme token (external) (object)(preinitiationCardData)required
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).

card.​primaryAccountNumberstring[ 13 .. 19 ] charactersrequired

The unique number assigned to a payment card, such as a credit or debit card.

Example: "4111111111111111"
card.​cardHolderNamestring[ 2 .. 45 ] characters

The full name of the individual who owns the payment card, printed on the physical card.

card.​expiryMonthinteger(int32)[ 1 .. 12 ]required

The expiry month [MM] of the card.

Example: 3
card.​expiryYearinteger(int32)[ 2000 .. 9999 ]required

The expiry year [YYYY] of the card.

Example: 2025
card.​cardVerificationCodestring[ 3 .. 4 ] characters

A 3 or 4 digit security code found on the card, used for verification in non-face-to-face transactions.

Example: "123"
curl -i -X POST \
  https://api-services.pxp.io/api/v1/threedsecure/standalone/authentications \
  -H 'Content-Type: application/json' \
  -d '{
    "amount": {
      "transactionValue": 0.1,
      "currencyCode": "EUR"
    },
    "fingerprintCallbackUrl": "string",
    "acquirerProfileId": "string",
    "requestorAuthenticationIndicator": {
      "PaymentTransaction": {
        "value": 1
      }
    },
    "merchantGroup": "string",
    "card": {
      "primaryAccountNumber": "4111111111111111",
      "cardHolderName": "string",
      "expiryMonth": 3,
      "expiryYear": 2025,
      "cardVerificationCode": "123"
    }
  }'

Responses

OK

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

The current state of the authentication request.

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

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

Example: true
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

Whether 3D Secure authentication is supported for this transaction.

Example: true
recommendedChallengeIndicatorstring or null

The recommended challenge indicator.

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

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)(challengeWindowSizeProperty)[ 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(requestorChallengeIndicatorProperty)[ 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(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 colour 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

Whether the browser has Java enabled.

Example: true
browserData.​javaScriptEnabledbooleanrequired

Whether the browser has JavaScript enabled.

Example: true
browserData.​languagestring[ 0 .. 8 ] charactersrequired

The IETF BCP 47 language tag.

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/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

OK

Bodyapplication/json
statestring or null(authenticationStateEnum)

The current state of the authentication request.

Enum"PendingClientData""AuthenticationSuccessful""AuthenticationFailed""AuthenticationRejected""AuthenticationError""PendingCustomerChallenge"
transactionStatusstring or null(transactionStatusEnum)

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

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

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
application/json
{
  "state": "PendingClientData",
  "transactionStatus": "Y",
  "electronicCommerceIndicator": "05",
  "cardholderAuthenticationVerificationValue": "CAVV1234567890",
  "exemptionGranted": true,
  "exemptionGrantedByIssuer": {
    "TransactionRiskAnalysisExemption": { … }
  },
  "acsUrl": "https://acs.example.com/challenge",
  "challengeData": "eyJjaGFsbGVuZ2VEYXRhIjoiQUJDIn0=",
  "stateData": {
    "code": "01",
    "reason": "Card authentication failure"
  },
  "cardholderInfo": "string"
}

Get 3DS authentication by ID

Request

This endpoint retrieves the details of a specific 3DS standalone authentication using the authenticationId provided in the path. The service is designed for retrieving authentication records that were created as part of a 3DS verification process.

Path
authenticationIdstringrequired

The authentication ID.

curl -i -X GET \
  'https://api-services.pxp.io/api/v1/threedsecure/standalone/authentications/{authenticationId}'

Responses

OK

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

The current state of the authentication request.

Enum"PendingClientData""AuthenticationSuccessful""AuthenticationFailed""AuthenticationRejected""AuthenticationError""PendingCustomerChallenge"
threeDSecureVersionstring or null

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

Example: "2.1.0"
directoryServerTransactionIdstring or null

The Directory Server transaction ID.

cardholderAuthenticationVerificationValuestring or null

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

Example: "CAVV1234567890"
electronicCommerceIndicatorstring or null(electronicCommerceIndicatorProperty)

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

Example: "05"
Response
application/json
{
  "authenticationId": "550e8400-e29b-41d4-a716-446655440000",
  "state": "PendingClientData",
  "threeDSecureVersion": "2.1.0",
  "directoryServerTransactionId": "string",
  "cardholderAuthenticationVerificationValue": "CAVV1234567890",
  "electronicCommerceIndicator": "05"
}

Integrated authentication

Operations
©2025 PXP Financial. PXP Financial Registered Office: The Corn Mill - 1 Roydon Road - Stanstead Abbotts - Hertfordshire - SG12 8XL - United Kingdom Phone +44 2038850598. PXP Financial is Authorised By The Financial Conduct Authority And Our Financial Services Register Number is 504318.