Version: v1

Payment Method Details Error Codes

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

Error Code Summary

Error Codes Summary

Nickname Validation

Error Title Reference	Error Title	HTTP Status	Detail Message	Scenario	Resolution
Nickname Format	PAYMENT_METHOD_ERROR	400	Nickname must be alphanumeric and up to 30 characters.	Nickname contains special characters or is too long	Use only letters and numbers for the nickname and keep it under 30 characters
Nickname Contains Account #	PAYMENT_METHOD_ERROR	400	nickname shouldn't contain account number	Nickname includes the bank account number	Remove any account numbers from the nickname field
Nickname Contains Card #	PAYMENT_METHOD_ERROR	400	Please make sure that the nickname field doesn't contain a card number.	Nickname includes a card number	Remove any card numbers from the nickname field

Bank Account Validation

Error Title Reference	Error Title	HTTP Status	Detail Message	Scenario	Resolution
Name Contains Account #	PAYMENT_METHOD_ERROR	400	nameOnAccount shouldn't contain account number	Name on account includes the account number	Remove any account numbers from the name on account field
Account Number Format	PAYMENT_METHOD_ERROR	400	accountNumber is not valid	Account number contains non-digits	Ensure account number contains only numeric digits
Account Number Length	PAYMENT_METHOD_ERROR	400	accountNumber can be upto 17 digits	Account number is longer than 17 digits	Provide an account number that is 17 digits or less
Required Account Number	PAYMENT_METHOD_ERROR	400	accountNumber is required	Account number is missing	Include a valid account number in the request
Valid Account Type	PAYMENT_METHOD_ERROR	400	accountType is not valid	Account type is not checking or savings	Use only 'checking' or 'savings' for account type
Required Account Type	PAYMENT_METHOD_ERROR	400	accountType is required	Account type is missing	Include the account type (checking or savings) in the request
Bank Account Details Required	PAYMENT_METHOD_ERROR	400	Bank Account details are needed	Bank account details missing	Provide all required bank account details
Routing Number Required	PAYMENT_METHOD_ERROR	400	routingNumber is required	Routing number is missing	Include a valid routing number in the request
Routing Number Format	PAYMENT_METHOD_ERROR	400	routingNumber must be a 9 digit number	Routing number is not 9 digits	Ensure routing number is exactly 9 digits
Name on Account Required	PAYMENT_METHOD_ERROR	400	Name on account is required	Name on account is missing	Include the name on account in the request
Invalid Payment Method Type	PAYMENT_METHOD_ERROR	400	BANK_ACCOUNT type is not applicable for paymentMethod.type	Bank account type used with card	Use consistent payment method types (don't mix card and bank account details)

Card Categories Validation

Error Title Reference	Error Title	HTTP Status	Detail Message	Scenario	Resolution
Medication Label Validation	PAYMENT_METHOD_ERROR	400	Medication label cannot be empty and maximum allowed length is 100	Empty or too long medication label in cardCategories	Provide a non-empty medication label under 100 characters
Medication Value Validation	PAYMENT_METHOD_ERROR	400	Medication value cannot be empty and maximum allowed length is 100	Empty or too long medication value in cardCategories	Provide a non-empty medication value under 100 characters
Invalid Card Category Type	PAYMENT_METHOD_ERROR	400	Invalid card category type	Unsupported card category type in cardCategories	Set Supported Card Category as per the merchant settings

Card Information Validation

Error Title Reference	Error Title	HTTP Status	Detail Message	Scenario	Resolution
Name on Card Required	PAYMENT_METHOD_ERROR	400	Name on card must not be blank.	Name on card is blank	Provide a non-empty name on the card field
Card Number in Name Field	PAYMENT_METHOD_ERROR	400	Please make sure that the name field doesn't contain a card number.	Name on card contains a card number	Remove any card numbers from the name on card field
Vendor Payment Method ID Required	PAYMENT_METHOD_ERROR	400	vendorPaymentMethodId is required	Vendor payment method ID missing	Include the vendor payment method ID in the request

Payment Method Validation

Error Title Reference	Error Title	HTTP Status	Detail Message	Scenario	Resolution
Payment Method Required	PAYMENT_METHOD_ERROR	400	paymentMethod is required	Payment method is missing	Include the payment method object in the request
Payment Method Type Required	PAYMENT_METHOD_ERROR	400	paymentMethod type is required	Payment method type is missing	Specify a valid payment method type (e.g., "CARD" or "BANK_ACCOUNT")

Error Code Details

Nickname Validation

Nickname must be alphanumeric and up to 30 characters.

Validates that the nickname follows the required format: alphanumeric, up to 30 characters, no consecutive spaces.

Sample Invalid Request:

{
  "customer": {
    "hsid": "123e4567-e89b-12d3-a456-426614174000"
  },
  "paymentMethod": {
    "type": "CARD",
    "paymentMethodDetails": {
      "nameOnCard": "John Doe"
    },
    "nickname": "My Credit Card With Special Characters @#$%"
  }
}

Sample Error Response:

{
  "title": "PAYMENT_METHOD_ERROR",
  "status": 400,
  "detail": "Nickname must be alphanumeric and up to 30 characters."
}

Nickname shouldn't contain account number

Validates that the nickname doesn't contain the bank account number.

Sample Invalid Request:

{
  "customer": {
    "hsid": "123e4567-e89b-12d3-a456-426614174000"
  },
  "paymentMethod": {
    "type": "BANK_ACCOUNT",
    "paymentMethodDetails": {
      "type": "BANK_ACCOUNT",
      "accountNumber": "987654321",
      "routingNumber": "123456789",
      "accountType": "checking",
      "nameOnAccount": "John Doe"
    },
    "nickname": "My Account 987654321"
  }
}

Sample Error Response:

{
  "title": "PAYMENT_METHOD_ERROR",
  "status": 400,
  "detail": "nickname shouldn't contain account number"
}

Please make sure that the nickname field doesn't contain a card number.

Validates that the nickname doesn't contain a card number.

Sample Invalid Request:

{
  "customer": {
    "hsid": "123e4567-e89b-12d3-a456-426614174000"
  },
  "paymentMethod": {
    "type": "CARD",
    "paymentMethodDetails": {
      "nameOnCard": "John Doe"
    },
    "nickname": "Visa 4111111111111111"
  }
}

Sample Error Response:

{
  "title": "PAYMENT_METHOD_ERROR",
  "status": 400,
  "detail": "Please make sure that the nickname field doesn't contain a card number."
}

Bank Account Validation

Name Contains Account Number

Validates that the name on account doesn't contain the account number.

Sample Invalid Request:

{
  "customer": {
    "hsid": "123e4567-e89b-12d3-a456-426614174000"
  },
  "paymentMethod": {
    "type": "BANK_ACCOUNT",
    "paymentMethodDetails": {
      "type": "BANK_ACCOUNT",
      "accountNumber": "987654321",
      "routingNumber": "123456789",
      "accountType": "checking",
      "nameOnAccount": "John Doe 987654321"
    }
  }
}

Sample Error Response:

{
  "title": "PAYMENT_METHOD_ERROR",
  "status": 400,
  "detail": "nameOnAccount shouldn't contain account number"
}

Account Number Format

Validates that the account number contains only digits.

Sample Invalid Request:

{
  "customer": {
    "hsid": "123e4567-e89b-12d3-a456-426614174000"
  },
  "paymentMethod": {
    "type": "BANK_ACCOUNT",
    "paymentMethodDetails": {
      "type": "BANK_ACCOUNT",
      "accountNumber": "ABC-123456",
      "routingNumber": "123456789",
      "accountType": "checking",
      "nameOnAccount": "John Doe"
    }
  }
}

Sample Error Response:

{
  "title": "PAYMENT_METHOD_ERROR",
  "status": 400,
  "detail": "accountNumber is not valid"
}

Account Number Length

Validates that the account number is not longer than 17 digits.

Sample Invalid Request:

{
  "customer": {
    "hsid": "123e4567-e89b-12d3-a456-426614174000"
  },
  "paymentMethod": {
    "type": "BANK_ACCOUNT",
    "paymentMethodDetails": {
      "type": "BANK_ACCOUNT",
      "accountNumber": "123456789012345678",
      "routingNumber": "123456789",
      "accountType": "checking",
      "nameOnAccount": "John Doe"
    }
  }
}

Sample Error Response:

{
  "title": "PAYMENT_METHOD_ERROR",
  "status": 400,
  "detail": "accountNumber can be upto 17 digits"
}

Required Account Number

Validates that the account number is provided.

Sample Invalid Request:

{
  "customer": {
    "hsid": "123e4567-e89b-12d3-a456-426614174000"
  },
  "paymentMethod": {
    "type": "BANK_ACCOUNT",
    "paymentMethodDetails": {
      "type": "BANK_ACCOUNT",
      "routingNumber": "123456789",
      "accountType": "checking",
      "nameOnAccount": "John Doe"
    }
  }
}

Sample Error Response:

{
  "title": "PAYMENT_METHOD_ERROR",
  "status": 400,
  "detail": "accountNumber is required"
}

Valid Account Type

Validates that the account type is either "checking" or "savings".

Sample Invalid Request:

{
  "customer": {
    "hsid": "123e4567-e89b-12d3-a456-426614174000"
  },
  "paymentMethod": {
    "type": "BANK_ACCOUNT",
    "paymentMethodDetails": {
      "type": "BANK_ACCOUNT",
      "accountNumber": "987654321",
      "routingNumber": "123456789",
      "accountType": "business",
      "nameOnAccount": "John Doe"
    }
  }
}

Sample Error Response:

{
  "title": "PAYMENT_METHOD_ERROR",
  "status": 400,
  "detail": "accountType is not valid"
}

Required Account Type

Validates that the account type is provided.

Sample Invalid Request:

{
  "customer": {
    "hsid": "123e4567-e89b-12d3-a456-426614174000"
  },
  "paymentMethod": {
    "type": "BANK_ACCOUNT",
    "paymentMethodDetails": {
      "type": "BANK_ACCOUNT",
      "accountNumber": "987654321",
      "routingNumber": "123456789",
      "nameOnAccount": "John Doe"
    }
  }
}

Sample Error Response:

{
  "title": "PAYMENT_METHOD_ERROR",
  "status": 400,
  "detail": "accountType is required"
}

Bank Account Details Required

Validates that bank account details are provided.

Sample Invalid Request:

{
  "customer": {
    "hsid": "123e4567-e89b-12d3-a456-426614174000"
  },
  "paymentMethod": {
    "type": "BANK_ACCOUNT"
  }
}

Sample Error Response:

{
  "title": "PAYMENT_METHOD_ERROR",
  "status": 400,
  "detail": "Bank Account details are needed"
}

Routing Number Required

Validates that the routing number is provided.

Sample Invalid Request:

{
  "customer": {
    "hsid": "123e4567-e89b-12d3-a456-426614174000"
  },
  "paymentMethod": {
    "type": "BANK_ACCOUNT",
    "paymentMethodDetails": {
      "type": "BANK_ACCOUNT",
      "accountNumber": "987654321",
      "accountType": "checking",
      "nameOnAccount": "John Doe"
    }
  }
}

Sample Error Response:

{
  "title": "PAYMENT_METHOD_ERROR",
  "status": 400,
  "detail": "routingNumber is required"
}

Routing Number Format

Validates that the routing number is exactly 9 digits.

Sample Invalid Request:

{
  "customer": {
    "hsid": "123e4567-e89b-12d3-a456-426614174000"
  },
  "paymentMethod": {
    "type": "BANK_ACCOUNT",
    "paymentMethodDetails": {
      "type": "BANK_ACCOUNT",
      "accountNumber": "987654321",
      "routingNumber": "12345678",
      "accountType": "checking",
      "nameOnAccount": "John Doe"
    }
  }
}

Sample Error Response:

{
  "title": "PAYMENT_METHOD_ERROR",
  "status": 400,
  "detail": "routingNumber must be a 9 digit number"
}

Name on Account Required

Validates that the name on account is provided.

Sample Invalid Request:

{
  "customer": {
    "hsid": "123e4567-e89b-12d3-a456-426614174000"
  },
  "paymentMethod": {
    "type": "BANK_ACCOUNT",
    "paymentMethodDetails": {
      "type": "BANK_ACCOUNT",
      "accountNumber": "987654321",
      "routingNumber": "123456789",
      "accountType": "checking"
    }
  }
}

Sample Error Response:

{
  "title": "PAYMENT_METHOD_ERROR",
  "status": 400,
  "detail": "Name on account is required"
}

Invalid Payment Method Type

Validates that bank account type is applicable for the payment method.

Sample Invalid Request:

{
  "customer": {
    "hsid": "123e4567-e89b-12d3-a456-426614174000"
  },
  "paymentMethod": {
    "type": "CARD",
    "paymentMethodDetails": {
      "type": "BANK_ACCOUNT",
      "accountNumber": "987654321",
      "routingNumber": "123456789",
      "accountType": "checking",
      "nameOnAccount": "John Doe"
    }
  }
}

Sample Error Response:

{
  "title": "PAYMENT_METHOD_ERROR",
  "status": 400,
  "detail": "BANK_ACCOUNT type is not applicable for paymentMethod.type"
}

Card Categories Validation

Medication Label Validation

Validates that when using cardCategories for manufacturer cards, the medication label must not be empty and cannot exceed 100 characters.

Sample Invalid Request:

{
  "customer": {
    "hsid": "123e4567-e89b-12d3-a456-426614174000"
  },
  "paymentMethod": {
    "type": "CARD",
    "paymentMethodDetails": {
      "nameOnCard": "John Doe"
    },
    "cardCategories": [
      {
        "type": "MANUFACTURER_CARD",
        "medications": [
          {
            "label": "",
            "value": "125mg"
          }
        ]
      }
    ]
  }
}

Sample Error Response:

{
  "title": "PAYMENT_METHOD_ERROR",
  "status": 400,
  "detail": "Medication label cannot be empty and maximum allowed length is 100"
}

Medication Value Validation

Validates that when using cardCategories for manufacturer cards, the medication value must not be empty and cannot exceed 100 characters.

Sample Invalid Request:

{
  "customer": {
    "hsid": "123e4567-e89b-12d3-a456-426614174000"
  },
  "paymentMethod": {
    "type": "CARD",
    "paymentMethodDetails": {
      "nameOnCard": "John Doe"
    },
    "cardCategories": [
      {
        "type": "MANUFACTURER_CARD",
        "medications": [
          {
            "label": "Acetaminophen",
            "value": ""
          }
        ]
      }
    ]
  }
}

Sample Error Response:

{
  "title": "PAYMENT_METHOD_ERROR",
  "status": 400,
  "detail": "Medication value cannot be empty and maximum allowed length is 100"
}

Invalid Card Category Type

Validates that the card category type must be valid. The only supported card category type is MANUFACTURER_CARD.

Sample Invalid Request:

{
  "customer": {
    "hsid": "123e4567-e89b-12d3-a456-426614174000"
  },
  "paymentMethod": {
    "type": "CARD",
    "paymentMethodDetails": {
      "nameOnCard": "John Doe"
    },
    "cardCategories": [
      {
        "type": "UNKNOWN_TYPE",
        "medications": [
          {
            "label": "Acetaminophen",
            "value": "125mg"
          }
        ]
      }
    ]
  }
}

Sample Error Response:

{
  "title": "PAYMENT_METHOD_ERROR",
  "status": 400,
  "detail": "Invalid card category type"
}

Card Information Validation

Name on Card Requirement

Validates that the name on card field is not blank.

Sample Invalid Request:

{
  "customer": {
    "hsid": "123e4567-e89b-12d3-a456-426614174000"
  },
  "paymentMethod": {
    "type": "CARD",
    "paymentMethodDetails": {
      "nameOnCard": ""
    }
  }
}

Sample Error Response:

{
  "title": "PAYMENT_METHOD_ERROR",
  "status": 406,
  "detail": "Name on card must not be blank."
}

Card Number in Name Field

Validates that the name field doesn't contain a card number.

Sample Invalid Request:

{
  "customer": {
    "hsid": "123e4567-e89b-12d3-a456-426614174000"
  },
  "paymentMethod": {
    "type": "CARD",
    "paymentMethodDetails": {
      "nameOnCard": "John Doe 4111111111111111"
    }
  }
}

Sample Error Response:

{
  "title": "PAYMENT_METHOD_ERROR",
  "status": 406,
  "detail": "Please make sure that the name field doesn't contain a card number."
}

Vendor Payment Method ID Required

Validates that the vendor payment method ID is provided.

tip

Required only payment method type card

Sample Invalid Request:

{
  "customer": {
    "hsid": "123e4567-e89b-12d3-a456-426614174000"
  },
  "paymentMethod": {
    "type": "CARD",
    "paymentMethodDetails": {
      "nameOnCard": "John Doe"
    }
  }
}

Sample Error Response:

{
  "title": "PAYMENT_METHOD_ERROR",
  "status": 406,
  "detail": "vendorPaymentMethodId is required"
}

Payment Method Validation

Payment Method Required

Validates that the payment method is provided.

Sample Invalid Request:

{
  "customer": {
    "hsid": "123e4567-e89b-12d3-a456-426614174000"
  }
}

Sample Error Response:

{
  "title": "PAYMENT_METHOD_ERROR",
  "status": 406,
  "detail": "paymentMethod is required"
}

Payment Method Type Required

Validates that the payment method type is provided.

Sample Invalid Request:

{
  "customer": {
    "hsid": "123e4567-e89b-12d3-a456-426614174000"
  },
  "paymentMethod": {
    "vendorPaymentMethodId": "pm_123456789"
  }
}

Sample Error Response:

{
  "title": "PAYMENT_METHOD_ERROR",
  "status": 406,
  "detail": "paymentMethod type is required"
}

Error Code Summary​

Nickname Validation​

Bank Account Validation​

Card Categories Validation​

Card Information Validation​

Payment Method Validation​

Error Code Details​

Nickname Validation​

Bank Account Validation​

Card Categories Validation​

Card Information Validation​

Payment Method Validation​

Error Code Summary

Nickname Validation

Bank Account Validation

Card Categories Validation

Card Information Validation

Payment Method Validation

Error Code Details

Nickname Validation

Bank Account Validation

Card Categories Validation

Card Information Validation

Payment Method Validation