Error Codes

Failed API Calls

For any unsuccessful API responses (having a non-2xx HTTP status), a JSON error response will be returned with the following fields:

status - Number that simply duplicates the HTTP status code.
failures - Object array where each failure contains the following fields:
- code - Enumerated string value that categorizes the failure.
- description - String value with more details about the specific problem.
- field - String value that identifies a field in the JSON request, where applicable.

In some cases, the "code" identifies a general category of failures that may have many descriptions. Below is an example:

Request:

POST "https://uat.api.converge.eu.elavonaws.com/orders"
{
     "total": {
                   "amount": "1.23"
              }
}

Response:

{
     "status": 400,
     "failures": [
                      {
                           "code": "badRequest",
                           "description": "The request is invalid; correct all issues before resending",
                           "field": null
                      },
                      {
                           "code": "fieldValidationFailure",
                           "description": "must not be null",
                           "field": "total.currencyCode"
                      }
                 ]
}

Generally, the first failure will provide more information related to the HTTP status code. The table below shows a list of the HTTP status codes and their descriptions:

HTTP Status	Failure Code	Failure Description
400	badRequest	The request is invalid; correct all issues before resending.
401	unauthorized	A valid API key is required.
403	forbidden	Public API keys may only be used to create hosted cards
404	notFound	The requested resource does not exist.
405	methodNotAllowed	The given method may not be used here. Note that the X-HTTP-Method-Override header can only be used to override POST with either PATCH or DELETE.
406	notAcceptable	The Accept request header must specify 'application/json;charset=UTF-8'; the Accept-Version request header if present, must reference a valid API version.
409	conflict	This request does not match the original, or the original request is still processing.
411	lengthRequired	Content-Length must be specified for this request.
413	payloadTooLarge	The request payload is too large.
415	unsupportedMediaType	The Content-Type request header must specify 'application/json'.
429	tooManyRequests	Too many requests have been received too quickly for this API key.

Additional failures will describe as many additional specific issues as can be currently identified. Because descriptions are sometimes generated dynamically, it's impossible to enumerate all possibilities.

The JSON request is parsed and bound to a resource as defined by the API specification. Failures at this stage of processing will have the code "jsonBindingFailure". Descriptions specify as much as possible to help identify the issue encountered.

Below are examples of these types of failures. Some details of each description (e.g. field names, line and column numbers) will vary.

Failure Code	Failure Description
jsonBindingFailure	Unexpected character ('c' (code 99)): was expecting double-quote to start field name; near line: 2, column 4.
jsonBindingFailure	Unexpected character ('}' (code 125)): expected a value; near line: 3, column 2.
jsonBindingFailure	Illegal unquoted character ((CTRL-CHAR, code 13)): has to be escaped using backslash to be included in string value; near line: 2, column 15.
jsonBindingFailure	Unrecognized token 'value': expected ('true', 'false', or 'null') near line: 3, column 26.
jsonBindingFailure	Cannot deserialize 'fieldName' from String.
jsonBindingFailure	Cannot deserialize 'fieldName' from START_ARRAY token ('[').
jsonBindingFailure	Cannot deserialize 'fieldName' from START_OBJECT token ('{').
jsonBindingFailure	Duplicate field 'fieldName'; near line: 1, column 1.
jsonBindingFailure	Required request body is missing.
jsonBindingFailure	Resource reference could not be parsed as either an href or an id.
jsonBindingFailure	Unrecognized field name: 'fieldName'.
jsonBindingFailure	Value of field 'fieldName' is read-only and cannot be set.

If the request is successfully parsed and bound, request validation is then applied. Most failures at this stage will have the code "fieldValidationFailure".

Below is a list of these types of failures. Note that there are cases when the failure code is more specific.

Failure Code	Failure Description
fieldValidationFailure	3DS is only allowed on e-commerce transactions.
fieldValidationFailure	3DSv1 is no longer supported.
fieldValidationFailure	A transaction already exists for this payment session.
fieldValidationFailure	Amount must have at most 9 integer digits and at most 4 fractional digits.
fieldValidationFailure	Cannot set cancelledBy because payment link is already cancelled.
fieldValidationFailure	Can only be set if doCancel is true.
fieldValidationFailure	Card has expired or is expiring soon.
fieldValidationFailure	Card issuer currency is not supported for Elavon currency conversion.
fieldValidationFailure	Card number does not match surcharge advice.
fieldValidationFailure	Card number or shopper interaction does not match forex advice.
fieldValidationFailure	Card type is not supported by merchant.
fieldValidationFailure	Card type is not supported for debt repayment.
fieldValidationFailure	Currency conversion is not supported for this card type.
fieldValidationFailure	Currency conversion is unavailable for this card.
fieldValidationFailure	Currency is not supported by Elavon platform.
fieldValidationFailure	Currency is the same as card issuer currency.
fieldValidationFailure	Currency must be in the merchant settlement currency for American Express.
fieldValidationFailure	Currency must be in the merchant settlement currency since merchant does not support multi-currency transactions.
fieldValidationFailure	Debtor account was missing required information.
fieldValidationFailure	Debt repayment is not supported for this merchant.
fieldValidationFailure	doCapture must be set to true for debt repayment merchants.
fieldValidationFailure	Exactly one of card or hostedCard must not be null.
fieldValidationFailure	Exactly one of directoryServerTransactionId or transactionId must not be null.
fieldValidationFailure	Exactly one of total, forexAdvice, or surchargeAdvice must not be null for type 'sale'.
fieldValidationFailure	First billing date is not valid.
fieldValidationFailure	Google Pay is not supported for DCC transactions.
fieldValidationFailure	Google Pay is not supported for merchant initiated transactions.
fieldValidationFailure	Google Pay only supports ecommerce transactions.
fieldValidationFailure	Invalid token.
fieldValidationFailure	Invalid token type.
fieldValidationFailure	initialTotal currencyCode must match total currencyCode.
fieldValidationFailure	initialTotal must not be null if initialTotalBillCount is greater than 0.
fieldValidationFailure	initialTotalBillCount must be greater than 0 if initialTotal is not null.
fieldValidationFailure	initialTotalBillCount must be less than billCount.
fieldValidationFailure	Issuing country of the card must match the DBA country for debt repayment.
fieldValidationFailure	Maximum of 50 tokens per request.
fieldValidationFailure	Merchant does not have surcharging enabled.
fieldValidationFailure	Merchant does not support currency conversion.
fieldValidationFailure	Merchant does not support Google Pay.
fieldValidationFailure	Must be '0', '1', '2', '5', '6', or '7', optionally with a leading zero.
fieldValidationFailure	Must be '5', '6', or '7', optionally with a leading zero.
fieldValidationFailure	Must be 'Y', 'U', or 'A'.
fieldValidationFailure	Must be 13 to 19 digits.
fieldValidationFailure	Must be 3 or 4 digits.
fieldValidationFailure	Must be a 4 digit year between 2000 and 2099, inclusive.
fieldValidationFailure	Must be a hexadecimal string.
fieldValidationFailure	Must be a future date.
fieldValidationFailure	Must be a valid credit card number.
fieldValidationFailure	Must be a valid URL.
fieldValidationFailure	Must be greater than 0.
fieldValidationFailure	Must be greater than or equal to 1.
fieldValidationFailure	Must be greater than previous expiresAt.
fieldValidationFailure	Must be HTTP(S) with a host.
fieldValidationFailure	Must be null for hpp type 'hppType'.
fieldValidationFailure	Must be null for a transaction authorized outside North America.
fieldValidationFailure	Must be null for type 'transactionType'.
fieldValidationFailure	Must be null when creating any transaction.
fieldValidationFailure	Must be null when source is not 'payByLink'.
fieldValidationFailure	Must be false for type 'transactionType'.
fieldValidationFailure	Must be true for type 'transactionType'.
fieldValidationFailure	Must be six digits.
fieldValidationFailure	Must be specified in debt repayment information.
fieldValidationFailure	Must be within 1 year.
fieldValidationFailure	Must be valid version in the form of x.x.x containing only digits.
fieldValidationFailure	Must match the total.currencyCode.
fieldValidationFailure	Must not authenticate 3-D Secure data in both hosted card and transaction.
fieldValidationFailure	Must not be blank.
fieldValidationFailure	Must not be 'value' for type 'transactionType'.
fieldValidationFailure	Must not be 'unknown'.
fieldValidationFailure	Must not be greater than the total.amount.
fieldValidationFailure	Must not be null.
fieldValidationFailure	Must not be null for hpp type 'hppType'.
fieldValidationFailure	Must not be null if card.expirationYear or card.expirationMonth or card.billTo or card.holderName is updated.
fieldValidationFailure	Must be null when transactionId is not null.
fieldValidationFailure	Must not be null when transactionStatus is 'Y' or 'A'.
fieldValidationFailure	Must only consist of word characters.
fieldValidationFailure	Must only use cryptogramSecurity in combination with card or threeDSecure alone.
fieldValidationFailure	Must only use one of either applePayment or googlePayPayment.
fieldValidationFailure	Not a well-formed email address.
fieldValidationFailure	Not an active subscription.
fieldValidationFailure	Order total and order item currency codes do not match.
fieldValidationFailure	Parent transaction was not found.
fieldValidationFailure	postalCode must be specified in debt repayment information.
fieldValidationFailure	Previous recurring transaction must be a recurring type of 'first' or 'subsequent'.
fieldValidationFailure	Previous recurring transaction was not found.
fieldValidationFailure	Stored card already exists for this card number.
fieldValidationFailure	Surcharging is not supported for this card.
fieldValidationFailure	The account referenced does not exist.
fieldValidationFailure	The debtorAccount value cannot be updated once set.
fieldValidationFailure	The forex advice referenced cannot be updated once set.
fieldValidationFailure	The forex advice referenced either does not exist or has expired.
fieldValidationFailure	The Google Pay payment referenced either does not exist or has expired.
fieldValidationFailure	The hosted card referenced cannot be updated once set.
fieldValidationFailure	The hosted card referenced either does not exist or has expired.
fieldValidationFailure	The order referenced does not exist.
fieldValidationFailure	The PAN token referenced does not exist.
fieldValidationFailure	The payment link referenced cannot be updated once set.
fieldValidationFailure	The payment link referenced either does not exist or has expired.
fieldValidationFailure	The payment session referenced either does not exist or has expired.
fieldValidationFailure	The plan is not subscribable.
fieldValidationFailure	The plan referenced was not found.
fieldValidationFailure	The shopper referenced cannot be updated once set.
fieldValidationFailure	The shopper referenced does not exist.
fieldValidationFailure	The stored card referenced cannot be updated once set.
fieldValidationFailure	The stored card referenced does not belong to the shopper.
fieldValidationFailure	The stored card referenced does not exist.
fieldValidationFailure	The surcharge advice referenced either does not exist or has expired.
fieldValidationFailure	The threeDSecure value cannot be updated once set.
fieldValidationFailure	The transaction referenced cannot be updated once set.
fieldValidationFailure	The transaction referenced either does not exist or has expired.
fieldValidationFailure	The webhook referenced does not exist.
fieldValidationFailure	Transaction amount does not match the 3DS authorized amount.
fieldValidationFailure	Transaction and order currency codes do not match.
fieldValidationFailure	Transaction must use same card as previous recurring transaction for 'subsequent' recurring type.
fieldValidationFailure	Transaction must use same stored card as previous recurring transaction for 'subsequent' recurring type.
cardTypeNotSupported	Declined because the card type is not supported by merchant.
cardTypeNotSupported	JCB card type is not supported for Apple Pay or Google Pay payments.
currencyConversionUnavailable	Currency conversion is unavailable for this card.
demoMerchantNotSupported	3-D Secure functionality in hostedCard is deprecated and not supported for 'demo' merchants. See the developer documentation for more details.
domainNotRegistered	Domain provided has not been registered for the merchant.
illegalArgument	Either doCapture must be false or heldForReview must be true.
illegalArgument	Transaction is not in AUTHORIZED state.
invalid	Invalid token.
invalid	Plan cannot be deleted while active subscriptions exist.
invalid	Stored card cannot be deleted while active or past due subscriptions exist.
invalidRefundParentCaptureFlag	Parent transaction is not eligible for settlement.
invalidRefundParentTxnType	Parent transaction type is invalid.
maestro3dsRequired	3DS must be performed on Maestro ecommerce transactions.
merchantNotRegistered	Merchant has not been registered for Apple Pay payment sessions.
northAmericanMerchantNotSupported	3-D Secure functionality in hostedCard is not supported for merchants in North America. See the developer documentation for more details.
notFound	Merchant surcharging settings not found.
parentNotAuthorized	Parent transaction was declined or expired.
paymentLinkCancelled	The payment link referenced was cancelled.
paymentLinkExpired	The payment link referenced was expired.
paymentLinkLimitReached	The conversion limit for this payment link has been reached.
refundAlreadyProcessed	Parent transaction is already refunded.
refundAmountOverflow	Total refund amount exceeds parent transaction amount.
refundCurrencyMismatch	Parent transaction does not have the same currency.
surchargeNotSupported	Surcharge advices are not supported in the EU region.
voidAlreadyProcessed	Parent transaction is already refunded.
voidParentAlreadySettled	Parent transaction is settling or has already settled.
voidParentAmountMismatch	Parent transaction does not have the same amount or currency.
voidParentNotProcessed	Parent transaction is not processed.

If query parameters are provided to perform filtering, validation will also be applied to those.

Below are examples of these types of failures. The specific values for the field name and operator will vary.

Failure Code	Failure Description
filterParseFailure	Invalid value for fieldName 'fieldName'.
filterParseFailure	Unrecognized operator: 'op'.
filterParseFailure	Unrecognized operator 'op' for fieldName 'fieldName'.

For more information on filtering, see the Collection Filtering section of the API Reference.

Declined Transactions

When creating a transaction, if the request is valid, an authorization is performed for the transaction. If the transaction authorization is declined, a transaction is still created and a successful status code is returned. To determine why the transaction was declined, check the "failures" object array in the created transaction.

The first failure identifies where in the authorization chain the transaction was declined. Below is a list of these types of failures.

Failure Code	Failure Description
declinedByGateway	Transaction was declined by the payment gateway.
declinedByProcessor	Declined by the payment processor.
declinedByIssuer	Declined by the card issuer.

There may be additional failures that provide more information about why the transaction was declined. Below is a list of these types of failures.

Failure Code	Failure Description
3dsEnforcedOnEcommerceSales	Declined because 3DS shopper authentication was not performed or failed.
avsPostalCodeMismatch	Declined because AVS result is postal code mismatch.
avsStreetMismatch	Declined because AVS result is street mismatch.
cardExpired	Declined because the card has expired.
cardTypeNotSupported	Declined because the card type is not supported by merchant.
cvvMismatch	Declined because the CVV does not match.
highRiskBillingCountry	Declined because the billing country is rated as high-risk.
highRiskIpAddress	Declined because it was generated from an IP address rated as high-risk.
highRiskIssuingCountry	Declined because the card issuing country is rated as high-risk.
highRiskPan	Declined because the card PAN was recognized as a high-risk PAN.
maxAmountExceeded	Declined because it exceeds the maximum amount allowed.
merchantNotActive	Declined because the merchant is currently inactive.
missingBinData	Declined because BIN file service did not return any data
panFrequencyCheck	Declined because card PAN was seen too often in defined time frame.
processorError	The processor is unavailable or an error occurred.

Below is an example of a valid transaction that was declined. The "failures" object array in the response indicates why the transaction was declined.

Request:

POST "https://uat.api.converge.eu.elavonaws.com/transactions"
{
    "total":  {
                  "amount":  "10.00",
                  "currencyCode":  "EUR"
              },
    "card":  {
                 "number":  "5021652222222228",
                 "expirationMonth":  1,
                 "expirationYear":  2025
             },
    "shopperInteraction": "telephoneOrder"
}

Response:

{
    "href":  "https://uat.api.converge.eu.elavonaws.com/transactions/8pp7cb7cc68wfm4tkx6t9x7xj62r",
    "id":  "8pp7cb7cc68wfm4tkx6t9x7xj62r",
    "createdAt":  "2023-03-10T12:27:56.349Z",
    "modifiedAt":  "2023-03-10T12:27:56.349Z",
    "type":  "sale",
    "source":  "directApiCall",
    "merchant":  "https://uat.api.converge.eu.elavonaws.com/merchants/XrDXRBh9YHxwqQTj2Cmq7j49",
    "processorAccount":  "https://uat.api.converge.eu.elavonaws.com/processor-accounts/KmvmfQJpCBJpXHyP2kgrK2hD",
    "account":  "https://uat.api.converge.eu.elavonaws.com/accounts/XrDXRBh9YHxwqQTj2Cmq7j49",
    "total":  {
                  "amount":  "10.00",
                  "currencyCode":  "EUR"
              },
    "totalRefunded":  null,
    "issuerTotal":  null,
    "salesTax":  null,
    "conversionRate":  null,
    "markupRate":  null,
    "markupRateAnnotation":  null,
    "parentTransaction":  null,
    "description":  null,
    "shopperStatement":  null,
    "debtorAccount":  null,
    "customReference":  null,
    "shopperReference":  null,
    "processorReference":  "ASSJARULFLV",
    "issuerReference":  null,
    "orderReference":  null,
    "shopperInteraction":  "telephoneOrder",
    "shopper":  null,
    "shipTo":  null,
    "shopperEmailAddress":  null,
    "shopperIpAddress":  null,
    "shopperLanguageTag":  null,
    "shopperTimeZone":  null,
    "order":  null,
    "subscription":  null,
    "credentialOnFileType":  "none",
    "credentialOnFileData":  null,
    "card":  {
                 "holderName":  null,
                 "panToken":  {
                                  "token":  "9505057890664098709",
                                  "provider":  "ELAVON_C2_V1",
                                  "type":  "pan"
                              },
                 "panFingerprint":  "4284dwprgk3kdgyhtxccwjjj",
                 "expirationMonth":  1,
                 "expirationYear":  2025,
                 "billTo":  null,
                 "maskedNumber":  "XXXXXXXXXXXX2228",
                 "last4":  "2228",
                 "bin":  "502165",
                 "scheme":  "MasterCard",
                 "brand":  "Maestro",
                 "fundingSource":  "debit",
                 "issuingBank":  "BANK OF BARODA",
                 "issuingCountry":  "IND",
                 "issuingCurrency":  "INR",
                 "isDebit":  "true",
                 "isCorporate":  "false",
                 "isDccAllowed":  "true"
             },
    "paymentLink":  null,
    "paymentSession":  null,
    "createdBy":  null,
    "modifiedBy":  null,
    "customFields":  null,
    "isHeldForReview":  false,
    "doCapture":  true,
    "doSendReceipt":  true,
    "isAuthorized":  false,
    "authorizationCode":  null,
    "verificationResults":  {
                                "name":  "unprovided",
                                "securityCode":  "unprovided",
                                "addressStreet":  "unprovided",
                                "addressPostalCode":  "unprovided",
                                "threeDSecureV1":  "unprovided",
                                "threeDSecureV2":  "unprovided"
                            },
    "state":  "declined",
    "batch":  null,
    "relatedTransactions":  [

                            ],
    "failures":  [
                     {
                         "code":  "declinedByIssuer",
                         "description":  "Declined by the card issuer",
                         "field":  null
                     }
                 ],
    "history":  [

                ]
}