Version: v2

Customer Object Error Codes

This document provides a comprehensive reference for validation errors related to the customer object in the Convenient Checkout API. These errors help identify issues with customer 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	Missing Required Identifiers	INVALID_REQUEST	`400 BAD REQUEST`	customer object must include at least one of customer.hsid, customer.enterpriseId, or customer.metadata
CCG Schema Validation	Invalid Enterprise ID	INVALID_REQUEST	`400 BAD REQUEST`	customer.enterpriseId is invalid
CCG Schema Validation	Invalid HSID	INVALID_REQUEST	`400 BAD REQUEST`	customer.hsid must be a valid UUID
CCG Schema Validation	Customer Not Found	NOT_FOUND	`404 NOT FOUND`	Customer not found for given customer.enterpriseId
CCG Schema Validation	Exceeded Metadata Entries	INVALID_REQUEST	`400 BAD REQUEST`	customer.metadata cannot exceed 20 entries
CCG Schema Validation	Metadata Key Size Exceeded	INVALID_REQUEST	`400 BAD REQUEST`	customer.metadata key cannot exceed 40 characters
CCG Schema Validation	Metadata Value Size Exceeded	INVALID_REQUEST	`400 BAD REQUEST`	customer.metadata value cannot exceed 100 characters
CCG Schema Validation	Email Validation	INVALID_REQUEST	`400 BAD REQUEST`	customer.email must be a valid email address
CCG Schema Validation	First Name Length Exceeded	INVALID_REQUEST	`400 BAD REQUEST`	customer.firstName cannot exceed 100 characters
CCG Schema Validation	Last Name Length Exceeded	INVALID_REQUEST	`400 BAD REQUEST`	customer.lastName cannot exceed 100 characters
CCG Schema Validation	SSN Validation	INVALID_REQUEST	`400 BAD REQUEST`	customer.ssnLastFour must be 4 digits

Missing Required Identifiers

Missing Required Identifiers

Details:

Scenario: Customer identifiers such as hsid, enterpriseId, or metadata are mandatory to locate the customer.
Resolution: Include at least one of hsid, enterpriseId, or metadata in the customer object.
API Endpoints: /v2/payments, /v2/sessions
Scopes: merchant, user

Sample Request

{
  "customer": {
    "metadata": null,
    "hsid": null,
    "enterpriseId": null
  }
}

Sample Response

{
  "title": "INVALID_REQUEST",
  "status": 400,
  "detail": "customer object must include at least one of customer.hsid, customer.enterpriseId, or customer.metadata"
}

Invalid HSID

Invalid hsid

Details:

Scenario: Validates that the HSID is a properly formatted UUID.
Resolution: Provide a valid UUID format for the hsid.
API Endpoints: /v2/payments, /v2/sessions
Scopes: merchant, user

Sample Request

{
  "email": "test@example.com",
  "hsid": "invalid-hsid"
}

Sample Response

{
  "title": "INVALID_REQUEST",
  "status": 400,
  "detail": "customer.hsid must be a valid UUID"
}

Invalid Enterprise ID

Invalid enterpriseId

Details:

Scenario: Validates that Enterprise ID contains only digits.
Resolution: Ensure enterpriseId contains only numeric digits.
API Endpoints: /v2/payments, /v2/sessions
Scopes: merchant, user

Sample Request

{
  "email": "test@example.com",
  "enterpriseId": "abc123"
}

Sample Response

{
  "title": "INVALID_REQUEST",
  "status": 400,
  "detail": "customer.enterpriseId is invalid"
}

Customer Not Found For Given Enterprise Id

Customer Not found for given Enterprise Id

Details:

Scenario: No customer record exists for the provided enterpriseId.
Resolution: Verify the enterpriseId is correct or create the customer record.
API Endpoints: /v2/payments, /v2/sessions
Scopes: merchant, user

Sample Request

{
  "enterpriseId": "9999999999"
}

Sample Response

{
  "title": "NOT_FOUND",
  "status": 404,
  "detail": "Customer not found for given customer.enterpriseId"
}

Exceeded Metadata Entries

Exceeded Metadata Entries

Details:

Scenario: Customer metadata exceeds the allowed number of entries.
Resolution: Reduce metadata entries so that the total does not exceed 20 entries.
API Endpoints: /v2/payments, /v2/sessions
Scopes: merchant, user

Sample Request

{
  "email": "test@example.com",
  "metadata": {
    "key1": "value1",
    "key2": "value2"
    // ... more key-value pairs ...
  }
}

Sample Response

{
  "title": "INVALID_REQUEST",
  "status": 400,
  "detail": "customer.metadata cannot exceed 20 entries"
}

Metadata Key Size Exceeded

Metadata Key Size Exceeded

Details:

Scenario: Metadata key length exceeds the allowed maximum.
Resolution: Shorten metadata keys to at most 40 characters.
API Endpoints: /v2/payments, /v2/sessions
Scopes: merchant, user

Sample Request

{
  "email": "test@example.com",
  "metadata": {
    "thisKeyIsVeryLongAndExceedsTheMaximumAllowedLengthForMetadataKeys": "value"
  }
}

Sample Response

{
  "title": "INVALID_REQUEST",
  "status": 400,
  "detail": "customer.metadata key cannot exceed 40 characters"
}

Metadata Value Size Exceeded

Metadata Value Size Exceeded

Details:

Scenario: Metadata value length exceeds the allowed maximum.
Resolution: Truncate or shorten metadata values so that each value is at most 100 characters.
API Endpoints: /v2/payments, /v2/sessions
Scopes: merchant, user

Sample Request

{
  "email": "test@example.com",
  "metadata": {
    "key": "This value is too long and exceeds the maximum allowed length for metadata values which is 100 characters."
  }
}

Sample Response

{
  "title": "INVALID_REQUEST",
  "status": 400,
  "detail": "customer.metadata value cannot exceed 100 characters"
}

Email Validation

Email Validation

Details:

Scenario: Email is not properly formatted according to email standards.
Resolution: Provide a valid email address for the customer.email field.
API Endpoints: /v2/payments, /v2/sessions
Scopes: merchant, user

Sample Request

{
  "email": "invalid-email",
  "hsid": "123e4567-e89b-12d3-a456-426614174000"
}

Sample Response

{
  "title": "INVALID_REQUEST",
  "status": 400,
  "detail": "customer.email must be a valid email address"
}

First Name Length Exceeded

First Name Length Exceeded

Details:

Scenario: Customer first name exceeds the maximum allowed length.
Resolution: Ensure firstName is no longer than 100 characters.
API Endpoints: /v2/payments, /v2/sessions
Scopes: merchant, user

Sample Request

{
  "firstName": "A very long first name that exceeds the maximum allowed length of 100 characters..."
}

Sample Response

{
  "title": "INVALID_REQUEST",
  "status": 400,
  "detail": "customer.firstName cannot exceed 100 characters"
}

Last Name Length Exceeded

Last Name Length Exceeded

Details:

Scenario: Customer last name exceeds the maximum allowed length.
Resolution: Ensure lastName is no longer than 100 characters.
API Endpoints: /v2/payments, /v2/sessions
Scopes: merchant, user

Sample Request

{
  "lastName": "A very long last name that exceeds the maximum allowed length of 100 characters..."
}

Sample Response

{
  "title": "INVALID_REQUEST",
  "status": 400,
  "detail": "customer.lastName cannot exceed 100 characters"
}

SSN Validation

SSN Validation

Details:

Scenario: SSN last four digits are not exactly 4 numeric digits.
Resolution: Provide exactly 4 numeric digits for ssnLastFour.
API Endpoints: /v2/payments, /v2/sessions
Scopes: merchant, user

Sample Request

{
  "email": "test@example.com",
  "ssnLastFour": "123"
}

Sample Response

{
  "title": "INVALID_REQUEST",
  "status": 400,
  "detail": "customer.ssnLastFour must be 4 digits"
}

ZIP Code Validation

ZIP Code Validation

Details:

Scenario: ZIP code is not exactly 5 digits.
Resolution: Provide a 5-digit ZIP code in zip5.
API Endpoints: /v2/payments, /v2/sessions
Scopes: merchant, user

Sample Request

{
  "email": "test@example.com",
  "zip5": "1234"
}

Sample Response

{
  "title": "INVALID_REQUEST",
  "status": 400,
  "detail": "customer.zip5 must be exactly 5 digits"
}

Date of Birth Validation

Date of Birth Validation

Details:

Scenario: Date of birth is not provided in a valid ISO date format.
Resolution: Provide dateOfBirth in YYYY-MM-DD format and ensure it's a valid date.
API Endpoints: /v2/payments, /v2/sessions
Scopes: merchant, user

Sample Request:

{
  "email": "test@example.com",
  "dateOfBirth": "01-01-2000"
}

Sample Response:

{
  "title": "INVALID_REQUEST",
  "status": 400,
  "detail": "customer.dateOfBirth must be valid and should be in YYYY-MM-DD format"
}

Phone Number Validation

Phone Number Validation

Details:

Scenario: Phone number components are missing or malformed.
Resolution: Provide valid phoneNumber.countryCode (digits only, 1-3 chars) and phoneNumber.number (digits only, 7-15 chars).
API Endpoints: /v2/payments, /v2/sessions
Scopes: merchant, user

Sample Request (Invalid Country Code)

{
  "email": "test@example.com",
  "phoneNumber": {
    "countryCode": "ABC",
    "number": "1234567890"
  }
}

Sample Response

{
  "title": "INVALID_REQUEST",
  "status": 400,
  "detail": "customer.phoneNumber.countryCode is invalid. It must contain only digits and be 1 to 3 characters long."
}

Sample Request (Invalid Number)

{
  "email": "test@example.com",
  "phoneNumber": {
    "countryCode": "01",
    "number": "123"
  }
}

Sample Response

{
  "title": "INVALID_REQUEST",
  "status": 400,
  "detail": "customer.phoneNumber.number is invalid. It must contain only digits and be 7 to 15 characters long."
}

Sample Request (Missing Country Code)

{
  "email": "test@example.com",
  "phoneNumber": {
    "number": "1234567890"
  }
}

Sample Response (Missing Country Code)

{
  "title": "INVALID_REQUEST",
  "status": 400,
  "detail": "customer.phoneNumber.countryCode is required"
}

Error Codes Summary​

Missing Required Identifiers​

Invalid HSID​

Invalid Enterprise ID​

Customer Not Found For Given Enterprise Id​

Exceeded Metadata Entries​

Metadata Key Size Exceeded​

Metadata Value Size Exceeded​

Email Validation​

First Name Length Exceeded​

Last Name Length Exceeded​

SSN Validation​

ZIP Code Validation​

Date of Birth Validation​

Phone Number Validation​

Error Codes Summary

Missing Required Identifiers

Invalid HSID

Invalid Enterprise ID

Customer Not Found For Given Enterprise Id

Exceeded Metadata Entries

Metadata Key Size Exceeded

Metadata Value Size Exceeded

Email Validation

First Name Length Exceeded

Last Name Length Exceeded

SSN Validation

ZIP Code Validation

Date of Birth Validation

Phone Number Validation