Payment Object Error Codes

This document provides a comprehensive reference for validation errors related to the payment object in the Convenient Checkout API. These errors help identify issues with payment data in API requests and guide you in resolving them.

Error Codes Summary

Error Code Summary

Error Title Reference	Error Title	HTTP Status	Detail Message	Scenario	Resolution
Payment Object Validation
Partial Authorization Not Allowed	INVALID_REQUEST	400 BAD REQUEST	Partial authorization not allowed for authorizeCard = false	When sending a request with partialAuthorization=true, authorizeCard=false, and a card included in the request	Set authorizeCard=true when using partialAuthorization=true
Statement Descriptor Suffix Invalid	INVALID_REQUEST	400 BAD REQUEST	payment.statementDescriptorSuffix only allows alphanumeric, space, hyphen and dot with at least one letter and allowed maximum length is 10	When statement descriptor suffix is invalid	Use only alphanumeric characters, spaces, hyphens, and dots in the suffix; include at least one letter; and keep it under 10 characters
Invalid Amount	INVALID_REQUEST	400 BAD REQUEST	Invalid amount ${validatedValue}, it must be between 1 and 99999999 and not contain decimals	When amount format is invalid	Ensure amount is a whole number between 1 and 99999999 and does not contain decimals
Exceeded Metadata Entries	INVALID_REQUEST	400 BAD REQUEST	Exceeded the max number of entries in metadata. Max 20	When exceeding the maximum number of metadata entries	Reduce the number of metadata entries to 20 or fewer
Metadata Key Size Exceeded	INVALID_REQUEST	400 BAD REQUEST	Metadata key size bigger than: 40	When a metadata key exceeds maximum allowed length	Ensure metadata keys are 40 characters or less
Metadata Value Size Exceeded	INVALID_REQUEST	400 BAD REQUEST	Metadata value size bigger than: 100	When a metadata value exceeds maximum allowed length	Ensure metadata values are 100 characters or less
Merchant Transaction ID Required	INVALID_REQUEST	400 BAD REQUEST	merchantTransactionId is required	When merchant transaction ID is missing in the payment object	Include a unique merchantTransactionId in the payment request
Customer Required	INVALID_REQUEST	400 BAD REQUEST	Customer is required	When customer object is missing	Include the customer object with appropriate identifiers in the request

---

Error Codes Details

Payment Object Validation

Partial Authorization Not Allowed

Scenario: When sending a request with partialAuthorization=true, authorizeCard=false, and a card included in the request

Sample Request:

{
"config": {
    "paymentMethodChannel": {
      "card": ["WEBFORM"]
    }
  },
    "payment": {
    "amount": 1000,
    "merchantTransactionId": "txn123456",
        "partialAuthorization": true,
    "authorizeCard": false
  },
  "customer": {
    "email": "test@example.com"
  }
}

Sample Response:

{
  "title": "INVALID_REQUEST",
  "status": 400,
  "detail": "Partial authorization not allowed for authorizeCard = false"
}

Statement Descriptor Suffix Invalid

Scenario: When statement descriptor suffix is invalid

Sample Request:

{
  "payment": {
    "amount": 1000,
    "merchantTransactionId": "txn123456",
    "statementDescriptorSuffix": "12345!@#$%"
  },
  "customer": {
    "email": "test@example.com"
  }
}

Sample Response:

{
  "title": "INVALID_REQUEST",
  "status": 400,
  "detail": "payment.statementDescriptorSuffix only allows alphanumeric, space, hyphen and dot with at least one letter and allowed maximum length is 10"
}

Invalid Amount

Scenario: When amount format is invalid

Sample Request:

{
  "payment": {
    "amount": 10.50,
    "merchantTransactionId": "txn123456"
  },
  "customer": {
    "email": "test@example.com"
  }
}

Sample Response:

{
  "title": "INVALID_REQUEST",
  "status": 400,
  "detail": "Invalid amount 10.5, it must be between 1 and 99999999 and not contain decimals"
}

Exceeded Metadata Entries

Scenario: When exceeding the maximum number of metadata entries

Sample Request:

{
  "payment": {
    "amount": 1000,
    "merchantTransactionId": "txn123456",
    "metadata": {
      "key1": "value1",
      "key2": "value2",
      "key3": "value3",
      "key4": "value4",
      "key5": "value5",
      "key6": "value6",
      "key7": "value7",
      "key8": "value8",
      "key9": "value9",
      "key10": "value10",
      "key11": "value11"
    }
  },
  "customer": {
    "email": "test@example.com"
  }
}

Sample Response:

{
  "title": "INVALID_REQUEST",
  "status": 400,
  "detail": "Exceeded the max number of entries in metadata. Max 20"
}

Metadata Key Size Exceeded

Scenario: When a metadata key exceeds maximum allowed length

Sample Request:

{
  "payment": {
    "amount": 1000,
    "merchantTransactionId": "txn123456",
    "metadata": {
      "thisKeyIsWayTooLongAndExceedsTheMaximumAllowedCharacterLength": "value"
    }
  },
  "customer": {
    "email": "test@example.com"
  }
}

Sample Response:

{
  "title": "INVALID_REQUEST",
  "status": 400,
  "detail": "Metadata key size bigger than: 40"
}

Metadata Value Size Exceeded

Scenario: When a metadata value exceeds maximum allowed length

Sample Request:

{
  "payment": {
    "amount": 1000,
    "merchantTransactionId": "txn123456",
    "metadata": {
      "key": "This value is way too long and exceeds the maximum allowed character length for metadata values in the system which is typically around 500 characters depending on configuration but this particular value is intentionally made to be longer than that to trigger the validation error and demonstrate the enforcement of the metadata value size constraint in the application which helps maintain data integrity and performance"
    }
  },
  "customer": {
    "email": "test@example.com"
  }
}

Sample Response:

{
  "title": "INVALID_REQUEST",
  "status": 400,
  "detail": "Metadata value size bigger than: 500"
}

Merchant Transaction ID Required

Scenario: When merchant transaction ID is missing in the payment object

Sample Request:

{
  "payment": {
    "amount": 1000
    // merchantTransactionId is missing
  },
  "customer": {
    "email": "test@example.com"
  }
}

Sample Response:

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

Customer Required for Pay and Save Flow

Scenario: When customer object is missing When customer object is missing for authenticated user payment

Sample Request:

{
  "payment": {
    "amount": 1000,
    "merchantTransactionId": "txn123456",
    "paymentMethod":{
       "paymentMethodDetails":{
          "type":"BANK_ACCOUNT",
          "savePaymentMethod": true
    }
    }
   
  }
  // customer object is missing
}

Sample Response:

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