Checkout Session Authorization Error Codes

This document provides a comprehensive reference for session authorization errors in the Convenient Checkout API. These errors help identify issues with checkout session authentication and authorization.

Error Codes Summary

Error Code Summary

Error Title Reference	Error Title	HTTP Status	Detail Message	Scenario	Resolution
Checkout Session Authorization	FORBIDDEN	403 FORBIDDEN	Access denied when attempting to save payment method using completed session	Attempting to save payment method with a completed checkout session	Create a new session for saving payment methods; completed sessions cannot be reused
	FORBIDDEN	403 FORBIDDEN	Access denied when attempting to save payment method using PAYMENT mode	Attempting to save payment method when session is in payment mode	Use PAYMENT_METHOD_ENTRY or WALLET or PAYMENT_WITH_WALLET mode for saving payment methods
	FORBIDDEN	403 FORBIDDEN	Access denied when attempting to poll setup payment method using PAYMENT mode	Attempting to poll for setup status when session is in payment mode	Use PAYMENT_METHOD_ENTRY or WALLET or PAYMENT_WITH_WALLET mode for saving payment methods
	FORBIDDEN	403 FORBIDDEN	Access denied when attempting to save payment method using cancelled session	Attempting to save payment method with a cancelled checkout session	Create a new session; cancelled sessions cannot be reused
	FORBIDDEN	403 FORBIDDEN	Not allowed to access this session	When merchant2 tries to access a session initiated by merchant1	Use the same merchant credentials that were used to create the session

---

Error Codes Details

Checkout Session Authorization

Using Completed Session

When attempting to save a payment method, the checkout session (identified by the checkoutId in the header) must not be in a completed state.

Sample Error Response:

{
  "title": "FORBIDDEN",
  "status": 403,
  "detail": "Access denied when attempting to save payment method using completed session"
}

Session in Payment Mode

When attempting to save a payment method, the checkout session (identified by the checkoutId in the header) must not be in PAYMENT mode. Payment method saving is only allowed in SETUP or SETUP_AND_PAYMENT modes.

Sample Error Response:

{
  "title": "FORBIDDEN",
  "status": 403,
  "detail": "Access denied when attempting to save payment method using PAYMENT mode"
}

Polling in Payment Mode

When polling for the status of a payment method setup operation, the checkout session (identified by the checkoutId in the header) must not be in PAYMENT mode.

Sample Error Response:

{
  "title": "FORBIDDEN",
  "status": 403,
  "detail": "Access denied when attempting to poll setup payment method using PAYMENT mode"
}

Using Cancelled Session

When attempting to save a payment method, the checkout session (identified by the checkoutId in the header) must not be in a cancelled state.

Sample Error Response:

{
  "title": "FORBIDDEN",
  "status": 403,
  "detail": "Access denied when attempting to save payment method using cancelled session"
}

Cross-Merchant Session Access

When a merchant attempts to access a session that was created by a different merchant. The merchant ID is verified against the session's originating merchant, and if they don't match, the request is rejected.

Sample Request:

GET v1/sessions/{sessionId}
X-Merchant-Id: merchant2-uuid
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Sample Error Response:

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