Sessions API Error Codes

This document provides a comprehensive reference for session-level errors in the Convenient Checkout API. These errors help identify issues with session creation, access, and validation.

Quick Reference to Related Error Codes

• For customer object validation error, see the Customer Object Error Codes
• For Payment object validation error, see the Payment Object Error Codes
• For Agent object validation error, see the Agent Object Error Codes
• For Consent object validation error, see the Consent Object Error Codes
• For Payment Details object validation error, see the Payment Details Object Error Codes

Error Codes Summary

Error Code Summary

Error Title Reference	Error Title	HTTP Status	Detail Message	Scenario	Resolution
Session Controller Validation
Card WS2 check has failed	INVALID_REQUEST	400 BAD REQUEST	Card WS2 check has failed.	WS2 verification of agent information (e.g., MSID) failed during session creation	Ensure agent userid is part of PCI_WorkStation group
Session Id not found	NOT_FOUND	404 NOT FOUND	Session Id not found	When requesting a session that doesn't exist	Check that the session ID is correct and the session has been created
Your session has been canceled	SESSION_CANCELED	410 GONE	Your session has been canceled	When requesting a canceled session	Create a new session; canceled sessions cannot be reused
Your session is no longer valid	SESSION_TIMEOUT	401 UNAUTHORIZED	Your session is no longer valid	When requesting an expired session	Create a new session; expired sessions cannot be reused
Not allowed to access this session	FORBIDDEN	403 FORBIDDEN	Not allowed to access this session	When merchant ID in request doesn't match the session's merchant ID	Use the same merchant credentials that were used to create the session
Customer Identifier is Missing	INVALID_REQUEST	400 BAD REQUEST	Customer identifier is missing	When customer identifier is not provided for session modes: PAYMENT_METHOD_ENTRY, WALLET, PAYMENT_METHOD_SELECT, PAYMENT_METHOD_DISPLAY	Include a valid customer identifier (hsid, enterpriseId, or metadata)
Consent is required	INVALID_REQUEST	400 BAD REQUEST	Consent is required!	When consent is missing in PAYMENT mode	Include a valid consent object with the required fields
payment is required	INVALID_REQUEST	400 BAD REQUEST	payment is required	When payment object is missing for session modes: PAYMENT, PAYMENT_WITH_WALLET	Include a valid payment object with the required fields

---

Error Codes Details

Session Controller Validation

Card WS2 check has failed

Scenario: WS2 verification of agent information (e.g., MSID) failed during session creation.

Sample Response:

{
  "title": "INVALID_REQUEST",
  "status": 400,
  "detail": "Card WS2 check has failed.",
  "errorDetails": null
}

Session Id not found

Scenario: When requesting a session that doesn't exist

Sample Request:

GET v1/sessions/00000000-0000-0000-0000-000000000000
X-Merchant-Id: 123e4567-e89b-12d3-a456-426614174000
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Sample Response:

{
  "status": 404,
  "title": "NOT_FOUND",
  "detail": "Session Id not found"
}

Your session has been canceled

Scenario: When requesting a canceled session

Sample Request:

GET v1/sessions/123e4567-e89b-12d3-a456-426614174001
X-Merchant-Id: 123e4567-e89b-12d3-a456-426614174000
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Sample Response:

{
  "status": 410,
  "title": "SESSION_CANCELED",
  "detail": "Your session has been canceled"
}

Your session is no longer valid

Scenario: When requesting an expired session

Sample Request:

GET v1/sessions/123e4567-e89b-12d3-a456-426614174002
X-Merchant-Id: 123e4567-e89b-12d3-a456-426614174000
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Sample Response:

{
  "status": 401,
  "title": "SESSION_TIMEOUT",
  "detail": "Your session is no longer valid"
}

Not allowed to access this session

Scenario: When merchant ID in request doesn't match the session's merchant ID

Sample Request:

GET v1/sessions/123e4567-e89b-12d3-a456-426614174000
X-Merchant-Id: 99999999-e89b-12d3-a456-426614174000
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Sample Response:

{
  "status": 403,
  "title": "FORBIDDEN",
  "detail": "Not allowed to access this session"
}

Customer Identifier is Missing

Scenario: When customer identifier is not provided for session modes: PAYMENT_METHOD_ENTRY, WALLET, PAYMENT_METHOD_SELECT, PAYMENT_METHOD_DISPLAY.

Sample Request:

{
  "config": {
    "modes": ["PAYMENT_METHOD_ENTRY"]
  },
  "payment": {
    "amount": 1000,
    "merchantTransactionId": "txn123456"
  }
  // customer object is missing
}

Sample Response:

{
  "title": "INVALID_REQUEST",
  "status": 400,
  "detail": "Customer identifier is missing"
}

Consent is required

Scenario: When consent is missing in PAYMENT mode.

Sample Request:

{
  "config": {
    "modes": ["PAYMENT"]
  },
  "payment": {
    "amount": 1000,
    "merchantTransactionId": "txn123456"
  },
  "customer": {
    "email": "test@example.com"
  }
  // consent object is missing
}

Sample Response:

{
  "title": "INVALID_REQUEST",
  "status": 400,
  "detail": "Consent is required!"
}

payment is required

Scenario: When payment object is missing for session modes: PAYMENT, PAYMENT_WITH_WALLET.

Sample Request:

{
  "config": {
    "modes": ["PAYMENT_WITH_WALLET"]
  },
  "customer": {
    "email": "test@example.com"
  }
  // payment object is missing
}

Sample Response:

{
  "title": "INVALID_REQUEST",
  "status": 400,
  "detail": "payment is required"
}