Pre-initiate integrated authentication requests

Gather the required data before proceeding with the full 3DS authentication and transaction processing.

Pre-initiate an integrated authentication request

POST

/v1/threedsecure/integrated/authentications

Request example

Use this request to pre-initiate an integrated 3D Secure authentication request for a transaction using card details.

{
  "amount": {
    "transactionValue": 29.99,
    "currencyCode": "EUR"
  },
  "fingerprintCallbackUrl": "https://example-merchant.com/3ds-fingerprint-callback",
  "providerId": "provider_123456",
  "requestorAuthenticationIndicator": "01",
  "site": "merchant_site_001",
  "card": {
    "primaryAccountNumber": "4111111111111111",
    "cardHolderName": "John Doe",
    "expiryMonth": 3,
    "expiryYear": 2025,
    "cardVerificationCode": "123"
  }
}

Request parameters

Parameter	Description
`amount` object	Details about the authenticated transaction's amount.
`amount.transactionValue` number required	The amount of the authenticated transaction. Numbers after the decimal will be zero padded if they're less than the expected `currencyCode` exponent.
`amount.currencyCode` string required	The three-character currency code conforming to ISO 4217 standard.
`fingerprintCallbackUrl` string required	The fingerprint callback URL.
`providerId` string (≤ 36 characters)	The unique identifier for the provider that will process the transaction. This field is optional.
`intent` string	The intent of the authentication request. This field is conditionally required: it's required if `providerId` isn't sent, otherwise it's optional. It makes sense to authenticate transactions with the following intents: `Purchase`, `Authorisation`, `EstimatedAuthorisation`, `Verification`. Possible values: `Authorisation` `Purchase` `Payout` `EstimatedAuthorisation` `Verification` `Refund` `Void` `Capture` `Incremental` `StandaloneRefund`
`requestorAuthenticationIndicator` string	The indicator specifying the type of authentication request. Possible values: `01`: Payment transaction `02`: Initial recurring `03`: Initial card-on-file for MITs `04`: Initial card-on-file for CITs `05`: Store card without purchase `06`: Instalment `07`: Billing agreement `08`: Split shipment `09`: Delayed shipment `10`: Split payment
`site` string (≤ 10 characters) required	The site identifier.
`card` object required	Details about the card.
`card.primaryAccountNumber` string (13-19 characters) required	The payment card number.
`card.cardHolderName` string (2-45 characters)	The full name on the card. This field is optional.
`card.expiryMonth` integer (1-12) required	The card expiry month.
`card.expiryYear` integer (2000-9999) required	The card expiry year.
`card.cardVerificationCode` string	The card's 3 or 4 digit security code (CVC/CVV).

Response example

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

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

Response parameters

Parameter	Description
`authenticationId` string (GUID)	The unique reference provided by PXP for the authentication request.
`state` string	The current state of the authentication request. Possible values: `PendingClientData` `AuthenticationSuccessful` `AuthenticationFailed` `AuthenticationRejected` `AuthenticationError` `PendingCustomerChallenge`
`scaMandated` boolean	Whether Strong Customer Authentication (SCA) is mandated for this transaction.
`applicableExemptions` string or null	The exemptions that apply to the transaction from SCA requirements. Possible values: `LVP`: Low Value Payment `TRA`: Transaction Risk Analysis `null`: No exemptions available
`threeDSecureVersion` string	The version of the 3D Secure protocol being used (e.g., `2.1.0`).
`threeDSecureFingerprintUrl` string	The URL to which the 3D Secure method data should be sent.
`threeDSecureFingerprintData` string	The data required for the 3D Secure method. Typically, this is a base64 encoded string.
`threeDSecureSupported` boolean	Whether 3D Secure authentication is supported for this transaction.
`recommendedChallengeIndicator` string or null	The recommended challenge indicator. 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`