API Error Codes Reference

Auto-generated. Do not edit manually.

Agent Object Error Codes

Location

See details

Error Code Summary

Error Title Reference	Error Title	HTTP Status	Detail Message	Scenario	Resolution
First Name Validation	INVALID_REQUEST	400 BAD REQUEST	agent.firstName cannot be more than 50 characters	When first name exceeds 50 characters	Ensure the agent's first name is 50 characters or less
Last Name Validation	INVALID_REQUEST	400 BAD REQUEST	agent.lastName cannot be more than 50 characters	When last name exceeds 50 characters	Ensure the agent's last name is 50 characters or less
User ID Validation	INVALID_REQUEST	400 BAD REQUEST	agent.userId is required	When agent user ID is missing, null or empty	Include a valid agent.userId in the request

Authorization Error Codes

Location

See details

Error Code Summary

Error Title Reference	Error Title	HTTP Status	Detail Message	Scenario	Resolution
Authorization Validation
WITHOUT_TOKEN	UNAUTHORIZED	401 UNAUTHORIZED	access_token is missing	When no access token is provided in the request	Include a valid access token in the Authorization header
EXPIRED_TOKEN	UNAUTHORIZED	401 UNAUTHORIZED	jwt signature verification failed: 'exp' claim expired at	When the JWT token is expired	Generate a new JWT token using valid credentials
NULL_TOKEN	UNAUTHORIZED	401 UNAUTHORIZED	invalid jwt: invalid jwt string	When the JWT token is null or malformed	Ensure a valid, properly formatted JWT token is provided
CROSS_MERCHANT_TOKEN	FORBIDDEN	403 FORBIDDEN	403 FORBIDDEN	When the token is for a different merchant	Use a token issued for the correct merchant ID
RESTRICTED_SCOPE_TOKEN	FORBIDDEN	403 FORBIDDEN	insufficient_scope	When the token does not have sufficient scope	Request a token with the required scopes for the operation
INVALID_MERCHANTID	FORBIDDEN	403 FORBIDDEN	403 FORBIDDEN	When the merchant ID is invalid	Provide a valid merchant ID that you are authorized to access
MISSING_MERCHANT_HEADER	BAD_REQUEST	400 BAD REQUEST	Missing request header 'X-Merchant-Id' for method parameter of type UUID	When X-Merchant-Id header is missing	Provide a valid merchant ID that you are authorized to access

Consent Object Error Codes

Location

See details

Error Code Summary

Error Title Reference	Error Title	HTTP Status	Detail Message	Scenario	Resolution
Merchant Consent Text Validation	INVALID_REQUEST	400 BAD REQUEST	Consent is Invalid!	Merchant consent text is invalid or contains unsupported characters	Remove special characters from consent text
Merchant Consent Id Validation	INVALID_REQUEST	400 BAD REQUEST	merchantConsentId is required	Merchant consent id is missing or invalid	Provide a valid merchant consent ID in the request
Consent Collection Timestamp Validation	INVALID_REQUEST	400 BAD REQUEST	collectionTimestamp is required	Consent collection timestamp is missing or invalid	Include a valid collection timestamp in ISO 8601 format
Consent Collection Details Validation	INVALID_REQUEST	400 BAD REQUEST	collectionDetails are not valid	Consent collection details are missing or invalid	Provide complete and valid collection details
Agent Object Requirement with PPD Consent	INVALID_REQUEST	400 BAD REQUEST	agent object is required with PPD consent	PPD consent requires agent object information	Include agent object with all required fields when using PPD consent

Customer Object Error Codes

Location

See details

Error Code Summary

Error Title Reference	Error Title	HTTP Status	Detail Message	Scenario	Resolution
Identifier Validation
Missing Required Identifiers	INVALID_REQUEST	400 BAD REQUEST	customer should contain hsid, enterpriseId or metadata	Required customer identifiers are missing	Include at least one of hsid, enterpriseId, or metadata in the customer object
Invalid Enterprise ID	INVALID_REQUEST	400 BAD REQUEST	invalid enterpriseId	Enterprise ID is not all digits	Ensure enterpriseId contains only numeric digits
Invalid HSID	INVALID_REQUEST	400 BAD REQUEST	invalid hsid	HSID is not a valid UUID	Provide a valid UUID format for the hsid
Customer Not found for given Enterprise Id	NOT_FOUND	404 NOT FOUND	Customer not found for given enterpriseId	No customer found for the provided enterpriseId	Verify the enterpriseId is correct and exists in the system
Metadata Validation
Exceeded Metadata Entries	INVALID_REQUEST	400 BAD REQUEST	Exceeded the max number of entries in metadata. Max 20	Metadata has more than 20 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	Metadata key exceeds 40 characters	Ensure all metadata keys are 40 characters or less
Metadata Value Size Exceeded	INVALID_REQUEST	400 BAD REQUEST	Metadata value size bigger than: 100	Metadata value exceeds 100 characters	Ensure all metadata values are 100 characters or less
Demographics Validation
Email Validation	INVALID_REQUEST	400 BAD REQUEST	customer.email Email should be valid	Email is not in valid format	Provide a valid email address format (e.g., user@example.com)
First Name Length Exceeded	INVALID_REQUEST	400 BAD REQUEST	First name max length is 100	First name exceeds 100 characters	Ensure the first name is 100 characters or less
Last Name Length Exceeded	INVALID_REQUEST	400 BAD REQUEST	Last name max length is 100	Last name exceeds 100 characters	Ensure the last name is 100 characters or less
SSN Validation	INVALID_REQUEST	400 BAD REQUEST	customer.ssnLastFour must match "^[0-9]4$"	SSN last four is not 4 digits	Provide exactly 4 digits for the SSN last four
ZIP Code Validation	INVALID_REQUEST	400 BAD REQUEST	Zip 5 must be exactly 5 digits long.	ZIP code is not 5 digits	Provide exactly 5 digits for the ZIP code
Date of Birth Validation	INVALID_REQUEST	400 BAD REQUEST	customer.dateOfBirth Invalid date of birth: <value>	Date of birth is not in ISO format	Use ISO 8601 format for date of birth (YYYY-MM-DD)
Country Code Validation	INVALID_REQUEST	400 BAD REQUEST	customer.phoneNumber.countryCode invalid countryCode	Country code is not valid	Use a valid country code (e.g., 01, 91)
Phone Number Validation	INVALID_REQUEST	400 BAD REQUEST	customer.phoneNumber.number invalid number	Phone number is not valid	Provide a valid phone number format

Payment Details Object Error Codes

Location

See details

Error Code Summary

Error Title Reference	Error Title	HTTP Status	Detail Message	Scenario	Resolution
Payment Details Validation
Payment Details Not Valid	INVALID_REQUEST	400 BAD REQUEST	payment details are not valid	When Qualified Amount is either missing or null	Include a valid qualified amount in the payment details
Qualified + Vision Amount Exceeds Total Amount	INVALID_REQUEST	400 BAD REQUEST	details qualified amount + vision amount cannot be greater than amount	When the sum of qualified amount and vision amount exceeds the total amount	Ensure the sum of qualified and vision amounts is less than or equal to the total amount
Prescription Amount Exceeds Qualified Amount	INVALID_REQUEST	400 BAD REQUEST	details prescription amount cannot be greater than qualified amount	When prescription amount is greater than qualified amount	Ensure prescription amount is less than or equal to qualified amount

Payment Method Details Error Codes

Location

See details

Error Code Summary

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

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)

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

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

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")

Payment Object Error Codes

Location

See details

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

Cancel Payment Error Codes

Location

See details

Error Code Summary

Error Title Reference	Error Title	HTTP Status	Detail Message	Scenario	Resolution
Missing Cancellation Reason	INVALID_REQUEST	400 BAD REQUEST	paymentCancellationReason must not be null	Reason not provided	Include a valid cancellation reason in the request
Invalid Cancellation Reason Enum	INVALID_REQUEST	400 BAD REQUEST	Failed to read HTTP message Please review API specs https://docs.healthsafepay.com/api-reference/	Reason is not one of: DUPLICATE, FRAUDULENT, REQUESTED_BY_CUSTOMER, ABANDONED	Use only allowed values: DUPLICATE, FRAUDULENT, REQUESTED_BY_CUSTOMER, or ABANDONED
Invalid Payment Id	INVALID_REQUEST	400 BAD REQUEST	Invalid Payment, Payment Id: [${paymentId}], Payment Status: [COMPLETED]	Payment is already completed or invalid	Ensure payment is in a cancellable state (Only AUTHORIZED and ACCEPTED payments can be cancelled)
Invalid Payment Id Format	INVALID_REQUEST	400 BAD REQUEST	Invalid payment id	Payment id is not found or is malformed	Provide a valid payment ID in the correct UUID format

Capture Payment Error Codes

Location

See details

Error Code Summary

Error Title Reference	Error Title	HTTP Status	Detail Message	Scenario	Resolution
Invalid Amount	INVALID_REQUEST	400 BAD REQUEST	amount Invalid amount ${amount}, it must be between 1 and 99999999	Amount is zero, negative, or out of allowed range	Provide a positive integer amount between 1 and 99999999
Invalid Decimal Amount	INVALID_REQUEST	400 BAD REQUEST	amount Invalid amount ${amount}, it must be between 1 and 99999999	Amount is not a valid integer (decimal provided)	Use whole number amounts without decimals or fractional values
Capture Exceeds Authorized	INVALID_REQUEST	400 BAD REQUEST	Capture amount exceeds authorized amount or no amount authorized for capture	Capture amount is greater than pre-authorized amount or no pre-authorization exists	Ensure capture amount is less than or equal to the authorized amount
Metadata Key Size	INVALID_REQUEST	400 BAD REQUEST	payment.metadata Metadata key size bigger than: 40	Metadata key exceeds 40 characters	Keep metadata keys to 40 characters or less
Metadata Value Size	INVALID_REQUEST	400 BAD REQUEST	payment.metadata Metadata value size bigger than: 100	Metadata value exceeds 100 characters	Keep metadata values to 100 characters or less
Metadata Entry Limit	INVALID_REQUEST	400 BAD REQUEST	payment.metadata Exceeded the max number of entries in metadata. Max 20	More than 20 metadata entries provided	Limit metadata entries to a maximum of 20 key-value pairs
Invalid Payment Status	INVALID_REQUEST	400 BAD REQUEST	Payment with ${paymentId} is in invalid status: COMPLETED	Attempt to capture a payment that is already completed	Only attempt to capture payments that are in AUTHORIZED status

Payment Authorization Error Codes

Location

See details

Error Code Summary

Error Title Reference	Error Title	HTTP Status	Detail Message	Scenario	Resolution
Payment Authorization
Cross-Merchant Payment Capture	FORBIDDEN	403 FORBIDDEN	Not authorized to capture this payment	When merchant2 attempts to capture a payment initiated by merchant1	Use the same merchant credentials that were used to create the payment
Cross-Merchant Payment Cancellation	FORBIDDEN	403 FORBIDDEN	Not authorized to cancel this payment	When merchant2 attempts to cancel a payment initiated by merchant1	Use the same merchant credentials that were used to create the payment

Payment Error Codes

Location

See details

Error Code Summary

Error Title Reference	Error Title	HTTP Status	Detail Message	Scenario	Resolution
Consent Requirement	INVALID_REQUEST	400 BAD REQUEST	Consent is required!	When a ACH payment is initiated without the required consent information	Include a valid consent object with all required fields for ACH Payments
VendorPaymentMethodId Reuse	INVALID_REQUEST	400 BAD REQUEST	VendorPaymentMethodId cannot be reused.	When attempting to use a vendor payment method ID that has already been used	Use a unique vendor payment method ID that hasn't been used before
Payment Method Not Found	NOT_ACCEPTABLE	406 NOT ACCEPTABLE	Payment Method not found	When the requested payment method cannot be found in the system	Verify the payment method ID is correct and exists for the customer
Payment Method Authorization Failed	NOT_ACCEPTABLE	406 NOT ACCEPTABLE	Payment method could not be authorized. Please try a different payment method.	When the payment method cannot be authorized for the transaction	Try a different payment method or check with the customer about potential issues with their payment method
Payment Method Type Not Configured	NOT_ACCEPTABLE	406 NOT ACCEPTABLE	Payment method type is not configured.	When the payment method type is not configured for the merchant	Contact support to ensure your merchant account is configured for the payment method type you're trying to use
Payment Already Processed	INVALID_REQUEST	400 BAD REQUEST	Payment already processed or in process for given transactionId	When attempting to process a payment with merchant transaction id that is already processed or currently being processed	Use a unique merchant transaction ID for each payment request
Maximum Retries Reached	PAYMENT_ERROR	403 FORBIDDEN	Payment failed after maximum retries	When the maximum number of payment retry attempts has been reached	Create a new payment transaction or contact support for assistance
Payment Information Not Found	NOT_FOUND	404 NOT FOUND	Payment information not found.	When the requested payment information cannot be found in the system or when the payment is not associated to the merchant	Verify the payment ID is correct and belongs to your merchant account
Missing Merchant Transaction ID in GetPayment Call	INVALID_REQUEST	400 BAD REQUEST	Required query parameter 'merchantTransactionId' is not present. Please review API specs https://docs.healthsafepay.com/api-reference/	When the merchantTransactionId is missing from the request	Include the merchantTransactionId as a query parameter in your request

Stripe Payment Processing Error Codes

Location

See details

Error Code Summary

Error Title Reference	Error Title	HTTP Status	Detail Message	Scenario	Resolution
Card Authentication Errors	NOT_ACCEPTABLE	406 NOT ACCEPTABLE	This 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.	When card requires 3D Secure authentication in agent session	Guide the customer to complete the card entry via SMS or email where 3D Secure can be handled, or request an alternative payment method.
	NOT_ACCEPTABLE	406 NOT ACCEPTABLE	Payment method could not be authorized. This payment method requires authentication from a customer.	When card requires 3D Secure authentication in agent session	Guide the customer to complete the card entry via SMS or email where 3D Secure can be handled, or request an alternative payment method.
Card Decline Errors	NOT_ACCEPTABLE	406 NOT ACCEPTABLE	The card was declined for an unknown reason. Contact issuer for more information.	Card declined	Advise the customer to contact their card issuer to determine the reason for the decline, or use an alternative payment method.
	NOT_ACCEPTABLE	406 NOT ACCEPTABLE	An error occurred while processing the card, please try again.	Generic processing error	Attempt the transaction again. If the issue persists, request a different payment method from the customer.
	NOT_ACCEPTABLE	406 NOT ACCEPTABLE	Payment method could not be authorized. Please try a different payment method.	General payment authorization failure	Request that the customer provide an alternative payment method.
	NOT_ACCEPTABLE	406 NOT ACCEPTABLE	Payment method is canceled by a customer or expired by the financial partner	Card no longer valid	Ask the customer to update their card information or provide a new payment method.
Card Validation Errors	NOT_ACCEPTABLE	406 NOT ACCEPTABLE	The CVC number is incorrect.	Invalid CVC	Prompt the customer to re-enter the correct CVC for their card.
	NOT_ACCEPTABLE	406 NOT ACCEPTABLE	The card has expired.	Expired card	Request that the customer provide a card that has not expired.
Financial Limit Errors	NOT_ACCEPTABLE	406 NOT ACCEPTABLE	The customer's account has insufficient funds to complete the purchase. Please use an alternative payment method.	Insufficient funds error (specific to payments)	Advise the customer to use a different payment method or to fund their account before attempting the transaction again.
	NOT_ACCEPTABLE	406 NOT ACCEPTABLE	The customer has exceeded the balance, credit limit, or transaction amount limit available on their card. Contact issuer for more information.	Card limit exceeded (specific to payments)	Suggest that the customer contact their card issuer regarding their limits, or use a different payment method.
Bank Account Errors	NOT_ACCEPTABLE	406 NOT ACCEPTABLE	The customer's bank account has been closed.	Account closed	Inform the customer that the bank account has been closed and request an alternative payment method.
	NOT_ACCEPTABLE	406 NOT ACCEPTABLE	The customer's bank account could not be located.	Account not found	Verify the bank account details with the customer and correct any errors, or request an alternative payment method.
Early Warning System Errors	NOT_ACCEPTABLE	406 NOT ACCEPTABLE	earlyWarningMessage	Early warning system validation error	Review the specific early warning message and take appropriate action based on the warning type. This may require additional verification or an alternative payment method.

Refund Error Codes

Location

See details

Error Code Summary

Error Title Reference	Error Title	HTTP Status	Detail Message	Scenario	Resolution
Refund Amount Validation	INVALID_REQUEST	400 BAD REQUEST	Refund amount cannot be more than the un-refunded amount of the original payment	When attempting to refund more than the available amount	Ensure refund amount is less than or equal to the available (un-refunded) amount
	INVALID_REQUEST	400 BAD REQUEST	When paymentMethodId is present, amount is required	When using paymentMethodId without specifying an amount	Include a valid amount when using paymentMethodId
Payment Status Validation	PAYMENT_ERROR	400 BAD REQUEST	Cannot issue refund for this payment	When attempting to refund a payment not in COMPLETED status	Only attempt to refund payments that are in COMPLETED status
Payment Status Validation	INVALID_REQUEST	400 BAD REQUEST	Cannot issue refund for this payment	When attempting to refund for disputed fraudulent transaction	Disputed fraudulent transactions cannot be refunded
	INVALID_REQUEST	400 BAD REQUEST	Refunds can only be processed for captured payments	When attempting to refund a payment in AUTHORIZED status	Capture the payment before attempting to refund it or cancel the payment if not required.
	INVALID_REQUEST	400 BAD REQUEST	The amount given exceeds the allowed refund limit	When attempting to issue Credit beyond allowed refund limit	Reduce the refund amount to be within the allowed limit
Payment Identifier Validation	INVALID_REQUEST	400 BAD REQUEST	paymentId or paymentMethodId is required	When neither paymentId nor paymentMethodId is provided	Include either paymentId or paymentMethodId in the request
	INVALID_REQUEST	400 BAD REQUEST	Either paymentId or paymentMethodId should be provided. The request has both paymentId and paymentMethodId	When both paymentId and paymentMethodId are provided	Use either paymentId or paymentMethodId, not both
	INVALID_REQUEST	400 BAD REQUEST	When paymentMethodId is present, customer should contain hsid, enterpriseId or metadata	When customer identifiers are missing with paymentMethodId	Include customer identifiers when using paymentMethodId
Payment Method Status Validation	INVALID_REQUEST	400 BAD REQUEST	Payment method is canceled by a customer or expired by the financial partner	When attempting to refund using an invalid payment method	Use only valid, active payment methods for refunds
	INVALID_REQUEST	400 BAD REQUEST	Credit is not allowed for bank accounts.	When attempting to refund to a bank account payment method	Use card payment methods for unlinked refunds/credits
	INVALID_REQUEST	400 BAD REQUEST	Invalid paymentMethodId	When attempting to issue Credit for Invalid or Deleted Payment Method	Use only valid, active payment methods for refunds
Payment Dispute Validation	INVALID_REQUEST	400 BAD REQUEST	Payment is in dispute and not available for refund	When attempting to refund a payment that is in dispute	Refunds are not applicable for payments where the merchant has lost the dispute, as the customer has already received the funds through the dispute resolution process.
Refund Already Exists	INVALID_REQUEST	400 BAD REQUEST	This payment is already refunded	When attempting to create a refund on already completed payment	If the payment has already been fully refunded, additional linked refunds are not allowed. To provide more funds to the customer, issue a credit using a valid payment method.
Refund Already Exists (merchantTransactionId)	INVALID_REQUEST	400 BAD REQUEST	Refund already exists for the given merchantTransactionId	When attempting to create a refund with a duplicate merchantTransactionId	Provide a unique merchantTransactionId for every refund transaction

Checkout Session Authorization Error Codes

Location

See details

Error Code Summary

Error Title Reference	Error Title	HTTP Status	Detail Message	Scenario	Resolution
Checkout Session Authorization	FORBIDDEN	403 FORBIDDEN	Access denied when attempting to save payment method using completed session	Attempting to save payment method with a completed checkout session	Create a new session for saving payment methods; completed sessions cannot be reused
	FORBIDDEN	403 FORBIDDEN	Access denied when attempting to save payment method using PAYMENT mode	Attempting to save payment method when session is in payment mode	Use PAYMENT_METHOD_ENTRY or WALLET or PAYMENT_WITH_WALLET mode for saving payment methods
	FORBIDDEN	403 FORBIDDEN	Access denied when attempting to poll setup payment method using PAYMENT mode	Attempting to poll for setup status when session is in payment mode	Use PAYMENT_METHOD_ENTRY or WALLET or PAYMENT_WITH_WALLET mode for saving payment methods
	FORBIDDEN	403 FORBIDDEN	Access denied when attempting to save payment method using cancelled session	Attempting to save payment method with a cancelled checkout session	Create a new session; cancelled sessions cannot be reused
	FORBIDDEN	403 FORBIDDEN	Not allowed to access this session	When merchant2 tries to access a session initiated by merchant1	Use the same merchant credentials that were used to create the session

Config Object Error Codes

Location

See details

Error Code Summary

Error Title Reference	Error & Status	Detail Message	Scenario	Resolution
Config Parameter Validation
saveDisabled/paymentMethodSaveMode not supported in [modes]	INVALID_REQUEST 400 BAD REQUEST	Invalid Request. Request parameter saveDisabled or paymentMethodSaveMode not supported in Mode: [modes]	When sending a request with saveDisabled=true or paymentMethodSaveMode specified, and mode contains fallback-not-possible modes	Remove saveDisabled or paymentMethodSaveMode parameters when using non-supported modes
Payment Method ID required for PAYMENT_METHOD_DISPLAY	INVALID_REQUEST 400 BAD REQUEST	Payment Method ID is required for mode - PAYMENT_METHOD_DISPLAY	When sending a request with PAYMENT_METHOD_DISPLAY mode but omitting the payment method ID	Include a valid payment method ID when using PAYMENT_METHOD_DISPLAY mode
saveDisabled and paymentMethodSaveMode cannot be used together	INVALID_REQUEST 400 BAD REQUEST	Invalid request: 'saveDisabled' and 'paymentMethodSaveMode' cannot be used together. Use only 'paymentMethodSaveMode'.	When sending a request with both saveDisabled and paymentMethodSaveMode specified	Use only paymentMethodSaveMode parameter, not both parameters together
Merchant name contains invalid characters	INVALID_REQUEST 400 BAD REQUEST	config.merchant.name Merchant name contains invalid characters	When the merchant name in the config object contains unsupported characters (only alphanumeric, space, hyphen, and dot)	Use only alphanumeric characters, spaces, hyphens, and dots in the merchant name
Merchant name must not be blank	INVALID_REQUEST 400 BAD REQUEST	config.merchant.name Merchant name must not be blank	When the merchant name in the config object is blank or not provided	Provide a non-empty merchant name in the config object
Merchant name character limit	INVALID_REQUEST 400 BAD REQUEST	config.merchant.name Merchant name must be less than or equal to 80 characters	When the merchant name in the config object exceeds 80 characters	Ensure merchant name is 80 characters or less
Invalid mode	INVALID_REQUEST 400 BAD REQUEST	Invalid mode	When providing an invalid session mode	Use one of the supported session modes (PAYMENT, PAYMENT_WITH_WALLET, WALLET, etc.)
Invalid PaymentMethodChannel	INVALID_REQUEST 400 BAD REQUEST	Invalid PaymentMethodChannel	When providing an invalid payment method channel	Use one of the supported payment method channels
Payment method type is not configured	INVALID_REQUEST 400 BAD REQUEST	Payment method type is not configured.	Payment method type is missing or not configured for the merchant during session creation	Ensure the payment method type is configured for your merchant account
You have no capture methods available	INVALID_REQUEST 400 BAD REQUEST	You have no capture methods available.	No available channels for configured payment methods (e.g., merchant configuration or session error)	Contact support to enable appropriate capture methods for your account
config.privacyPolicyUrl must be a valid URL	INVALID_REQUEST 400 BAD REQUEST	config.privacyPolicyUrl must be a valid URL	When privacyPolicyUrl in config is not a valid URL	Provide a valid, properly formatted URL for the privacy policy
Session Mode not applicable for guest checkout	INVALID_REQUEST 400 BAD REQUEST	Session Mode not applicable for guest checkout!	When a session mode is not allowed for guest checkout (WALLET, PAYMENT_METHOD_SELECT, PAYMENT_METHOD_ENTRY, PAYMENT_WITH_WALLET)	For guest checkout, use only supported modes like PAYMENT or PAYMENT_METHOD_DISPLAY
Invalid Card Category type	INVALID_REQUEST 400 BAD REQUEST	Invalid card category type config.cardCategories.type	When a card categories type is not given as Merchant configured type ( ex: MANUFACTURER_CARD )	Use only merchant-configured card category types
More than 100 medications	INVALID_REQUEST 400 BAD REQUEST	Maximum of 100 medications allowed in cardCategories[].medication	When a card categories medication having a more than 100 medications	Limit medications to 100 per card category
Card Categories given but Medication not provided	INVALID_REQUEST 400 BAD REQUEST	Medications cannot be empty in cardCategories[].medications	When a Card Categories given as Manufacturer card, medication should have to be provided	Provide at least one medication in cardCategories[].medications
More than 100 char in cardCategories.label	INVALID_REQUEST 400 BAD REQUEST	Category label cannot exceed 100 characters	When a Card Categories label consisting more then 100 characters	Limit card category label to 100 characters or less
More than 100 char or empty string in medication.value	INVALID_REQUEST 400 BAD REQUEST	Medication value cannot be empty and maximum allowed length is 100	When a Card Categories medication label consisting more then 100 characters	Provide a non-empty medication value of 100 characters or less
More than 100 char or empty string in medication.label	INVALID_REQUEST 400 BAD REQUEST	Medication label cannot be empty and maximum allowed length is 100	When a Card Categories medication value consisting more then 100 characters	Provide a non-empty medication label of 100 characters or less

Sessions API Error Codes

Location

See details

Error Code Summary

Error Title Reference	Error Title	HTTP Status	Detail Message	Scenario	Resolution
Session Controller Validation
Card WS2 check has failed	INVALID_REQUEST	400 BAD REQUEST	Card WS2 check has failed.	WS2 verification of agent information (e.g., MSID) failed during session creation	Ensure agent userid is part of PCI_WorkStation group
Session Id not found	NOT_FOUND	404 NOT FOUND	Session Id not found	When requesting a session that doesn't exist	Check that the session ID is correct and the session has been created
Your session has been canceled	SESSION_CANCELED	410 GONE	Your session has been canceled	When requesting a canceled session	Create a new session; canceled sessions cannot be reused
Your session is no longer valid	SESSION_TIMEOUT	401 UNAUTHORIZED	Your session is no longer valid	When requesting an expired session	Create a new session; expired sessions cannot be reused
Not allowed to access this session	FORBIDDEN	403 FORBIDDEN	Not allowed to access this session	When merchant ID in request doesn't match the session's merchant ID	Use the same merchant credentials that were used to create the session
Customer Identifier is Missing	INVALID_REQUEST	400 BAD REQUEST	Customer identifier is missing	When customer identifier is not provided for session modes: PAYMENT_METHOD_ENTRY, WALLET, PAYMENT_METHOD_SELECT, PAYMENT_METHOD_DISPLAY	Include a valid customer identifier (hsid, enterpriseId, or metadata)
Consent is required	INVALID_REQUEST	400 BAD REQUEST	Consent is required!	When consent is missing in PAYMENT mode	Include a valid consent object with the required fields
payment is required	INVALID_REQUEST	400 BAD REQUEST	payment is required	When payment object is missing for session modes: PAYMENT, PAYMENT_WITH_WALLET	Include a valid payment object with the required fields

Delete Payment Method Error Codes

Location

See details

Error Code Summary

Error Title Reference	Error Title	HTTP Status	Detail Message	Scenario	Resolution
Payment Method Configuration	PAYMENT_METHOD_ERROR	403 FORBIDDEN	Payment method: BANK_ACCOUNT not configured in Merchant: MerchantId	Attempting to delete a payment method type that is not configured for the merchant	Contact support to ensure your merchant account is configured for the payment method type you're trying to delete

Find Payment Method Error Codes

Location

See details

Error Code Summary

Error Title Reference	Error Title	HTTP Status	Detail Message	Scenario	Resolution
Customer Validation	INVALID_REQUEST	400 BAD REQUEST	customer is required	Customer object is missing or null	Include a valid customer object with appropriate identifiers (hsid, enterpriseId, or metadata)

SetUp Payment Method Error Codes

Location

See details

Error Code Summary

Error Title Reference	Error Title	HTTP Status	Detail Message	Scenario	Resolution
Reusing Vendor Payment Method	PAYMENT_METHOD_ERROR	400 BAD REQUEST	VendorPaymentMethodId cannot be reused	Attempting to save a payment method with a vendor payment method ID that's already in use	Use a unique vendor payment method ID that hasn't been used before
Manufacturer Card Validation	PAYMENT_METHOD_ERROR	400 BAD REQUEST	Manufacturer card cannot be default	Attempting to set a manufacturer card as default	Set either manufacturerCard=false or default=false, a manufacturer card cannot be the default payment method
	PAYMENT_METHOD_ERROR	400 BAD REQUEST	Agent is required to add manufacturer card	Missing agent information for manufacturer card (applicable only when using manufacturerCard=true)	Include complete agent information when setting up a manufacturer card
	PAYMENT_METHOD_ERROR	400 BAD REQUEST	Medication is required to add manufacturer card	Missing medication in cardCategories for manufacturer card	Include medication details in the cardCategories object for manufacturer cards
	PAYMENT_METHOD_ERROR	400 BAD REQUEST	Only one medication can be associated per manufacturer card	More than one medication added to cardCategories	Limit medication entries to one per manufacturer card
	PAYMENT_METHOD_ERROR	400 BAD REQUEST	MANUFACTURER_CARD category type is not enabled	If merchant request for Manufacturer card catgories when not configured in merchant settings	Contact support to enable manufacturer card category types for your merchant account
Maximum Retries Reached	NOT_ACCEPTABLE	406 NOT ACCEPTABLE	Maximum number of retries reached.	When the maximum number of payment setup retry attempts has been reached	Create a new payment setup attempt or contact support for assistance

Update Payment Method Error Codes

Location

See details

Error Code Summary

Error Title Reference	Error & Status	Detail Message	Scenario	Resolution
Agent Validation	INVALID_REQUEST 400 BAD REQUEST	Agent is required to update manufacturer card	Agent object is missing when updating manufacturer card	Include a valid agent object when updating a manufacturer card
Manufacturer Card Validation	INVALID_REQUEST 400 BAD REQUEST	Manufacturer card cannot be default	Both manufacturerCard and default are set to true	Set either manufacturerCard=false or default=false; a manufacturer card cannot be the default payment method
Payment Method Type Validation	INVALID_REQUEST 400 BAD REQUEST	Payment method type in request does not match the existing payment method	Type mismatch between request and existing payment method	Ensure the payment method type in the request matches the existing payment method type
Payment Method Status Validation	FORBIDDEN 403 FORBIDDEN	Cannot update invalid payment method	Attempt to update a payment method with INVALIDATED status	Only update payment methods that are in a valid (non-invalidated) status
Payment Method ID Validation	INVALID_REQUEST 400 BAD REQUEST	Invalid paymentMethodId	Payment method ID does not exist or has invalid format	Provide a valid, existing paymentMethodId
Field Validation	PAYMENT_METHOD_ERROR 400 BAD REQUEST	Account type must not be blank.	Missing required account type field	Include a valid account type in the request
	PAYMENT_METHOD_ERROR 400 BAD REQUEST	ZipCode must be exactly 5 digits long.	Invalid zip code format	Provide a valid 5-digit zip code
Expiry Date Validation	PAYMENT_METHOD_ERROR 400 BAD REQUEST	invalid expiryMonth	Expiry month is invalid (zero, negative, or greater than 12)	Provide a valid expiry month (1-12)
	PAYMENT_METHOD_ERROR 400 BAD REQUEST	expiry month and year cannot be in the past	Expired date provided	Provide a valid expiry date that is not in the past
	PAYMENT_METHOD_ERROR 400 BAD REQUEST	expiryYear cannot be more than 50 years from current year	Expiry year too far in future	Provide an expiry year that is within 50 years from the current year
	PAYMENT_METHOD_ERROR 400 BAD REQUEST	expiryMonth is required when expiryYear is present	Incomplete expiry date	Provide both expiry month and year
	PAYMENT_METHOD_ERROR 400 BAD REQUEST	expiryYear is required when expiryMonth is present	Incomplete expiry date	Provide both expiry month and year