Skip to main content
Version: v2

Payment API Error Codes

This page documents all error codes for the Payment API (v2). These errors occur when processing payments that involve one or more payment methods. Each error includes the code name, HTTP status, description, recommended developer action, and notes where applicable.

Error Summary​

Authorization error​

Error TitleHTTP StatusError Message
FORBIDDEN403403 FORBIDDEN. RequestId: ${x-request-id}

Resource Not Found error​

Error TitleHTTP StatusError Message
NOT_FOUND404paymentId not found

Schema validation error​

Payment Object​

Error TitleHTTP StatusError Message
INVALID_REQUEST400paymentId must be valid UUID
INVALID_REQUEST400amount is required
INVALID_REQUEST400amount must be an integer between 1 and 99999999
INVALID_REQUEST400amount must equal the sum of paymentAllocations[:].amount
INVALID_REQUEST400merchantTransactionId is required
INVALID_REQUEST400merchantTransactionId cannot exceed 50 characters
INVALID_REQUEST400description cannot exceed 100 characters
INVALID_REQUEST400statementDescriptorSuffix only allows alphanumeric, space, hyphen and dot, and must contain at least one letter
INVALID_REQUEST400statementDescriptorSuffix cannot exceed 10 characters
INVALID_REQUEST400metadata cannot exceed 20 entries
INVALID_REQUEST400metadata key cannot exceed 40 characters
INVALID_REQUEST400metadata value cannot exceed 100 characters
INVALID_REQUEST400paymentAllocations is required and must contain at least 2 items
INVALID_REQUEST400paymentAllocations cannot contain more than 2 items
INVALID_REQUEST400paymentAllocations[n].amount is required
INVALID_REQUEST400paymentAllocations[n].amount must be an integer between 1 and 99999999
INVALID_REQUEST400paymentAllocations[n].paymentMethodId is required
INVALID_REQUEST400paymentAllocations[n].paymentMethodId must be valid UUID

Customer Object​

Error TitleHTTP StatusError Message
INVALID_REQUEST400customer object is required
INVALID_REQUEST400customer object must include at least one of customer.hsid, customer.enterpriseId, or customer.metadata
INVALID_REQUEST400customer.firstName cannot exceed 50 characters
INVALID_REQUEST400customer.lastName cannot exceed 50 characters
INVALID_REQUEST400customer.email must be a valid email address
INVALID_REQUEST400customer.email cannot exceed 120 characters
INVALID_REQUEST400customer.ssn must contain only digits and cannot exceed 4 characters
INVALID_REQUEST400customer.dateOfBirth must be a valid date in format YYYY-MM-DD
INVALID_REQUEST400customer.zip5 must be exactly 5 digits
INVALID_REQUEST400customer.phoneNumber.countryCode must contain only digits and must be 1 to 3 characters long
INVALID_REQUEST400customer.phoneNumber.number must contain only digits and must be 4-11 characters long
INVALID_REQUEST400customer.enterpriseIdentifier must contain only digits
INVALID_REQUEST400customer.hsid must be a valid UUID

Business Rule Violation Error​

Error TitleHTTP StatusError Message
UNPROCESSABLE_ENTITY422merchantTransactionId not found
UNPROCESSABLE_ENTITY422Customer identifier missing
UNPROCESSABLE_ENTITY422Customer not found for given enterpriseIdentifier
UNPROCESSABLE_ENTITY422Payment method ending with {last4} is not configured. Please provide a valid payment method
UNPROCESSABLE_ENTITY422Manufacturer card ending with {last4} not enabled for this merchant. Please use a different payment method
UNPROCESSABLE_ENTITY422The sum of paymentAllocations[:].amount cannot exceed 100000000
UNPROCESSABLE_ENTITY422paymentAllocations[n].paymentMethodId not found. Please provide a valid payment method
UNPROCESSABLE_ENTITY422paymentAllocations[:].paymentMethodId must be unique
UNPROCESSABLE_ENTITY422Payment method ending with {last4} is invalid. Please provide a valid payment method
UNPROCESSABLE_ENTITY422This card requires an additional security step to be performed by the customer. Please have the customer enter the card via text or email; otherwise, have the customer provide a different payment method.
UNPROCESSABLE_ENTITY422Split payments cannot be processed using a bank account. Please select a different payment method
UNPROCESSABLE_ENTITY422The payment cannot be processed because the maximum retry limit for this merchantTransactionId has been reached
UNPROCESSABLE_ENTITY422agent.userId is required

Payment Details Object​

Error TitleHTTP StatusError Message
UNPROCESSABLE_ENTITY422 UNPROCESSABLE ENTITYpaymentDetails.qualifiedAmount is required when paymentDetails is provided
UNPROCESSABLE_ENTITY422 UNPROCESSABLE ENTITYsum of paymentDetails.qualifiedAmount and paymentDetails.visionAmount cannot exceed amount
UNPROCESSABLE_ENTITY422 UNPROCESSABLE ENTITYpaymentDetails.prescriptionAmount cannot exceed paymentDetails.qualifiedAmount

Payment processor error​

PaymentAllocation processor error​

HTTP Status Codes
  • Allocation-specific errors are returned at the allocation level under paymentAllocations[n] within the parent processor response.
  • For allocation-level entries, the HTTP status is shown as NA, as it is inherited from the parent 422 UNPROCESSABLE_ENTITY response.
Error Code Coverage
  • Error Code Coverage: Only the known and documented error-code combinations are listed here; additional combinations may occur.
  • Vendor Error Details: error.errorDetails reflects data returned by the vendor. The structure is not guaranteed; all fields are optional and subject to change.
Error TitleHTTP StatusError Message
PAYMENT_ERRORNAPayment method could not be authorized. Please try a different payment method.
PAYMENT_ERRORNAThe payment can't be authorized. Contact issuer for more information.
PAYMENT_ERRORNAThe card was declined because the transaction requires authentication such as 3D Secure.
PAYMENT_ERRORNAPayment method could not be authorized. This payment method requires authentication from a customer.
PAYMENT_ERRORNAThe card was declined for an unknown reason. Contact issuer for more information.
PAYMENT_ERRORNAThe card does not support this type of purchase. Contact issuer for more information.
PAYMENT_ERRORNAThe customer has exceeded the balance, credit limit, or transaction amount limit available on their card. Contact issuer for more information.
PAYMENT_ERRORNAThe card does not support the specified currency.
PAYMENT_ERRORNAThe card has expired.
PAYMENT_ERRORNAThe CVC number is incorrect.
PAYMENT_ERRORNAThe card number is incorrect.
PAYMENT_ERRORNAThe postal code is incorrect. Contact issuer for more information.
PAYMENT_ERRORNAThe customer's account has insufficient funds to complete the purchase. Please use an alternative payment method.
PAYMENT_ERRORNAThe card, or account the card is connected to, is invalid. Contact issuer for more information.
PAYMENT_ERRORNAThe payment amount is invalid, or exceeds the amount that's allowed. Contact issuer for more information
PAYMENT_ERRORNAThe expiration month is invalid.
PAYMENT_ERRORNAThe expiration year is invalid.
PAYMENT_ERRORNAThe PIN entered is incorrect.
PAYMENT_ERRORNAThe card issuer couldn't be reached, please try again.
PAYMENT_ERRORNAThe card was declined because it requires a PIN.
PAYMENT_ERRORNAAn error occurred while processing the card, please try again.
PAYMENT_ERRORNASomething went wrong and we are unable to complete your request. Please try again later.
PAYMENT_ERRORNATest card was used. Use valid card to make payment.
PAYMENT_ERRORNAThe card was declined for an unknown reason. Try again or contact issuer for more information.
PAYMENT_ERRORNAThe customer has exceeded the balance or credit limit available on their card. Please try another payment method.
PAYMENT_ERRORNAIIAS information is required to authorize this HSA/FSA card.

Error Details​

Authorization error​

Resource Not Found error​

Schema validation error​

Payment Object​

Customer Object​

Business Rule Violation Error​

Payment Details Object​

Payment processor error​

Payment Allocation processor error​

HTTP Status Codes
  • Allocation-specific errors are returned at the allocation level under paymentAllocations[n] within the parent processor response.
  • For allocation-level entries, the HTTP status is shown as NA, as it is inherited from the parent 422 UNPROCESSABLE_ENTITY response.
Error Code Coverage
  • Error Code Coverage: Only the known and documented error-code combinations are listed here; additional combinations may occur.
  • Vendor Error Details: error.errorDetails reflects data returned by the vendor. The structure is not guaranteed; all fields are optional and subject to change.