Skip to content
/
Modify a session

Session service API (1.0.0)

This is an API reference for the Session service.

Download OpenAPI description
session.json
session.yaml
Languages
Servers
Production environment
https://api-services.pxp.io/api/v1/
Sandbox environment
https://api-services.test.pxp.io/api/v1/

Create a session

Request

The Session service 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.

Security
PXP-UST1
Bodyapplication/jsonrequired
merchantstring<= 20 charactersrequired

Your unique merchant identifier, as assigned by PXP.

Example: "MERCHANT-1"
sitestring<= 20 charactersrequired

Your unique site identifier, as assigned by PXP.

Example: "SITE-1"
merchantTransactionIdstring<= 50 charactersrequired

A unique identifier for this transaction.

Example: "TRANSACTION-1"
sessionTimeoutinteger>= 1

The duration of the session, in minutes.

Example: 120
amountsobjectrequired

Details about the transaction amount.

amounts.​currencyCodestring= 3 charactersrequired

The currency code associated with the transaction, in ISO 4217 format.

Example: "EUR"
amounts.​transactionValuenumber>= 0required

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 does not require it (e.g., JPY 1.0).

Example: 30.32
transactionMethodobjectrequired

Details about the transaction method.

transactionMethod.​intentobjectrequired

Details about the intent for different payment methods.

transactionMethod.​intent.​cardstring

The intent for card or Apple Pay transactions.

Enum"Authorisation""Purchase""Verification""EstimatedAuthorisation""Payout"
Example: "EstimatedAuthorisation"
transactionMethod.​intent.​paypalstring

The intent for PayPal transactions.

Enum"Authorisation""Purchase"
Example: "Authorisation"
authorisationboolean

Whether or not to proceed with authorisation.

Example: true
addressVerificationobject

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.

identityVerificationobject

Details about the cardholder's identity. These help in ensuring that the information provided matches the cardholder's details on file.

threeDSecureDataobject

Details about the 3D Secure authentication data from an external authentication process.

curl -i -X POST \
  https://api-services.pxp.io/api/v1/sessions \
  -H 'Authorization: YOUR_API_KEY_HERE' \
  -H 'Content-Type: application/json' \
  -d '{
    "merchant": "MERCHANT-1",
    "site": "SITE-1",
    "merchantTransactionId": "TRANSACTION-1",
    "sessionTimeout": 120,
    "amounts": {
      "currencyCode": "EUR",
      "transactionValue": 30.32
    },
    "transactionMethod": {
      "intent": {
        "card": "EstimatedAuthorisation",
        "paypal": "Authorisation"
      }
    },
    "authorisation": true,
    "addressVerification": {
      "countryCode": "GB",
      "houseNumberOrName": "10 Downing Street",
      "postalCode": "SW1A 2AA"
    },
    "identityVerification": {
      "nameVerification": true
    },
    "threeDSecureData": {
      "threeDSecureVersion": "2.2",
      "electronicCommerceIndicator": "05",
      "cardHolderAuthenticationVerificationValue": "CAVV1234567890",
      "directoryServerTransactionId": "550e8400-e29b-41d4-a716-446655440000",
      "threeDSecureTransactionStatus": "Y"
    }
  }'

Responses

Session created successfully

Bodyapplication/json
sessionIdstring(uuid)required

The unique identifier for the created session.

Example: "f47ac10b-58cc-4372-a567-0e02b2c3d479"
hmacKeystringrequired

The HMAC key generated for securing session communications.

Example: "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6"
encryptionKeystringrequired

A key used for encrypting sensitive session data during communication.

Example: "k8l9m0n1o2p3q4r5s6t7u8v9w0x1y2z"
sessionExpirystring(date-time)required

The timestamp indicating when the session will expire, in ISO 8601 format.

Example: "2025-05-19T13:39:20.3843454Z"
allowedFundingTypesobject

Details about the funding types allowed for this session.

Response
application/json
{
  "sessionId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "hmacKey": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6",
  "encryptionKey": "k8l9m0n1o2p3q4r5s6t7u8v9w0x1y2z",
  "sessionExpiry": "2025-05-19T13:39:20.3843454Z",
  "allowedFundingTypes": {
    "cards": [ … ],
    "wallets": { … }
  }
}

Modify a session

Request

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

Security
PXP-UST1
Path
sessionIdstring(uuid)required

The unique identifier of the session to modify.

Bodyapplication/jsonrequired
transactionMethodobject

Details about the transaction method.

amountsobject

Details about the transaction amount.

addressVerificationobject

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.

identityVerificationobject

Details about the cardholder's identity. These help in ensuring that the information provided matches the cardholder's details on file.

authenticationboolean

Whether or not to proceed with authentication.

Example: true
authorisationboolean

Whether or not to proceed with authorisation.

Example: true
threeDSecureDataobject

Details about the 3D Secure authentication data from an external authentication process.

curl -i -X PATCH \
  'https://api-services.pxp.io/api/v1/session-details/{sessionId}' \
  -H 'Authorization: YOUR_API_KEY_HERE' \
  -H 'Content-Type: application/json' \
  -d '{
    "amounts": {
      "currencyCode": "EUR",
      "transactionValue": 20
    },
    "transactionMethod": {
      "intent": {
        "card": "EstimatedAuthorisation",
        "paypal": "Authorisation"
      }
    },
    "authentication": true,
    "authorisation": true,
    "threeDSecureData": {
      "threeDSecureVersion": "2.2",
      "electronicCommerceIndicator": "05",
      "cardHolderAuthenticationVerificationValue": "CAVV1234567890",
      "directoryServerTransactionId": "550e8400-e29b-41d4-a716-446655440000",
      "threeDSecureTransactionStatus": "Y"
    }
  }'

Responses

Session modified successfully

Response
No content
©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.