# 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

/v1/sessions

This endpoint requires PXP-UST1 authentication.

### Request example

Use the following request to create a session.


```json
{
  "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) | Your unique merchant identifier, as assigned by PXP. |
| `site`string (≤ 20 characters) | Your unique site identifier, as assigned by PXP. |
| `merchantTransactionId`string (≤ 50 characters) | A unique identifier for this transaction. |
| `sessionTimeout`number | The duration of the session, in minutes. |
| `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 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 | 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). |
| `allowTransaction`boolean | Whether the transaction is allowed to proceed. If not provided, defaults to `null` (no decision made yet). |
| `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.


```json
{
  "sessionId": "c5f0799b-0839-43ce-abc5-5b462a98f250",
  "hmacKey": "904bc42395d4af634e2fd48ee8c2c7f52955a1da97a3aa3d82957ff12980a7bb",
  "encryptionKey": "20d175a669ad3f8c195c9c283fc86155",
  "sessionExpiry": "2025-05-19T13:39:20.3843454Z",
  "allowedFundingTypes": {
    "cardSchemes": [
      "Diners",
      "Mastercard",
      "American Express",
      "Visa"
    ],
    "cards": [],
    "wallets": {
      "paypal": {
        "allowedFundingOptions": [
          "venmo", 
          "paylater", 
          "paypal"
        ],
        "merchantId": "paypal-merchant-123"
      },
      "applePay": {
        "merchantId": "merchant.com.example"
      },
      "googlePay": {
        "merchantId": "Unity",
        "gatewayMerchantId": "Prime",
        "merchantName": "Prime Team"
      }
    }
  }
}
```

| 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:`cardSchemes``cards``wallets` |
| `allowedFundingTypes.cardSchemes`array of strings | The list of supported card schemes. |
| `allowedFundingTypes.cards`array | The cards allowed for this session. Returns an empty array. |
| `allowedFundingTypes.wallets`object | Details about the supported wallets. |
| `allowedFundingTypes.wallets.paypal`object | Details about the PayPal wallet. |
| `allowedFundingTypes.wallets.paypal.allowedFundingOptions`array of strings | The list of allowed funding options for PayPal. |
| `allowedFundingTypes.wallets.paypal.merchantId`string | The PayPal merchant identifier. |
| `allowedFundingTypes.wallets.applePay`object | Details about the Apple Pay wallet. |
| `allowedFundingTypes.wallets.applePay.merchantId`string | The Apple Pay merchant identifier. |
| `allowedFundingTypes.wallets.googlePay`object | Details about the Google Pay wallet. |
| `allowedFundingTypes.wallets.googlePay.merchantId`string | The Google Pay merchant identifier. |
| `allowedFundingTypes.wallets.googlePay.gatewayMerchantId`string | A unique merchant identifier assigned by PXP. |
| `allowedFundingTypes.wallets.googlePay.merchantName`string | A unique merchant name assigned by PXP. |


## Modify a session

/v1/session-details/{sessionId}

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

This endpoint requires PXP-UST1 authentication.

### Request example


```json
{
  "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,
  "allowTransaction": 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. |
| `allowTransaction`boolean | Whether the transaction is allowed to proceed. If not provided, defaults to `null` (no decision made yet). |
| `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.


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


```json Modification not allowed
{
  "errorCode": "SES4006",
  "errorReason": "Session modification is not allowed, transaction has been authorised.",
  "correlationId": "24969442-62ab-4415-bc8e-d016ab7db109",
  "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. |