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":  [

                ]
}