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.

fingerprintCallbackUrlstring, non-emptyrequired

The fingerprint callback URL.

providerIdstring or null, [ 0 .. 36 ] characters

The unique identifier for the provider.

Example:"provider_123456"

intentstring or null

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

Enum:"Authorisation""Purchase""Payout""EstimatedAuthorisation""Verification""Refund""Void""Capture""Incremental""StandaloneRefund"

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:"01"

sitestring, [ 0 .. 10 ] charactersrequired

The site identifier for the merchant.

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).

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",
    "providerId": "provider_123456",
    "intent": "Authorisation",
    "requestorAuthenticationIndicator": "01",
    "site": "string",
    "card": {
      "primaryAccountNumber": "4111111111111111",
      "cardHolderName": "string",
      "expiryMonth": 3,
      "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

The current state of the authentication request. For pre-initiation, this can only be PendingClientData or null (if the card isn't enrolled for 3DS).

Value:"PendingClientData"

scaMandatedboolean

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

Whether 3D Secure authentication is supported for this transaction.

Example:true

recommendedChallengeIndicatorstring or null

The recommended challenge indicator.

Response

{
  "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"
}