# Pre-initiate an integrated authentication 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.

Endpoint: POST /threedsecure/integrated/authentications
Version: 1.0.0

## Request fields (application/json):

  - `amount` (object)
    Details about the authenticated transaction's amount.

  - `amount.transactionValue` (number, required)
    The amount of the authenticated transaction. The numbers after the decimal will be zero padded if they are less than the expected currencyCode exponent. For example, GBP 1.1 = GBP 1.10, EUR 1 = EUR 1.00, or BHD 1.3 = 1.300. The transaction will be rejected if numbers after the decimal are greater than the expected currencyCode exponent, for example, GBP 1.234, or if a decimal is supplied when the currencyCode exponent doesn't require it (e.g., JPY 1.0).

  - `amount.currencyCode` (string, required)
    The currency code associated with the transaction, in ISO 4217 format. This three-character code specifies the currency in which the transaction is processed, ensuring clarity and consistency across international transactions.
    Example: "EUR"

  - `fingerprintCallbackUrl` (string, required)
    The fingerprint callback URL.

  - `providerId` (string,null)
    The unique identifier for the provider.
    Example: "provider_123456"

  - `intent` (string,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"

  - `requestorAuthenticationIndicator` (string,null)
    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"

  - `site` (string, required)
    The site identifier for the merchant.

  - `card` (object, required) — one of:
    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.
    - Card:
      - `primaryAccountNumber` (string, required)
        The unique number assigned to a payment card, such as a credit or debit card.
        Example: "4111111111111111"
      - `cardHolderName` (string)
        The full name of the individual who owns the payment card, printed on the physical card.
      - `expiryMonth` (integer, required)
        The expiry month [MM] of the card.
        Example: 3
      - `expiryYear` (integer, required)
        The expiry year [YYYY] of the card.
        Example: 2025
      - `cardVerificationCode` (string)
        A 3 or 4 digit security code found on the card, used for verification in non-face-to-face transactions.
        Example: "123"
    - Gateway token:
      - `gatewayTokenId` (string, required)
        A securely stored token representing a previously saved card.
        Example: "2357e042-2bf0-4886-8d9d-718fa5909761"
    - Scheme token:
      - `schemeTokenId` (string, required)
        A unique scheme token ID generated by PXP, used as a reference to extract the schemeTokenNumber.
        Example: "4837261112345678"
    - Scheme token (external):
      - `schemeTokenNumber` (string, required)
        An external scheme token issued by Visa or Mastercard.
        Example: "4837261112345678"
      - `holderName` (string)
        The full name of the cardholder associated with the scheme token.
        Example: "Mr John Doe"
      - `expiryMonth` (integer, required)
        The expiry month [MM] of the scheme token.
        Example: 3
      - `expiryYear` (integer, required)
        The expiry year [YYYY] of the scheme token.
        Example: 2025
      - `verificationCode` (string)
        A 3 or 4 digit security code for the scheme token.
        Example: "123"

## Response 200 fields (application/json):

  - `authenticationId` (string,null)
    A unique reference provided by PXP for the authentication request, represented as a GUID.
    Example: "550e8400-e29b-41d4-a716-446655440000"

  - `state` (string,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).
    Enum: "PendingClientData"

  - `scaMandated` (boolean)
    Whether Strong Customer Authentication (SCA) is mandated for this transaction.
    Example: true

  - `applicableExemptions` (string,null)
    Specifies any exemptions that apply to the transaction from SCA requirements.
    Enum: "LVP", "TRA"

  - `threeDSecureVersion` (string,null)
    The version of the 3D Secure protocol being used for the authentication.
    Example: "2.1.0"

  - `threeDSecureFingerprintUrl` (string,null)
    The URL to which the 3D Secure method data should be sent.
    Example: "https://example.com/3ds-method"

  - `threeDSecureFingerprintData` (string,null)
    Data required for the 3D Secure method, typically a base64 encoded string.
    Example: "eyJ0aHJlZURTU2VjdXJlTWV0aG9kRGF0YSI6IlhYWiJ9"

  - `threeDSecureSupported` (boolean)
    Whether 3D Secure authentication is supported for this transaction.
    Example: true

  - `recommendedChallengeIndicator` (string,null)
    The recommended challenge indicator.

## Response 400 fields (application/json):

  - `errorCode` (string,null)

  - `errorReason` (string,null)

  - `correlationId` (string,null)

  - `details` (array,null)