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.

transactionMethodobjectrequired

Details about the transaction method.

allowTransactionboolean or null

Whether the transaction is allowed to proceed. If not provided, defaults to null (no decision made yet).

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.

customerProfileIdstring or null, <= 255 characters

Optional Unity Customer Profile identifier for Checkout Drop-in sessions. Links the session to a returning shopper profile and can filter which Drop-in payment methods are offered. Omit for guest or anonymous checkout. Include when the shopper is known and you want the session scoped to their Customer Profile. Profile lookup and payment-method enrichment apply when the session is created for Checkout Drop-in (serviceType of CheckoutDropIn). This field is request-only and isn't returned in the response.

Example:"your-customer-profile-id"

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,
    "transactionMethod": {
      "intent": {
        "card": "EstimatedAuthorisation"
      }
    },
    "amounts": {
      "currencyCode": "EUR",
      "transactionValue": 30.32
    }
  }'

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.

restrictionsobject

Details about the card restrictions configured at the merchant or site level. These restrictions define which card types are blocked based on owner type and funding source. Transactions using restricted cards will be declined with error code CRD184 (card restricted).

Response

{
  "sessionId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "hmacKey": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6",
  "encryptionKey": "k8l9m0n1o2p3q4r5s6t7u8v9w0x1y2z",
  "sessionExpiry": "2025-05-19T13:39:20.3843454Z",
  "allowedFundingTypes": {
    "cardSchemes": [ … ],
    "cards": []
  },
  "restrictions": {
    "card": { … }
  }
}

Create a session

Request

Responses

Was this helpful?