Version: v2

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 Category	Error Title Reference	Error Title	HTTP Status	Error Message
CCG Schema Validation	Partial Authorization Not Allowed	INVALID_REQUEST	`400 BAD REQUEST`	partialAuthorization requires authorizeCard to be true
CCG Schema Validation	Statement Descriptor Suffix Invalid	INVALID_REQUEST	`400 BAD REQUEST`	statementDescriptorSuffix only allows alphanumeric, space, hyphen and dot with at least one letter and cannot exceed 10 characters
CCG Schema Validation	Invalid Amount	INVALID_REQUEST	`400 BAD REQUEST`	amount must be an integer between 1 and 99999999
CCG Schema Validation	Exceeded Metadata Entries	INVALID_REQUEST	`400 BAD REQUEST`	metadata cannot exceed 20 entries
CCG Schema Validation	Metadata Key Size Exceeded	INVALID_REQUEST	`400 BAD REQUEST`	metadata key cannot exceed 40 characters
CCG Schema Validation	Metadata Value Size Exceeded	INVALID_REQUEST	`400 BAD REQUEST`	metadata value cannot exceed 100 characters
CCG Schema Validation	Description Size Exceeded	INVALID_REQUEST	`400 BAD REQUEST`	description cannot exceed 100 characters
CCG Schema Validation	Merchant Transaction ID Required	INVALID_REQUEST	`400 BAD REQUEST`	merchantTransactionId is required
CCG Schema Validation	Merchant Transaction ID Too Long	INVALID_REQUEST	`400 BAD REQUEST`	merchantTransactionId cannot exceed 50 characters
CCG Schema Validation	Missing Payment Allocations	INVALID_REQUEST	`400 BAD REQUEST`	paymentAllocations is required
CCG Schema Validation	Too Many Payment Allocations	INVALID_REQUEST	`400 BAD REQUEST`	paymentAllocations cannot exceed 2 entries
CCG Schema Validation	Invalid Allocation Amount	INVALID_REQUEST	`400 BAD REQUEST`	paymentAllocations[n].amount must be an integer between 1 and 99999999
CCG Schema Validation	Missing Payment Amount	INVALID_REQUEST	`400 BAD REQUEST`	amount is required
CCG Schema Validation	Missing Allocation Amount	INVALID_REQUEST	`400 BAD REQUEST`	paymentAllocations[n].amount is required
CCG Schema Validation	Allocation Sum Mismatch	INVALID_REQUEST	`400 BAD REQUEST`	sum of paymentAllocations[:].amount must equal amount
CCG Schema Validation	Duplicate Payment Method Id	INVALID_REQUEST	`400 BAD REQUEST`	paymentAllocations[:].paymentMethodId must be unique
CCG Schema Validation	Invalid Payment Method Id	INVALID_REQUEST	`400 BAD REQUEST`	paymentAllocations[n].paymentMethodId must be a valid UUID
CCG Schema Validation	Missing Payment Method Id	INVALID_REQUEST	`400 BAD REQUEST`	paymentAllocations[n].paymentMethodId is required

Error Codes Details

Partial Authorization Not Allowed

Partial Authorization Not Allowed

Details:

Scenario: When sending a request with partialAuthorization=true, authorizeCard=false, and a card included in the request.
Resolution: Set authorizeCard=true when using partialAuthorization=true.
API Endpoints: /v2/payments, /v2/sessions
Scopes: merchant, user

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": "partialAuthorization requires authorizeCard to be true"
}

Merchant Transaction ID Too Long

Merchant Transaction ID Too Long

Details:

Scenario: When merchantTransactionId exceeds the allowed length.
Resolution: Ensure merchantTransactionId is 50 characters or fewer.
API Endpoints: /v2/payments, /v2/sessions
Scopes: merchant, user

Sample Request

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

Sample Response

{
  "title": "INVALID_REQUEST",
  "status": 400,
  "detail": "merchantTransactionId cannot exceed 50 characters"
}

Description Size Exceeded

Description Size Exceeded

Details:

Scenario: When description exceeds the allowed length.
Resolution: Ensure description is 100 characters or fewer.
API Endpoints: /v2/payments, /v2/sessions
Scopes: merchant, user

Sample Request

{
  "payment": {
    "amount": 1000,
    "merchantTransactionId": "txn123456",
    "description": """This description is intentionally made longer than one hundred characters to trigger the validation error for description maximum length enforcement."""
  },
  "customer": { "email": "test@example.com" }
}

Sample Response

{
  "title": "INVALID_REQUEST",
  "status": 400,
  "detail": "description cannot exceed 100 characters"
}

Statement Descriptor Suffix Invalid

Statement Descriptor Suffix Invalid

Details:

Scenario: When statement descriptor suffix is invalid
Resolution: Use only alphanumeric characters, spaces, hyphens, and dots in the suffix; include at least one letter; and keep it under 10 characters
API Endpoints: /v2/payments, /v2/sessions
Scopes: merchant, user

Sample Request

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

Sample Response

{
  "title": "INVALID_REQUEST",
  "status": 400,
  "detail": "statementDescriptorSuffix only allows alphanumeric, space, hyphen and dot with at least one letter and cannot exceed 10 characters"
}

Payment Allocation Object Errors

MISSING_PAYMENT_ALLOCATIONS

paymentAllocations is required.

Details:

Scenario: When Payment Allocation object is missing in API Request
Resolution: Add Payment Allocation Object with valid paymentMethodId and amount
API Endpoints: /v2/payments, /v2/sessions
Scopes: merchant, user

Sample Request

{
  "amount": 1,
  "merchantTransactionId": "mtx-missing-allocations",
  "authorizeCard": false,
  "partialAuthorization": false
}

Sample Response

{
  "title": "INVALID_REQUEST",
  "status": 400,
  "detail": "paymentAllocations is required",
  "errorDetails": null
}

TOO_MANY_ALLOCATIONS

Maximum number of allocations allowed is 2

Details:

Scenario: Maximum number of allocations allowed is 2 in the request.
Resolution: Limit paymentAllocations to a maximum of two.
API Endpoints: /v2/payments, /v2/sessions
Scopes: merchant, user

Sample Request

{
  "amount": 3,
  "merchantTransactionId": "mtx-too-many-allocs",
  "authorizeCard": false,
  "partialAuthorization": false,
  "paymentAllocations": [
    { "paymentMethodId": "b6df8625-cd25-4123-b345-638aa7b5d011", "amount": 1 },
    { "paymentMethodId": "f5146db5-2a93-4c7b-82d6-5d9fcb77c601", "amount": 1 },
    { "paymentMethodId": "5da3cd1f-9b0e-4a92-a977-06b4a23d3a19", "amount": 1 }
  ]
}

Sample Response

{
  "title": "INVALID_REQUEST",
  "status": 400,
  "detail": "paymentAllocations cannot exceed 2 entries"
}

Amount Validation Errors

INVALID_PAYMENT_AMOUNT

amount is outside the valid range or contains decimals

Details:

Scenario: paymentAllocations[n].amount 0.1 is invalid, it must be between 1 and 99999999 and not contain decimals..
Resolution: Provide a whole number amount within the allowed range.
API Endpoints: /v2/payments, /v2/sessions
Scopes: merchant, user

Sample Request

{
  "amount": 100000000,
  "merchantTransactionId": "mtx-invalid-payment-amount",
  "authorizeCard": false,
  "partialAuthorization": false,
  "paymentAllocations": [
    {
      "paymentMethodId": "b6df8625-cd25-4123-b345-638aa7b5d011",
      "amount": 50000000
    },
    {
      "paymentMethodId": "f5146db5-2a93-4c7b-82d6-5d9fcb77c601",
      "amount": 50000000
    }
  ]
}

Sample Response

{
  "title": "INVALID_REQUEST",
  "status": 400,
  "detail": "amount must be an integer between 1 and 99999999"
}

INVALID_ALLOCATION_AMOUNT

paymentAllocations[n].amount 0.1 is invalid, it must be between 1 and 99999999 and not contain decimals.

Details:

Scenario: paymentAllocations[n].amount 0.1 is invalid, it must be between 1 and 99999999 and not contain decimals..
Resolution: Ensure each allocation amount is a whole number between 1–99,999,999.
API Endpoints: /v2/payments, /v2/sessions
Scopes: merchant, user

Sample Request

{
  "amount": 1.5,
  "merchantTransactionId": "mtx-decimal-total",
  "authorizeCard": false,
  "partialAuthorization": false,
  "paymentAllocations": [
    {
      "paymentMethodId": "b6df8625-cd25-4123-b345-638aa7b5d011",
      "amount": 1
    },
    {
      "paymentMethodId": "f5146db5-2a93-4c7b-82d6-5d9fcb77c601",
      "amount": 0.5
    }
  ]
}

Sample Response

{
  "title": "INVALID_REQUEST",
  "status": 400,
  "detail": "paymentAllocations[n].amount must be an integer between 1 and 99999999"
}

MISSING_PAYMENT_AMOUNT

amount is required

Details:

Scenario: amount is required from the request.
Resolution: Add a valid amount value.
API Endpoints: /v2/payments, /v2/sessions
Scopes: merchant, user

Sample Request

{
  "merchantTransactionId": "mtx-missing-total",
  "authorizeCard": false,
  "partialAuthorization": false,
  "paymentAllocations": [
    {
      "paymentMethodId": "b6df8625-cd25-4123-b345-638aa7b5d011",
      "amount": 1
    }
  ]
}

Sample Response

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

MISSING_ALLOCATION_AMOUNT

paymentAllocations[n].amount is required

Details:

Scenario: paymentAllocations[n].amount is required.
Resolution: Add amount to each paymentAllocations[i].
API Endpoints: /v2/payments, /v2/sessions
Scopes: merchant, user

Sample Request

{
  "amount": 1,
  "merchantTransactionId": "mtx-missing-allocation-amount",
  "authorizeCard": false,
  "partialAuthorization": false,
  "paymentAllocations": [
    {
      "paymentMethodId": "b6df8625-cd25-4123-b345-638aa7b5d011"
    }
  ]
}

Sample Response

{
  "title": "INVALID_REQUEST",
  "status": 400,
  "detail": "paymentAllocations[n].amount is required"
}

ALLOCATION_SUM_MISMATCH

sum of paymentAllocations[:].amount should be equal to amount

Details:

Scenario: sum of paymentAllocations[:].amount should be equal to amount.
Resolution: Ensure all allocation amounts add up exactly to the total payment amount.
API Endpoints: /v2/payments, /v2/sessions
Scopes: merchant, user

Sample Request

{
  "amount": 10,
  "merchantTransactionId": "mtx-sum-mismatch",
  "authorizeCard": false,
  "partialAuthorization": false,
  "paymentAllocations": [
    {
      "paymentMethodId": "b6df8625-cd25-4123-b345-638aa7b5d011",
      "amount": 4
    },
    {
      "paymentMethodId": "f5146db5-2a93-4c7b-82d6-5d9fcb77c601",
      "amount": 5
    }
  ]
}

Sample Response

{
  "title": "INVALID_REQUEST",
  "status": 400,
  "detail": "sum of paymentAllocations[:].amount must equal amount",
  "errorDetails": null
}

Payment Method Validation Errors

DUPLICATE_PAYMENT_METHOD_ID

paymentAllocations[:].paymentMethodId cannot be same

Details:

Scenario: paymentAllocations[:].paymentMethodId cannot be same.
Resolution: Use unique payment methods for each allocation.
API Endpoints: /v2/payments, /v2/sessions
Scopes: merchant, user

Sample Request

{
  "amount": 2,
  "merchantTransactionId": "mtx-sum-mismatch",
  "authorizeCard": false,
  "partialAuthorization": false,
  "paymentAllocations": [
    {
      "paymentMethodId": "b6df8625-cd25-4123-b345-638aa7b5d011",
      "amount": 1
    },
    {
      "paymentMethodId": "b6df8625-cd25-4123-b345-638aa7b5d011",
      "amount": 1
    }
  ]
}

Sample Response

{
  "title": "INVALID_REQUEST",
  "status": 400,
  "detail": "paymentAllocations[:].paymentMethodId must be unique"
}

MISSING_PAYMENT_METHOD_ID

paymentAllocations[:].paymentMethodId is required

Details:

Scenario: paymentAllocations[:].paymentMethodId is required.
Resolution: Add paymentMethodId for each allocation.
API Endpoints: /v2/payments, /v2/sessions
Scopes: merchant, user

Sample Request

{
  "amount": 1,
  "merchantTransactionId": "mtx-missing-pmid",
  "authorizeCard": false,
  "partialAuthorization": false,
  "paymentAllocations": [
    {
      "amount": 1
    }
  ]
}

Sample Response

{
  "title": "INVALID_REQUEST",
  "status": 400,
  "detail": "paymentAllocations[n].paymentMethodId is required"
}

INVALID_PAYMENT_METHOD_ID

paymentAllocations[n].paymentMethodId is invalid

Details:

Scenario: paymentAllocations[n].paymentMethodId is invalid.
Resolution: Use a properly formatted UUID string.
API Endpoints: /v2/payments, /v2/sessions
Scopes: merchant, user

Sample Request

{
  "amount": 1,
  "merchantTransactionId": "mtx-invalid-pmid",
  "authorizeCard": false,
  "partialAuthorization": false,
  "paymentAllocations": [
    {
      "paymentMethodId": "not-a-uuid",
      "amount": 1
    }
  ]
}

Sample Response

{
  "title": "INVALID_REQUEST",
  "status": 400,
  "detail": "paymentAllocations[n].paymentMethodId must be a valid UUID"
}

Invalid Amount

Invalid Amount

Scenario: When amount format is invalid

Resolution: Ensure amount is a whole number between 1 and 99999999 and does not contain decimals

API Endpoints: /v2/payments

Scopes: merchant, user

Sample Request

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

Sample Response

{
  "title": "INVALID_REQUEST",
  "status": 400,
  "detail": "amount must be an integer between 1 and 99999999"
}

Exceeded Metadata Entries

Exceeded Metadata Entries

Scenario: When exceeding the maximum number of metadata entries

Resolution: Reduce the number of metadata entries to 20 or fewer

API Endpoints: /v2/payments

Scopes: merchant, user

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": "metadata cannot exceed 20 entries"
}

Metadata Key Size Exceeded

Metadata Key Size Exceeded

Scenario: When a metadata key exceeds maximum allowed length

Resolution: Ensure metadata keys are 40 characters or less

API Endpoints: /v2/payments

Scopes: merchant, user

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 cannot exceed 40 characters"
}

Metadata Value Size Exceeded

Metadata Value Size Exceeded

Scenario: When a metadata value exceeds maximum allowed length

Resolution: Ensure metadata values are 100 characters or less

API Endpoints: /v2/payments

Scopes: merchant, user

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 cannot exceed 100 characters"
}

Merchant Transaction ID Required

Merchant Transaction ID Required

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

Resolution: Include a unique merchantTransactionId in the payment request.

API Endpoints: /v2/payments

Scopes: merchant, user

Sample Request

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

Sample Response

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

Error Codes Summary​

Error Codes Details​

Partial Authorization Not Allowed​

Merchant Transaction ID Too Long​

Description Size Exceeded​

Statement Descriptor Suffix Invalid​

Payment Allocation Object Errors​

MISSING_PAYMENT_ALLOCATIONS​

TOO_MANY_ALLOCATIONS​

Amount Validation Errors​

INVALID_PAYMENT_AMOUNT​

INVALID_ALLOCATION_AMOUNT​

MISSING_PAYMENT_AMOUNT​

MISSING_ALLOCATION_AMOUNT​

ALLOCATION_SUM_MISMATCH​

Payment Method Validation Errors​

DUPLICATE_PAYMENT_METHOD_ID​

MISSING_PAYMENT_METHOD_ID​

INVALID_PAYMENT_METHOD_ID​

Invalid Amount​

Exceeded Metadata Entries​

Metadata Key Size Exceeded​

Metadata Value Size Exceeded​

Merchant Transaction ID Required​

Error Codes Summary

Error Codes Details

Partial Authorization Not Allowed

Merchant Transaction ID Too Long

Description Size Exceeded

Statement Descriptor Suffix Invalid

Payment Allocation Object Errors

MISSING_PAYMENT_ALLOCATIONS

TOO_MANY_ALLOCATIONS

Amount Validation Errors

INVALID_PAYMENT_AMOUNT

INVALID_ALLOCATION_AMOUNT

MISSING_PAYMENT_AMOUNT

MISSING_ALLOCATION_AMOUNT

ALLOCATION_SUM_MISMATCH

Payment Method Validation Errors

DUPLICATE_PAYMENT_METHOD_ID

MISSING_PAYMENT_METHOD_ID

INVALID_PAYMENT_METHOD_ID

Invalid Amount

Exceeded Metadata Entries

Metadata Key Size Exceeded

Metadata Value Size Exceeded

Merchant Transaction ID Required