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