Config Object Error Codes

The Config Object in the Convenient Checkout API allows merchants to customize session behavior, payment options, and merchant information. This document lists error codes related to invalid or unsupported configuration parameters, helping developers troubleshoot integration issues quickly.

Error Codes Summary

Error Code Summary

Error Title Reference	Error & Status	Detail Message	Scenario	Resolution
Config Parameter Validation
saveDisabled/paymentMethodSaveMode not supported in [modes]	INVALID_REQUEST 400 BAD REQUEST	Invalid Request. Request parameter saveDisabled or paymentMethodSaveMode not supported in Mode: [modes]	When sending a request with saveDisabled=true or paymentMethodSaveMode specified, and mode contains fallback-not-possible modes	Remove saveDisabled or paymentMethodSaveMode parameters when using non-supported modes
Payment Method ID required for PAYMENT_METHOD_DISPLAY	INVALID_REQUEST 400 BAD REQUEST	Payment Method ID is required for mode - PAYMENT_METHOD_DISPLAY	When sending a request with PAYMENT_METHOD_DISPLAY mode but omitting the payment method ID	Include a valid payment method ID when using PAYMENT_METHOD_DISPLAY mode
saveDisabled and paymentMethodSaveMode cannot be used together	INVALID_REQUEST 400 BAD REQUEST	Invalid request: 'saveDisabled' and 'paymentMethodSaveMode' cannot be used together. Use only 'paymentMethodSaveMode'.	When sending a request with both saveDisabled and paymentMethodSaveMode specified	Use only paymentMethodSaveMode parameter, not both parameters together
Merchant name contains invalid characters	INVALID_REQUEST 400 BAD REQUEST	config.merchant.name Merchant name contains invalid characters	When the merchant name in the config object contains unsupported characters (only alphanumeric, space, hyphen, and dot)	Use only alphanumeric characters, spaces, hyphens, and dots in the merchant name
Merchant name must not be blank	INVALID_REQUEST 400 BAD REQUEST	config.merchant.name Merchant name must not be blank	When the merchant name in the config object is blank or not provided	Provide a non-empty merchant name in the config object
Merchant name character limit	INVALID_REQUEST 400 BAD REQUEST	config.merchant.name Merchant name must be less than or equal to 80 characters	When the merchant name in the config object exceeds 80 characters	Ensure merchant name is 80 characters or less
Invalid mode	INVALID_REQUEST 400 BAD REQUEST	Invalid mode	When providing an invalid session mode	Use one of the supported session modes (PAYMENT, PAYMENT_WITH_WALLET, WALLET, etc.)
Invalid PaymentMethodChannel	INVALID_REQUEST 400 BAD REQUEST	Invalid PaymentMethodChannel	When providing an invalid payment method channel	Use one of the supported payment method channels
Payment method type is not configured	INVALID_REQUEST 400 BAD REQUEST	Payment method type is not configured.	Payment method type is missing or not configured for the merchant during session creation	Ensure the payment method type is configured for your merchant account
You have no capture methods available	INVALID_REQUEST 400 BAD REQUEST	You have no capture methods available.	No available channels for configured payment methods (e.g., merchant configuration or session error)	Contact support to enable appropriate capture methods for your account
config.privacyPolicyUrl must be a valid URL	INVALID_REQUEST 400 BAD REQUEST	config.privacyPolicyUrl must be a valid URL	When privacyPolicyUrl in config is not a valid URL	Provide a valid, properly formatted URL for the privacy policy
Session Mode not applicable for guest checkout	INVALID_REQUEST 400 BAD REQUEST	Session Mode not applicable for guest checkout!	When a session mode is not allowed for guest checkout (WALLET, PAYMENT_METHOD_SELECT, PAYMENT_METHOD_ENTRY, PAYMENT_WITH_WALLET)	For guest checkout, use only supported modes like PAYMENT or PAYMENT_METHOD_DISPLAY
Invalid Card Category type	INVALID_REQUEST 400 BAD REQUEST	Invalid card category type config.cardCategories.type	When a card categories type is not given as Merchant configured type ( ex: MANUFACTURER_CARD )	Use only merchant-configured card category types
More than 100 medications	INVALID_REQUEST 400 BAD REQUEST	Maximum of 100 medications allowed in cardCategories[].medication	When a card categories medication having a more than 100 medications	Limit medications to 100 per card category
Card Categories given but Medication not provided	INVALID_REQUEST 400 BAD REQUEST	Medications cannot be empty in cardCategories[].medications	When a Card Categories given as Manufacturer card, medication should have to be provided	Provide at least one medication in cardCategories[].medications
More than 100 char in cardCategories.label	INVALID_REQUEST 400 BAD REQUEST	Category label cannot exceed 100 characters	When a Card Categories label consisting more then 100 characters	Limit card category label to 100 characters or less
More than 100 char or empty string in medication.value	INVALID_REQUEST 400 BAD REQUEST	Medication value cannot be empty and maximum allowed length is 100	When a Card Categories medication label consisting more then 100 characters	Provide a non-empty medication value of 100 characters or less
More than 100 char or empty string in medication.label	INVALID_REQUEST 400 BAD REQUEST	Medication label cannot be empty and maximum allowed length is 100	When a Card Categories medication value consisting more then 100 characters	Provide a non-empty medication label of 100 characters or less

Error Codes & Sample Requests/Responses

saveDisabled/paymentMethodSaveMode not supported

saveDisabled/paymentMethodSaveMode not supported in [modes]

Scenario: When sending a request with saveDisabled=true or paymentMethodSaveMode specified, and mode contains any fallback-not-possible modes (e.g., PAYMENT_METHOD_DISPLAY). Replace [modes] with the actual mode value in your request. Applicable Session Modes: PAYMENT

Sample Request:

{
  "mode": "PAYMENT_METHOD_DISPLAY",
  "config": {
    "saveDisabled": true
  }
}

Sample Response:

{
  "title": "INVALID_REQUEST",
  "status": 400,
  "detail": "Invalid Request. Request parameter saveDisabled or paymentMethodSaveMode not supported in Mode: PAYMENT_METHOD_DISPLAY"
}

Payment Method ID required for PAYMENT_METHOD_DISPLAY

Payment Method ID required for PAYMENT_METHOD_DISPLAY

Scenario: When sending a request with PAYMENT_METHOD_DISPLAY mode but omitting the payment method ID.

Sample Request:

{
  "mode": "PAYMENT_METHOD_DISPLAY"
}

Sample Response:

{
  "title": "INVALID_REQUEST",
  "status": 400,
  "detail": "Payment Method ID is required for mode - PAYMENT_METHOD_DISPLAY"
}

saveDisabled and paymentMethodSaveMode cannot be used together

saveDisabled and paymentMethodSaveMode cannot be used together

Scenario: When sending a request with both saveDisabled and paymentMethodSaveMode specified.

Sample Request:

{
  "config": {
    "saveDisabled": true,
    "paymentMethodSaveMode": "ALWAYS"
  }
}

Sample Response:

{
  "title": "INVALID_REQUEST",
  "status": 400,
  "detail": "Invalid request: 'saveDisabled' and 'paymentMethodSaveMode' cannot be used together. Use only 'paymentMethodSaveMode'."
}

Merchant name must not be blank

Merchant name must not be blank

Scenario: When the merchant name in the config object is not provided or is blank.

Sample Request:

{
  "config": {
    "merchant": {
      "name": ""
    }
  }
}

Sample Response:

{
  "title": "INVALID_REQUEST",
  "status": 400,
  "detail": "config.merchant.name Merchant name must not be blank"
}

Merchant name character limit

Merchant name character limit

Scenario: When the merchant name in the config object exceeds the maximum allowed length of 80 characters.

Sample Request:

{
  "config": {
    "merchant": {
      "name": "This is a very long merchant name that exceeds the maximum allowed character limit of eighty characters which is too long"
    }
  }
}

Sample Response:

{
  "title": "INVALID_REQUEST",
  "status": 400,
  "detail": "config.merchant.name Merchant name must be less than or equal to 80 characters"
}

Merchant name contains invalid characters

Merchant name contains invalid characters

Scenario: When the merchant name in the config object contains unsupported characters. Only alphanumeric characters, spaces, hyphens, and dots are allowed.

Sample Request:

{
  "config": {
    "merchant": {
      "name": "Invalid Merchant Name @#$%"
    }
  }
}

Sample Response:

{
  "title": "INVALID_REQUEST",
  "status": 400,
  "detail": "config.merchant.name Merchant name contains invalid characters"
}

Invalid Mode

Invalid mode

Scenario: When providing an invalid session mode

Sample Request:

{
  "config": {
    "modes": [
      "INVALID_MODE"
    ]
  },
  "payment": {
    "amount": 1000,
    "merchantTransactionId": "txn123456"
  },
  "customer": {
    "email": "test@example.com"
  }
}

Sample Response:

{
  "title": "INVALID_REQUEST",
  "status": 400,
  "detail": "Invalid mode"
}

Invalid Payment Method Channel

Invalid PaymentMethodChannel

Scenario: When providing an invalid payment method channel

Sample Request:

{
  "config": {
    "paymentMethodChannel": {
      "card": [
        "INVALID_CHANNEL"
      ]
    }
  },
  "payment": {
    "amount": 1000,
    "merchantTransactionId": "txn123456"
  },
  "customer": {
    "email": "test@example.com"
  }
}

Sample Response:

{
  "title": "INVALID_REQUEST",
  "status": 400,
  "detail": "Invalid PaymentMethodChannel"
}

Payment method type is not configured

Payment method type is not configured

Scenario: Payment method type is missing or not configured for the merchant during session creation.

Sample Response:

{
  "title": "INVALID_REQUEST",
  "status": 400,
  "detail": "Payment method type is not configured.",
  "errorDetails": null
}

No Capture methods

You have no capture methods available

Scenario: No available channels for configured payment methods (e.g., merchant configuration or session error).

Applicable Session Modes: PAYMENT_METHOD_ENTRY, PAYMENT, PAYMENT_WITH_WALLET

Sample Response:

{
  "title": "INVALID_REQUEST",
  "status": 400,
  "detail": "You have no capture methods available.",
  "errorDetails": null
}

Invalid Privacy Policy url

config.privacyPolicyUrl must be a valid URL

Scenario: When privacyPolicyUrl in config is not a valid URL.

Sample Request:

{
  "config": {
    "privacyPolicyUrl": "not-a-valid-url"
  }
}

Sample Response:

{
  "title": "INVALID_REQUEST",
  "status": 400,
  "detail": "config.privacyPolicyUrl must be a valid URL"
}

Session Mode not applicable

Session Mode not applicable for guest checkout

Scenario: When a session mode is not allowed for guest checkout. Applicable modes: WALLET,PAYMENT_METHOD_SELECT, PAYMENT_METHOD_ENTRY, PAYMENT_WITH_WALLET.

Sample Request:

{
  "config": {
    "modes": [
      "WALLET"
    ]
  },
  "customer": {
    "type": "guest"
  }
}

Sample Response:

{
  "title": "INVALID_REQUEST",
  "status": 400,
  "detail": "Session Mode not applicable for guest checkout!"
}

Card Categories

Card Categories object fields validation

**Scenario:**When a card categories type is not given as Merchant configured type ( ex: MANUFACTURER_CARD )

Sample Request:

{
  "config": {
    "cardCategories": [
      {
        "type": "DEBIT_CARD",
        "label": "Manufacturer copay card for debit used for copay medications and services only for this patient and their family. Do not use for other patients.",
        // This should be a valid card category label
        "medications": [
          {
            "label": "Pharacetamol 100mg Tablet copay medications and services only for this patient and their family. Do not use for other patients.",
            // This should be a valid medication label
            "value": ""
            // This should be a valid medication value
          }
        ]
      }
    ]
  }
}

Sample Response:

{
  "title": "INVALID_REQUEST",
  "status": 400,
  "detail": "Invalid card category type config.cardCategories.type."
}