Sessions API

Securely collect payment details and initiate a transaction.

Overview

The Sessions API enables the creation of transaction sessions, supporting various transaction methods such as card payments and alternative payment methods (APMs). It facilitates seamless integration for payment processing by generating a session that securely collects payment details and initiates transactions. This service ensures secure and efficient payment flows, improving the user experience across multiple payment channels.

Create a session

POST

/v1/sessions

This endpoint requires PXP-UST1 authentication.

Request example

Use the following request to create a session.

{
  "merchant": "MERCHANT-1",
  "site": "SITE-1",
  "merchantTransactionId": "TRANSACTION-1",
  "sessionTimeout": 120,
  "transactionMethod": {
    "intent": {
      "card": "EstimatedAuthorisation",
      "paypal": "Authorisation"
    }
  },
  "amounts": {
    "currencyCode": "EUR",
    "transactionValue": 30.32
  }
}

Parameter	Description
`merchant` string (≤ 20 characters) required	Your unique merchant identifier, as assigned by PXP.
`site` string (≤ 20 characters) required	Your unique site identifier, as assigned by PXP.
`merchantTransactionId` string (≤ 50 characters) required	A unique identifier for this transaction.
`sessionTimeout` number	The duration of the session, in minutes.
`transactionMethod` object required	Details about the transaction method.
`transactionMethod.intent` object required	Details about the intent for different payment methods.
`transactionMethod.intent.card` string	The intent for card or Apple Pay transactions. Possible values: `Authorisation` `Purchase` `Verification` `EstimatedAuthorisation` `Payout`
`transactionMethod.intent.paypal` string	The intent for PayPal transactions. Possible values: `Authorisation` `Purchase`
`amounts` object required	Details about the transaction amount.
`amounts.currencyCode` string (3 characters) required	The currency code associated with the transaction, in ISO 4217 format.
`amounts.transactionValue` number required	The transaction amount. 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 (e.g., GBP 1.234), or if a decimal is supplied when the `currencyCode` of the exponent doesn't require it (e.g., JPY 1.0).
`authorisation` boolean	Whether or not to proceed with authorisation.
`addressVerification` object	Details about the cardholder's address. These help in the validation and fraud prevention process by matching the provided address with the cardholder's address on file.
`addressVerification.countryCode` string (≤ 2 characters)	The country associated with the cardholder's address, in ISO 3166-1 alpha-2 format.
`addressVerification.houseNumberOrName` string (≤ 100 characters)	The house number or name associated with the cardholder's address.
`addressVerification.postalCode` string (≤ 10 characters)	The postal code of the cardholder's address.
`identityVerification` object	Details about the cardholder's identity. These help in ensuring that the information provided matches the cardholder's details on file.
`identityVerification.nameVerification` boolean	Whether the cardholder's name matches the name associated with the registered address on file.
`threeDSecureData` object	Details about the 3D Secure authentication data from an external authentication process.
`threeDSecureData.threeDSecureVersion` string (≤ 10 characters)	The 3DS protocol version.
`threeDSecureData.electronicCommerceIndicator` string (≤ 2 characters)	The ECI value indicating the authentication result.
`threeDSecureData.cardHolderAuthenticationVerificationValue` string (≤ 50 characters)	The CAVV value from 3DS authentication.
`threeDSecureData.directoryServerTransactionId` string (≤ 50 characters)	The Directory Server transaction identifier.
`threeDSecureData.threeDSecureTransactionStatus` string (≤ 1 character)	The 3DS transaction status.

Response example

If your request is successful, you'll receive a 200 response containing the session data.

{
  "sessionId": "c5f0799b-0839-43ce-abc5-5b462a98f250",
  "hmacKey": "904bc42395d4af634e2fd48ee8c2c7f52955a1da97a3aa3d82957ff12980a7bb",
  "encryptionKey": "20d175a669ad3f8c195c9c283fc86155",
  "sessionExpiry": "2025-05-19T13:39:20.3843454Z",
  "allowedFundingTypes": {
    "cards": [
      "Visa",
      "Diners",
      "Mastercard",
      "AmericanExpress"
    ],
    "wallets": {
      "paypal": {
        "allowedFundingOptions": [
          "venmo", 
          "paylater", 
          "paypal"
        ]
      },
      "applepay": {}
    }
  }
}

Parameter	Description
`sessionId` string (UUID)	The unique identifier for the newly-created session.
`hmacKey` string	The HMAC key generated for securing session communications.
`encryptionKey` string	A key used for encrypting sensitive session data during communication.
`sessionExpiry` string	The timestamp indicating when the session will expire, in ISO 8601 format.
`allowedFundingTypes` object	Details about the funding types allowed for this session. Possible values: `cards` `wallets`
`allowedFundingTypes.cards` array of strings or null	The list of supported card schemes.
`allowedFundingTypes.wallets` object	Details about the supported wallets.
`allowedFundingTypes.wallets.paypal` object	Details about the PayPal wallet.
`allowedFundingTypes.wallets.paypal.allowedFundingOptions` array of strings or null	The list of supported PayPal wallet options. Possible values: `venmo` `paylater` `paypal`
`allowedFundingTypes.wallets.apple` object	Details about the Apple Pay wallet.
`allowedFundingTypes.wallets.apple.allowedFundingOptions` array of strings or null	The list of supported Apple wallet options.

Modify a session

PATCH

/v1/session-details/{sessionId}

This endpoint allows updating session details after creation, including intent modification, amount updates, authentication decision, authorisation decision, and 3DS external data.

This endpoint requires PXP-UST1 authentication.

Request example

{
  "amounts": {
    "currencyCode": "EUR",
    "transactionValue": 20
  },
  "transactionMethod": {
    "intent": {
      "card": "EstimatedAuthorisation",
      "paypal": "Authorisation"
    }
  },
  "addressVerification": {
    "countryCode": "GB",
    "houseNumberOrName": "10 Downing Street",
    "postalCode": "SW1A 2AA"
  },
  "identityVerification": {
    "nameVerification": true
  },
  "authentication": true,
  "authorisation": true,
  "threeDSecureData": {
    "threeDSecureVersion": "2.2",
    "electronicCommerceIndicator": "05",
    "cardHolderAuthenticationVerificationValue": "CAVV1234567890",
    "directoryServerTransactionId": "550e8400-e29b-41d4-a716-446655440000",
    "threeDSecureTransactionStatus": "Y"
  }
}

Parameters

Parameter	Description
`transactionMethod` object	Details about the transaction method.
`transactionMethod.intent` object	Details about the intent for different payment methods.
`transactionMethod.intent.card` string	The intent for card transactions. Possible values: `Authorisation` `Purchase` `Verification` `EstimatedAuthorisation` `Payout`
`transactionMethod.intent.paypal` string	The intent for PayPal transactions. Possible values: `Authorisation` `Purchase`
`amounts` object	Details about the transaction amount.
`amounts.currencyCode` string (3 characters)	The currency code associated with the transaction, in ISO 4217 format.
`amounts.transactionValue` number	The transaction amount. 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 (e.g., GBP 1.234), or if a decimal is supplied when the `currencyCode` of the exponent doesn't require it (e.g., JPY 1.0).
`addressVerification` object	Details about the cardholder's address. These help in the validation and fraud prevention process by matching the provided address with the cardholder's address on file.
`addressVerification.countryCode` string (≤ 2 characters)	The country associated with the cardholder's address, in ISO 3166-1 alpha-2 format.
`addressVerification.houseNumberOrName` string (≤ 100 characters)	The house number or name associated with the cardholder's address.
`addressVerification.postalCode` string (≤ 10 characters)	The postal code of the cardholder's address.
`identityVerification` object	Details about the cardholder's identity. These help in ensuring that the information provided matches the cardholder's details on file.
`identityVerification.nameVerification` boolean	Whether the cardholder's name matches the name associated with the registered address on file.
`authentication` boolean	Whether or not to proceed with authentication.
`authorisation` boolean	Whether or not to proceed with authorisation.
`threeDSecureData` object	Details about the 3D Secure authentication data from an external authentication process.
`threeDSecureData.threeDSecureVersion` string (≤ 10 characters)	The 3DS protocol version.
`threeDSecureData.electronicCommerceIndicator` string (≤ 2 characters)	The ECI value indicating the authentication result.
`threeDSecureData.cardHolderAuthenticationVerificationValue` string (≤ 50 characters)	The CAVV value from 3DS authentication.
`threeDSecureData.directoryServerTransactionId` string (≤ 50 characters)	The Directory Server transaction identifier.
`threeDSecureData.threeDSecureTransactionStatus` string (≤ 1 character)	The 3DS transaction status.

Response example

If your request is successful, you'll receive a 204 response with no content.

If the request fails, you'll receive a 400 error response.

{
  "errorCode": "SES4001",
  "errorReason": "Session not found.",
  "correlationId": "398a1c0e-329d-4f7b-bbeb-56c201387e40",
  "details": []
}

Parameter	Description
`errorCode` string	The error code identifying the type of error.
`errorReason` string	The human-readable error message.
`correlationId` string	The unique identifier for tracking this request.
`details` array of strings	Additional error details.

Sessions API

Overview

Create a session

Request example

Response example

Modify a session

Request example

Parameters

Response example

Was this helpful?