Skip to main content
Version: v2

API Error Codes Reference

Auto-generated. Do not edit manually.

Agent Object Error Codes

Location
Error Code Summary
Error CategoryError Title ReferenceError TitleHTTP StatusError Message
CCG Schema ValidationFirst Name ValidationINVALID_REQUEST400 BAD REQUESTagent.firstName cannot be more than 50 characters
CCG Schema ValidationLast Name ValidationINVALID_REQUEST400 BAD REQUESTagent.lastName cannot be more than 50 characters
CCG Schema ValidationUser ID ValidationINVALID_REQUEST400 BAD REQUESTagent.userId is required
Location
Error Code Summary
Error CategoryError Title ReferenceError TitleHTTP StatusError Message
CCG Schema ValidationMerchant Consent Text ValidationINVALID_REQUEST400 BAD_REQUESTConsent is Invalid!
CCG Schema ValidationMerchant Consent Id ValidationINVALID_REQUEST400 BAD_REQUESTmerchantConsentId is required
CCG Schema ValidationConsent Collection Timestamp ValidationINVALID_REQUEST400 BAD_REQUESTcollectionTimestamp is required
CCG Schema ValidationConsent Collection Details ValidationINVALID_REQUEST400 BAD_REQUESTcollectionDetails are not valid
CCG Schema ValidationAgent Object Requirement with PPD ConsentINVALID_REQUEST400 BAD_REQUESTagent object is required with PPD consent

Customer Object Error Codes

Location
Error Code Summary
Error CategoryError Title ReferenceError TitleHTTP StatusError Message
CCG Schema ValidationMissing Required IdentifiersINVALID_REQUEST400 BAD REQUESTcustomer should contain hsid, enterpriseId or metadata
CCG Schema ValidationInvalid Enterprise IDINVALID_REQUEST400 BAD REQUESTcustomer.enterpriseId is invalid
CCG Schema ValidationInvalid HSIDINVALID_REQUEST400 BAD REQUESTcustomer.hsid must be a valid UUID
CCG Schema ValidationCustomer Not FoundNOT_FOUND404 NOT FOUNDCustomer not found for given enterpriseId
CCG Schema ValidationExceeded Metadata EntriesINVALID_REQUEST400 BAD REQUESTcustomer.metadata maximum allowed number of entries is 20
CCG Schema ValidationMetadata Key Size ExceededINVALID_REQUEST400 BAD REQUESTcustomer.metadata key maximum allowed length is 40
CCG Schema ValidationMetadata Value Size ExceededINVALID_REQUEST400 BAD REQUESTcustomer.metadata value maximum allowed length is 100
CCG Schema ValidationEmail ValidationINVALID_REQUEST400 BAD REQUESTcustomer.email must be a valid email address
CCG Schema ValidationFirst Name Length ExceededINVALID_REQUEST400 BAD REQUESTFirst name max length is 100
CCG Schema ValidationLast Name Length ExceededINVALID_REQUEST400 BAD REQUESTLast name max length is 100
CCG Schema ValidationSSN ValidationINVALID_REQUEST400 BAD REQUESTcustomer.ssnLastFour must be 4 digits

Payment Details Object Error Codes

Location
Error Code Summary
Error CategoryError Title ReferenceError TitleHTTP StatusError Message
CCG Schema ValidationPayment Details ValidationINVALID_REQUEST400 BAD REQUESTpayment details are not valid
CCG Schema ValidationQualified + Vision Amount Exceeds Total AmountINVALID_REQUEST400 BAD REQUESTdetails qualified amount + vision amount cannot be greater than amount
CCG Schema ValidationPrescription Amount Exceeds Qualified AmountINVALID_REQUEST400 BAD REQUESTdetails prescription amount cannot be greater than qualified amount

Payment Object Error Codes

Location
Error Code Summary
Error CategoryError Title ReferenceError TitleHTTP StatusError Message
CCG Schema ValidationPartial Authorization Not AllowedINVALID_REQUEST400 BAD REQUESTPartial authorization not allowed for authorizeCard = false
CCG Schema ValidationStatement Descriptor Suffix InvalidINVALID_REQUEST400 BAD REQUESTpayment.statementDescriptorSuffix only allows alphanumeric, space, hyphen and dot with at least one letter and allowed maximum length is 10
CCG Schema ValidationInvalid AmountINVALID_REQUEST400 BAD REQUESTInvalid amount ${validatedValue}, it must be between 1 and 99999999 and not contain decimals
CCG Schema ValidationExceeded Metadata EntriesINVALID_REQUEST400 BAD REQUESTmetadata maximum allowed number of entries is 20
CCG Schema ValidationMetadata Key Size ExceededINVALID_REQUEST400 BAD REQUESTmetadata key maximum allowed length is 40
CCG Schema ValidationMetadata Value Size ExceededINVALID_REQUEST400 BAD REQUESTmetadata value maximum allowed length is 100
CCG Schema ValidationDescription Size ExceededINVALID_REQUEST400 BAD REQUESTdescription maximum allowed length is 100
CCG Schema ValidationMerchant Transaction ID RequiredINVALID_REQUEST400 BAD REQUESTmerchantTransactionId is required
CCG Schema ValidationMerchant Transaction ID Too LongINVALID_REQUEST400 BAD REQUESTmerchantTransactionId maximum allowed length is 50
CCG Schema ValidationMissing Payment AllocationsINVALID_REQUEST400 BAD REQUESTpaymentAllocations is required.
CCG Schema ValidationToo Many Payment AllocationsINVALID_REQUEST400 BAD REQUESTMaximum number of allocations allowed is 2
CCG Schema ValidationInvalid Allocation AmountINVALID_REQUEST400 BAD REQUESTpaymentAllocations[0].amount 0.1 is invalid, it must be between 1 and 99999999 and not contain decimals.
CCG Schema ValidationMissing Payment AmountINVALID_REQUEST400 BAD REQUESTamount is required
CCG Schema ValidationMissing Allocation AmountINVALID_REQUEST400 BAD REQUESTpaymentAllocations[0].amount is required
CCG Schema ValidationAllocation Sum MismatchINVALID_REQUEST400 BAD REQUESTsum of paymentAllocations[:].amount should be equal to payment.amount
CCG Schema ValidationDuplicate Payment Method IdINVALID_REQUEST400 BAD REQUESTpaymentAllocations[:].paymentMethodId cannot be same
CCG Schema ValidationMissing Payment Method IdINVALID_REQUEST400 BAD REQUESTpaymentAllocations[:].paymentMethodId is required
CCG Schema ValidationInvalid Payment Method IdINVALID_REQUEST400 BAD REQUESTpaymentAllocations[n].paymentMethodId is invalid

Cancel Payments API Error Codes

Location
Error Code Summary
Error Title ReferenceError TitleHTTP StatusDetail Message
Payment Cancellation Reason MissingINVALID_REQUEST400 BAD REQUESTpaymentCancellationReason is missing or null
Invalid Payment Cancellation ReasonINVALID_REQUEST400 BAD REQUESTInvalid paymentCancellationReason

Payment Error Codes

Location
Error Code Summary
Error CategoryError Title ReferenceError TitleHTTP StatusError Message
CCG Schema ValidationConsent RequirementINVALID_REQUEST400 BAD REQUESTConsent is required!
CCG Business ValidationPayment Method Not FoundPAYMENT_METHOD_ERROR406 NOT_ACCEPTABLEPayment method ending with {last4} is not found. Please provide a valid payment method.
CCG Business ValidationPayment Method Type Not ConfiguredPAYMENT_METHOD_ERROR406 NOT_ACCEPTABLEPayment method ending with {last4} is not configured. Please provide a valid payment method.
CCG Business ValidationInvalid Payment MethodsPAYMENT_METHOD_ERROR406 NOT_ACCEPTABLEPayment method ending with {last4} is or invalid. Please provide a valid payment method.
Payment Processor ValidationVendor Processing ErrorPAYMENT_METHOD_ERROR406 NOT_ACCEPTABLEOne of the split tender card payments failed during processing.
CCG Business ValidationCard Requires 3D Secure AuthenticationPAYMENT_METHOD_ERROR406 NOT ACCEPTABLEThis 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.
CCG Business ValidationPayment Method Requires AuthenticationPAYMENT_METHOD_ERROR406 NOT ACCEPTABLEPayment method could not be authorized. This payment method requires authentication from a customer.

Stripe Payment Processing Error Codes

Location
Error Code Summary
Error CategoryError Title ReferenceError TitleHTTP StatusError Message
Payment Processor ValidationCard Authentication ErrorsPAYMENT_METHOD_ERROR406 NOT ACCEPTABLEThis 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.
Payment Processor ValidationCard Authentication ErrorsPAYMENT_METHOD_ERROR406 NOT ACCEPTABLEPayment method could not be authorized. This payment method requires authentication from a customer.
Payment Processor ValidationCard Decline ErrorsPAYMENT_METHOD_ERROR406 NOT ACCEPTABLEThe card was declined for an unknown reason. Contact issuer for more information.
Payment Processor ValidationCard Decline ErrorsPAYMENT_METHOD_ERROR406 NOT ACCEPTABLEAn error occurred while processing the card, please try again.
Payment Processor ValidationCard Decline ErrorsPAYMENT_METHOD_ERROR406 NOT ACCEPTABLEPayment method could not be authorized. Please try a different payment method.
Payment Processor ValidationCard Decline ErrorsPAYMENT_METHOD_ERROR406 NOT ACCEPTABLEPayment method is canceled by a customer or expired by the financial partner
Payment Processor ValidationCard Validation ErrorsPAYMENT_METHOD_ERROR406 NOT ACCEPTABLEThe CVC number is incorrect.
Payment Processor ValidationCard Validation ErrorsPAYMENT_METHOD_ERROR406 NOT ACCEPTABLEThe card has expired.
Payment Processor ValidationFinancial Limit ErrorsPAYMENT_METHOD_ERROR406 NOT ACCEPTABLEThe customer's account has insufficient funds to complete the purchase. Please use an alternative payment method.
Payment Processor ValidationFinancial Limit ErrorsPAYMENT_METHOD_ERROR406 NOT ACCEPTABLEThe customer has exceeded the balance, credit limit, or transaction amount limit available on their card. Contact issuer for more information.
Payment Processor ValidationBank Account ErrorsPAYMENT_METHOD_ERROR406 NOT ACCEPTABLEThe customer's bank account has been closed.
Payment Processor ValidationBank Account ErrorsPAYMENT_METHOD_ERROR406 NOT ACCEPTABLEThe customer's bank account could not be located.
Payment Processor ValidationEarly Warning System ErrorsPAYMENT_METHOD_ERROR406 NOT ACCEPTABLEearlyWarningMessage

Refund API Error Codes

Location
Error Code Summary
Error Title ReferenceError TitleHTTP StatusDetail MessageScenarioResolution
Structural Validation ErrorsBAD_REQUEST400 BAD REQUESTMerchantTransactionId must be unique across all refund requests.Duplicate merchantTransactionId provided.Use a new merchantTransactionId for each refund request.
Structural Validation ErrorsBAD_REQUEST400 BAD_REQUESTRefund already exists for the given merchantTransactionId.A refund with the same merchantTransactionId already exists.Do not retry with the same transaction ID; generate a new one.
Structural Validation ErrorsBAD_REQUEST400 BAD REQUESTmerchantTransactionId is required.merchantTransactionId missing in the request.Provide a valid merchantTransactionId field.
Structural Validation ErrorsBAD_REQUEST400 BAD REQUESTreason is required.reason field missing from the request.Include reason and ensure it has a valid value.
Structural Validation ErrorsBAD_REQUEST400 BAD REQUESTInvalid refund reason. reason can have only allowed values.Provided reason is not part of the allowed enum.Use only documented enum values for reason.
Structural Validation ErrorsBAD_REQUEST400 BAD REQUESTpaymentId is required.paymentId missing from the request.Provide a valid paymentId from a previous payment.
Structural Validation ErrorsBAD_REQUEST400 BAD REQUESTpayment not found.paymentId not found or not associated with the merchant.Use a valid paymentId from a Create Payment response.
Structural Validation ErrorsBAD_REQUEST400 BAD REQUESTpaymentAllocationId not linked to paymentIdrefundAllocations contains IDs not belonging to the referenced payment.Use paymentAllocationIds belonging to the correct payment.
Structural Validation ErrorsBAD_REQUEST400 BAD REQUESTamount is required for each refundAllocations.Missing amount in a refundAllocations entry.Add an amount value to every refundAllocations entry.
Structural Validation ErrorsBAD_REQUEST400 BAD REQUESTpaymentAllocationId is required for each refundAllocations.Missing paymentAllocationId in refundAllocations.Provide a valid paymentAllocationId for each entry.
Structural Validation ErrorsBAD_REQUEST400 BAD_REQUESTZero-amount refunds not allowed.amount = 0 submitted.Submit only positive refund amounts.
Error Title ReferenceError TitleHTTP StatusDetail MessageScenarioResolution
Structural Validation ErrorsNOT_FOUND404 NOT_FOUNDRefund information not found.refundId not found in CCG, or refundId not associated with the requesting merchant.Use a valid refundId returned from Create Refund, and ensure the refund belongs to the requesting merchant.
Structural Validation ErrorsBAD_REQUEST400 BAD_REQUESTRefundId is invalid.refundId is not in valid UUID format.Provide a valid UUID-formatted refundId.

Refund Error Codes

Location
Error Code Summary
Error Title ReferenceError TitleHTTP StatusDetail MessageScenarioResolution
Refund Amount ValidationINVALID_REQUEST400 BAD REQUESTRefund amount cannot be more than the un-refunded amount of the original paymentWhen attempting to refund more than the available amountEnsure refund amount is less than or equal to the available (un-refunded) amount
INVALID_REQUEST400 BAD REQUESTWhen paymentMethodId is present, amount is requiredWhen using paymentMethodId without specifying an amountInclude a valid amount when using paymentMethodId
Payment Status ValidationPAYMENT_ERROR400 BAD REQUESTCannot issue refund for this paymentWhen attempting to refund a payment not in COMPLETED statusOnly attempt to refund payments that are in COMPLETED status
Payment Status ValidationINVALID_REQUEST400 BAD REQUESTCannot issue refund for this paymentWhen attempting to refund for disputed fraudulent transactionDisputed fraudulent transactions cannot be refunded
INVALID_REQUEST400 BAD REQUESTRefunds can only be processed for captured paymentsWhen attempting to refund a payment in AUTHORIZED statusCapture the payment before attempting to refund it or cancel the payment if not required.
INVALID_REQUEST400 BAD REQUESTThe amount given exceeds the allowed refund limitWhen attempting to issue Credit beyond allowed refund limitReduce the refund amount to be within the allowed limit
Payment Identifier ValidationINVALID_REQUEST400 BAD REQUESTpaymentId or paymentMethodId is requiredWhen neither paymentId nor paymentMethodId is providedInclude either paymentId or paymentMethodId in the request
INVALID_REQUEST400 BAD REQUESTEither paymentId or paymentMethodId should be provided. The request has both paymentId and paymentMethodIdWhen both paymentId and paymentMethodId are providedUse either paymentId or paymentMethodId, not both
INVALID_REQUEST400 BAD REQUESTWhen paymentMethodId is present, customer should contain hsid, enterpriseId or metadataWhen customer identifiers are missing with paymentMethodIdInclude customer identifiers when using paymentMethodId
Payment Method Status ValidationINVALID_REQUEST400 BAD REQUESTPayment method is canceled by a customer or expired by the financial partnerWhen attempting to refund using an invalid payment methodUse only valid, active payment methods for refunds
INVALID_REQUEST400 BAD REQUESTCredit is not allowed for bank accounts.When attempting to refund to a bank account payment methodUse card payment methods for unlinked refunds/credits
INVALID_REQUEST400 BAD REQUESTInvalid paymentMethodIdWhen attempting to issue Credit for Invalid or Deleted Payment MethodUse only valid, active payment methods for refunds
Payment Dispute ValidationINVALID_REQUEST400 BAD REQUESTPayment is in dispute and not available for refundWhen attempting to refund a payment that is in disputeRefunds 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 ExistsINVALID_REQUEST400 BAD REQUESTThis payment is already refundedWhen attempting to create a refund on already completed paymentIf 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_REQUEST400 BAD REQUESTRefund already exists for the given merchantTransactionIdWhen attempting to create a refund with a duplicate merchantTransactionIdProvide a unique merchantTransactionId for every refund transaction

Checkout Session Authorization Error Codes

Location
Error Code Summary
Error Title ReferenceError TitleHTTP StatusDetail MessageScenarioResolution
Checkout Session AuthorizationFORBIDDEN403 FORBIDDENAccess denied when attempting to save payment method using completed sessionAttempting to save payment method with a completed checkout sessionCreate a new session for saving payment methods; completed sessions cannot be reused
FORBIDDEN403 FORBIDDENAccess denied when attempting to save payment method using PAYMENT modeAttempting to save payment method when session is in payment modeUse PAYMENT_METHOD_ENTRY or WALLET or PAYMENT_WITH_WALLET mode for saving payment methods
FORBIDDEN403 FORBIDDENAccess denied when attempting to poll setup payment method using PAYMENT modeAttempting to poll for setup status when session is in payment modeUse PAYMENT_METHOD_ENTRY or WALLET or PAYMENT_WITH_WALLET mode for saving payment methods
FORBIDDEN403 FORBIDDENAccess denied when attempting to save payment method using cancelled sessionAttempting to save payment method with a cancelled checkout sessionCreate a new session; cancelled sessions cannot be reused
FORBIDDEN403 FORBIDDENNot allowed to access this sessionWhen merchant2 tries to access a session initiated by merchant1Use the same merchant credentials that were used to create the session

Config Object Error Codes

Location
Error Code Summary
Error Title ReferenceError & StatusDetail MessageScenarioResolution
Config Parameter Validation
saveDisabled/paymentMethodSaveMode not supported in [modes]INVALID_REQUEST 400 BAD REQUESTInvalid 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 modesRemove saveDisabled or paymentMethodSaveMode parameters when using non-supported modes
Payment Method ID required for PAYMENT_METHOD_DISPLAYINVALID_REQUEST 400 BAD REQUESTPayment Method ID is required for mode - PAYMENT_METHOD_DISPLAYWhen sending a request with PAYMENT_METHOD_DISPLAY mode but omitting the payment method IDInclude a valid payment method ID when using PAYMENT_METHOD_DISPLAY mode
saveDisabled and paymentMethodSaveMode cannot be used togetherINVALID_REQUEST 400 BAD REQUESTInvalid request: 'saveDisabled' and 'paymentMethodSaveMode' cannot be used together. Use only 'paymentMethodSaveMode'.When sending a request with both saveDisabled and paymentMethodSaveMode specifiedUse only paymentMethodSaveMode parameter, not both parameters together
Merchant name contains invalid charactersINVALID_REQUEST 400 BAD REQUESTconfig.merchant.name Merchant name contains invalid charactersWhen 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 blankINVALID_REQUEST 400 BAD REQUESTconfig.merchant.name Merchant name must not be blankWhen the merchant name in the config object is blank or not providedProvide a non-empty merchant name in the config object
Merchant name character limitINVALID_REQUEST 400 BAD REQUESTconfig.merchant.name Merchant name must be less than or equal to 80 charactersWhen the merchant name in the config object exceeds 80 charactersEnsure merchant name is 80 characters or less
Invalid modeINVALID_REQUEST 400 BAD REQUESTInvalid modeWhen providing an invalid session modeUse one of the supported session modes (PAYMENT, PAYMENT_WITH_WALLET, WALLET, etc.)
Invalid PaymentMethodChannelINVALID_REQUEST 400 BAD REQUESTInvalid PaymentMethodChannelWhen providing an invalid payment method channelUse one of the supported payment method channels
Payment method type is not configuredINVALID_REQUEST 400 BAD REQUESTPayment method type is not configured.Payment method type is missing or not configured for the merchant during session creationEnsure the payment method type is configured for your merchant account
You have no capture methods availableINVALID_REQUEST 400 BAD REQUESTYou 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 URLINVALID_REQUEST 400 BAD REQUESTconfig.privacyPolicyUrl must be a valid URLWhen privacyPolicyUrl in config is not a valid URLProvide a valid, properly formatted URL for the privacy policy
Session Mode not applicable for guest checkoutINVALID_REQUEST 400 BAD REQUESTSession 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 typeINVALID_REQUEST 400 BAD REQUESTInvalid card category type config.cardCategories.typeWhen a card categories type is not given as Merchant configured type ( ex: MANUFACTURER_CARD )Use only merchant-configured card category types
More than 100 medicationsINVALID_REQUEST 400 BAD REQUESTMaximum of 100 medications allowed in cardCategories[].medicationWhen a card categories medication having a more than 100 medicationsLimit medications to 100 per card category
Card Categories given but Medication not providedINVALID_REQUEST 400 BAD REQUESTMedications cannot be empty in cardCategories[].medicationsWhen a Card Categories given as Manufacturer card, medication should have to be providedProvide at least one medication in cardCategories[].medications
More than 100 char in cardCategories.labelINVALID_REQUEST 400 BAD REQUESTCategory label cannot exceed 100 charactersWhen a Card Categories label consisting more then 100 charactersLimit card category label to 100 characters or less
More than 100 char or empty string in medication.valueINVALID_REQUEST 400 BAD REQUESTMedication value cannot be empty and maximum allowed length is 100When a Card Categories medication label consisting more then 100 charactersProvide a non-empty medication value of 100 characters or less
More than 100 char or empty string in medication.labelINVALID_REQUEST 400 BAD REQUESTMedication label cannot be empty and maximum allowed length is 100When a Card Categories medication value consisting more then 100 charactersProvide a non-empty medication label of 100 characters or less

Sessions API Error Codes

Location
Error Code Summary
Error Title ReferenceError TitleHTTP StatusDetail MessageScenarioResolution
Session Controller Validation
Card WS2 check has failedINVALID_REQUEST400 BAD REQUESTCard WS2 check has failed.WS2 verification of agent information (e.g., MSID) failed during session creationEnsure agent userid is part of PCI_WorkStation group
Session Id not foundNOT_FOUND404 NOT FOUNDSession Id not foundWhen requesting a session that doesn't existCheck that the session ID is correct and the session has been created
Your session has been canceledSESSION_CANCELED410 GONEYour session has been canceledWhen requesting a canceled sessionCreate a new session; canceled sessions cannot be reused
Your session is no longer validSESSION_TIMEOUT401 UNAUTHORIZEDYour session is no longer validWhen requesting an expired sessionCreate a new session; expired sessions cannot be reused
Not allowed to access this sessionFORBIDDEN403 FORBIDDENNot allowed to access this sessionWhen merchant ID in request doesn't match the session's merchant IDUse the same merchant credentials that were used to create the session
Customer Identifier is MissingINVALID_REQUEST400 BAD REQUESTCustomer identifier is missingWhen customer identifier is not provided for session modes: PAYMENT_METHOD_ENTRY, WALLET, PAYMENT_METHOD_SELECT, PAYMENT_METHOD_DISPLAYInclude a valid customer identifier (hsid, enterpriseId, or metadata)
Consent is requiredINVALID_REQUEST400 BAD REQUESTConsent is required!When consent is missing in PAYMENT modeInclude a valid consent object with the required fields
payment is requiredINVALID_REQUEST400 BAD REQUESTpayment is requiredWhen payment object is missing for session modes: PAYMENT, PAYMENT_WITH_WALLETInclude a valid payment object with the required fields