Error Codes Reference

When processing a transaction through the CityPay APIs an error code value is returned indicating the result of processing the transaction. Each error code combines a code, an error message and error id parameter.

A CityPay error code is presented in the format of an alpha character followed by a 3 digit numeric. The alpha character represents the error grouping i.e. C001 is a card validation error and the 3 digit numerics the code number of 001. The system group does not contain a character and is therefore the only code that appears as a 3 digit numeric.

An error message is a textual String describing the error. The error message field may include additional information pertaining to the thrown error which will aid in resolving the error.

An error id is also known as a complete error identifier. This code is in the format of error code.system code.location code where the system code and location code are internal codes to CityPay that aid in deciphering the origination of an error message. This identifier should be included with the error message in any support requests.

System

The System group defines a group that determines the outcome of processing transactions. This code is the result of an authorised transaction and defines further details on why a transaction may be authorised or declined. Should a transaction result in a sytem error code, it is expected that this transaction has reached authorisation through to the acquirer or card issuer and the result is determined by the contacted authorisation network.

ErrorCode

Error Message

Further Information

000

Accepted Transaction

The transaction was accepted.

001

Test Transaction

The transaction was marked as being a test transaction and was successfully returned.

002

Accepted Refund

The refund was successful

003

Accepted Void Transaction

The transaction was successfully voided

011

Signature Verification

 

012

Hold

 

013

Pin Invalid

 

014

Pin Retry

 

015

Pin Tries Exceeded

 

030

Cannot Authorise

Invalid Card Number The card number was rejected on authorisation although the card was of a good format.

031

Cannot Authorise

Expired Card The card was rejected on authorisation as the card has been expired by the issuer.

032

Processing Server Unavailable

A delegating processing server was unavailable and failover servers were retried, processing cannot continue Retry the transaction, if the transaction continues to fail, please consult support stating this error code.

040

Transaction verification passed

The transaction returned was verified succesfully

041

Transaction verification failed

The transaction returned has failed to be verified

050

Waiting Authorisation

If a transaction requires authentication using 3-D Secure, it will be marked as 050 waiting for authorisation. Should the transaction never be authorised i.e. the user decided not to continue with the transaction then the transaction will remain with the status set. This value will help to define whether authorisation was not fully processed at the time of the transaction.

071

Transaction already voided

The transaction was previously voided

072

Transaction already refunded

The transaction was previously refunded to the full amount

080

Transaction cancelled

The transaction was cancelled

081

Transaction timed out

The transaction timed out while processing Occurs when the transaction queues for processing and the transaction reaches a timeout period before a processing slot becomes free. Increasing the time out period for concurrency processing will lower the likely hood of receiving this type of error

082

Terminal allocation timed out

The transaction timed out while allocating a terminal id Occurs when the transaction queues for allocation of a terminal id. Tids are unavailable if there are too many concurrent transactions for the number of terminal ids allocated.

083

Transaction timed out

The transaction timed out while connecting to the acquirer Occurs when the transaction processing to the acquirer times out before being able to conect for processing

084

Transaction timed out

The transaction timed out while awaiting a response from the acquirer Occurs when the transaction processing to the acquirer connects however there is no response in the time allocated

088

Retain Card

 

089

Referred

The bank has referred the transaction, which results in a declined payment on the internet. This is usually caused by the following reason, a request for further information, such as authorised signature or card holder identification, frequent use of the card within the last 24 hours or a random referral.

090

Declined Transaction

The transaction was declined by the card issuer. The customer should consult their card issuer to confirm the reason of the decline.

091

Declined Transaction

The transaction was declined due to the card failing the fraud check The customer should consult their card provider.

092

Declined Refund

The refund was declined

093

Declined Void Transaction

The void transaction was declined

094

Declined Transaction

Transaction Declined. CSC Failure The transaction was declined due to the CSC number not matching that on record.

095

Declined Transaction

Transaction Declined. AVS Failure The transaction was declined due to the AVS numerics of the address not matching.

096

Declined Transaction

Transaction Declined. AVS Failure The transaction was declined due to the AVS numerics of the postcode not matching.

097

Declined Transaction

Transaction Declined. AVS Failure The transaction was declined due to the AVS numerics not matching.

098

Declined Transaction

Transaction Declined. Authentication Failure The transaction was declined due to an authorisation failure.

Card Validation Errors

Card validation errors are caused by invalidity of a card. This is generally related to processing errors when cards are presented for authorisation. Cards are checked against standard specifications and card scheme specifications, therefore you may find errors occur against certain card types than others.

ErrorCode

Error Message

Further Information

C001

Card number contains non-numeric character

 

C002

LUHN Check failure

Consider the possibility that the card number was keyed incorrectly

C003

Card number missing

 

C004

Card number is an invalid length

 

C005

Card is not yet valid

The start date is in the future. Check the validity of the card start date.

C006

Card has expired

The expiry date is in the past. Check the validity of the card expiry date.

C007

Card expiry month is not a valid month

Months should be an integer value between 1 and 12

C008

Card expiry year is not a valid year

Year values should be either a 2 digit or 4 digit number

C009

Expiry date is not YYMM

When providing an expiry date as a String the format should be 2 digit YEAR and 2 digit MONTH (YYMM) for example 0412

C010

Expiry data missing

 

C011

Issue number is not numeric

 

C012

CSC Not an Integer

 

C013

CSC is longer than 4 characters

 

C014

CSC Not Present

 

C015

Start date is not YYMM

When providing an expiry date as a String the format should be 2 digit YEAR and 2 digit MONTH (YYMM) for example 0412

C016

Card start date month is not a valid month

Months should be an integer value between 1 and 12

C017

Card start date year is not a valid year

Year values should be either a 2 digit or 4 digit number

C018

Card has previously been charged back

 

C019

Invalid expiry date

The expiry date is so far in the future that it is considered invalid. By default, this error is logged for expiry dates more than 7 years in the future; this offset may be changed by contacting support. Check the validity of the card expiry date and consider changing the Override Expiration Period.

C020

Invalid Start Date

The card start date contains an invalid date, invalid characters or has not been entered when required. Some card details may contain 2 digits and others 4 digits. Occasionally an invalid issue number may affect the start date.

C021

Card number is invalid

The card number is not a valid number

C022

Bin range not found

The card number provided cannot be used for this transaction

C023

Unexpected Issue Number

An unexpected issue number is present in the card details

C024

Expected Issue Number

An expected issue number is not present in the card details

C025

Invalid Issue Number

An invalid issue number is present in the card details

C026

CSC Length is invalid for Card

The length of the card security code (CSC,CV2,CVV2) is invalid for the given card type. Visa and Mastercard, generally require a 3 digit code where as American Express require 4 digits.

C027

Card has expired

The card is recognised as being expired. The cardholder is required to check with the card issuer as the authorisation returned the expiry response.

C028

Card holder name is mandatory

The card holder name is mandatory and is not supplied. The card holder's name is mandatory by this acquirer and should be supplied before continuing.

Data Error

The data error group determines that configuration and variable data is invalid. Commands or actions cannot be completed until data errors are ammended.

ErrorCode

Error Message

Further Information

D001

Gateway Not Configured Error

The gateway is not available as there is no configuration data available. Contact CityPay support by emailing support@CityPay.com

D002

Gateway Configuration Error

The gateway is not available as there is a problem with the configuration. Contact CityPay support by emailing support@CityPay.com

D003

Fraud Module Configuration Error

The fraud module is not available as there is a problem with the configuration. Contact CityPay support by emailing support@CityPay.com

D004

Class Instantiation Error

An internal gatway problem. Contact CityPay support by emailing support@CityPay.com

D005

Class Illegal Access Error

An internal gateway problem. Contact CityPay support by emailing support@CityPay.com

D006

Unkown Terminal

The terminal configuration information is invalid. Contact CityPay support by emailing support@CityPay.com

D007

Unauthorised to use this Terminal

The user is not authorised to use this terminal. Contact CityPay support by emailing support@CityPay.com

D008

Terminal Inactive

The terminal being used is currently inactive. Contact CityPay support by emailing support@CityPay.com

D009

Password Invalid

The password being used is invalid. Contact CityPay support by emailing support@CityPay.com

D010

User Invalid

The user is invalid. Contact CityPay support by emailing support@CityPay.com

D011

User does not have permission to perform this operation

User does not have permission to perform this operation Contact CityPay support by emailing support@CityPay.com

D012

Hostile card list is not available

The system cannot retrieve details from the hostile card list Contact CityPay support by emailing support@CityPay.com

D013

Merchant is not found

The merchant number is invalid Contact CityPay support by emailing support@CityPay.com

D014

Card holder must be present

The card holder must be present for this transaction Contact CityPay support by emailing support@CityPay.com

D015

Invalid Currency Code

The currency code provided is not a valid currency code Contact CityPay support by emailing support@CityPay.com

D016

Card type or currency for merchant not found

The card bin range or currency code is not valid for the given merchant. Contact CityPay support by emailing support@CityPay.com

D017

Cardholder must be present

The cardholder must be pressent for this transaction. Contact CityPay support by emailing support@CityPay.com

D018

Card must be present

The card must be pressent for this transaction. Contact CityPay support by emailing support@CityPay.com

D019

Manual entry not allowed for this merchant

The merchant is not allowed to perform a manual entry. Contact CityPay support by emailing support@CityPay.com

D020

Invalid Transaction Type

The transaction type requested is invalid. Contact CityPay support by emailing support@CityPay.com

D021

Transaction not allowed for card

The transaction is not allowed for the given card. Contact CityPay support by emailing support@CityPay.com

D022

Transaction not found for merchant with given trasaction number

A transaction cannot be found for the merchant using the given transaction number. Contact CityPay support by emailing support@CityPay.com

D023

Transaction not found for merchant with given identifier

A transaction cannot be found for the merchant using the given identifier. Contact CityPay support by emailing support@CityPay.com

D024

Decryption currently unavailable

The crypto server cannot be contacted for decryption, decryption requests are unavailable. Contact CityPay support by emailing support@CityPay.com

D025

Encryption currently unavailable

The crypto server cannot be contacted for encryption, encryption requests are unavailable. Contact CityPay support by emailing support@CityPay.com

D026

No batch id presented

A batch id was required to perform the action and was not preset. Batch ids are required when batching transactions for processing and are generally unique. Consult the integration documentation for exact requirements on the data required.

D027

No client id presented

A client id was required to perform the action and was not preset. Client ids are required when batching transactions and should be presented, consult your documentation for details on the requirement.

D028

None ASCII characters found in data

none ASCII encoded data was found when the data is restricted to the ASCII type. Data is restricted to an ASCII character set, ensure that none ASCII characters are not present.

D029

Invalid Encoding Error

The data contains an invalid encoding that is not allowed for the resource. Confirm that the encoding of the data is restricted to the character set required within the specifications documentation. Data should be restricted to the required encoding.

D030

Batch does not contain transactions

The batch presented for processing does not contain any transactions. Check that the batch contains transactions.

D031

Store is not found

The store id is invalid Contact CityPay support by emailing support@CityPay.com

D032

Store is inactive

The store defined by the store id is inactive Contact CityPay support by emailing support@CityPay.com

D033

Field value is an invalid signed integer value

The maximum integer value is 0x7fffffff. The provided value is too large Contact CityPay support by emailing support@CityPay.com

D034

Field value is an invalid signed long value

The maximum integer value is 0x7fffffffffffffff. The provided value is too large Contact CityPay support by emailing support@CityPay.com

D035

Field value is an invalid signed short value

The maximum integer value is 32767. The provided value is too large Contact CityPay support by emailing support@CityPay.com

D036

The Card Scheme could not be determined

Check the card pan to confirm that the pan number is correct and that the bin range entry for this card is available Contact CityPay support by emailing support@CityPay.com

D037

Acquirer is unavailable

The acquirer for this request is currently unavailable Contact CityPay support by emailing support@CityPay.com

D038

Gateway route is unavailable

The gateway route for this transaction is currently unavailable. This may be caused by a configuration change, technical fault or planned works Contact CityPay support by emailing support@CityPay.com

D039

No Terminal ID available

A terminal id is required to process a transaction. Dependant on the acquirer this may be due to a limitation of concurrency in processing against the number of allocation terminal IDs to the account. Contact CityPay support by emailing support@CityPay.com

D040

Acquirer Dataset is not found for transaction

No acquirer dataset is configured to handle this tranaction Contact CityPay support by emailing support@CityPay.com

D041

3DSecure Currently Unavailable

The ecommerce transaction requires 3DSecure for processing and the Merchant Plug In is currently unavailable. Please retry later The MPI is currently unavailable either due to a period of maintenance or a system error. Please contact CityPay support for information

D042

3DSecure Enrollment Error

The account is not enrolled fully for 3DSecure

D043

3DSecure Configuration Error

The account contains invalid or no configuration information which prevented a 3DSecure session from continuing

D044

3DSecure Merchant URI Invalid

The Merchant URI is either blank or invalid for 3DSecure authentication

D045

3DSecure Accept Headers Invalid

The Accept Headers is either blank or invalid for 3DSecure authentication

D046

3DSecure User Agent Invalid

The User Agent is either blank or invalid for 3DSecure authentication

D047

3DSecure Directory Server Comms Failure

A communication failure was realised while contacting the 3dsecure directory server

Fatal Error

Fatal errors are errors that have prevented authorisation from occurring such as communications errors or application errors. An engineer will be alerted whenever a fatal error occurs to investigate occurrences of these error types.

ErrorCode

Error Message

Further Information

F001

Unknown Error

 

F002

Data Error

 

F003

System Error

 

F004

Null error occurred

 

F005

Unknown Transaction Type

 

F006

Communication Error

 

Request Error

Request errors are caused when variables or parameters are provided for authorisation and they do not meet the requirements set out in the documentation for the API. Request errors will prevent authorisation from occurring.

ErrorCode

Error Message

Further Information

P001

Response type not set

 

P002

Merchant ID Not Supplied

 

P003

Merchant ID Is Invalid

 

P004

Amount is not supplied

 

P005

Amount is invalid

The transaction amount sent in the transaction request is invalid because it is too long or contains characters other than digits. Check the validity of the amount field.

P006

Amount is not supplied in the lowest denomination

 

P007

The request is not from an accepted source

 

P008

The referal source is unknown

This error occurs when the system cannot identify the source of the request (IP or HTTP Header).

P009

AVS Postcode is not supplied

 

P010

AVS Postcode greater than 8 characters

The AVS value contains too many numeric values

P011

AVS Address is not supplied

 

P012

AVS Address greater than 8 characters

The AVS value contains too many numeric values

P013

Transaction Id or Identifier not Present

 

P014

Transaction Id not Numeric

The transaction ID should be a numeric value

P015

Ceiling Limit Exceeded

The transaction amount for this transaction request is above the ceiling limit for the relevant Merchant.

P016

Identifier is greater than 50 characters

The identifier must be an alphanumeric value up to 50 characters in length

P017

LicenceKey is greater than 255 characters

The licencekey value must be an alphanumeric value up to 255 characters in length

P018

Invalid transaction type

The transaction type is not allowed for this merchant

P019

Validation Code Error

The request failed the validation code test and is deemed to be an insecure request

P020

Cashback amount is invalid

The cash amount sent in the transaction request is invalid because it is too long or contains characters other than digits.

P021

Cashback transaction not permitted

Transaction requested cashback and the Merchant does not allow cashback transactions for the credit/debit card tendered. Establish whether cashback is permitted for this card type in your merchant agreement.

P022

Cashback ceiling limit exceeded

The cash amount for this transaction request is above the ceiling limit for the relevant MerchantID.

P023

Invalid transaction type code

The transaction request does not have a valid Transaction Type code.

P024

Void Transaction failed, invalid orginal transaction

The request for a void transaction failed due to the original transaction not being valid.

P025

Void Transaction failed, no valid original authcode

The request for a void transaction failed due to the original transaction not hvaing a valid authorisation code.

P026

Identifier is not supplied

The transaction identifier was not supplied by the merchant. A valid identifier should be supplied by the merchant.

P027

Email address is not supplied

The email address is required and was not supplied by the merchant. A valid email address should be supplied by the merchant within the request.

P028

Product information is not supplied

Product Information is required for this transaction and was not supplied by the merchant. A valid product information string should be supplied by the merchant within the request.

P029

Authorisation key is not supplied

An authorisation key is required for this request and was not supplied A valid authorisation key string should be supplied by the merchant within the request. If you do not possess this key, please contact support.

P030

Authorisation invalid

 

P031

Unsupported transaction type

The transaction type requested is not supported by the gateway.

P032

Transaction type not available for processing

The transaction type is not configured for the merchant.

P033

Card scheme not available for processing

The card scheme is not configured for the merchant.

P034

Invalid Currency

The currency specified is invalid.

P035

Licence key is not supplied

The Licence key is required for processing and was not supplied.

P036

Licence key does not match

The Licence key was supplied but did not match the key required for processing.

P037

Licence key invalid

The Licence key was supplied and was not a valid key.

P038

Floor limit not reached

The floor limit was not reached for processing the transaction. Increase the amount charged or reduce the floor limit

P039

Identifier is less than 4 characters

The identifier must be an alphanumeric value greater than 4 characters in length

P040

Account Number Not Supplied

A card holder account number was not supplied and therefore the transaction cannot continue

P041

Account Number is an invalid length

A card holder account number is an invalid length

P042

Account Number contains invalid characters

A card holder account number contains non ascii characters or contains spaces surrounding the value

P043

Account Number not found

A card holder account was not found for the given request. Please check the account number and/or password is correct

P044

Field not provided

The given field was not provided and is required. Please check the documentation provided with your installation instructions.

P045

Field value invalid

The given field value is invalid. Please check the documentation provided with your installation instructions.

Refund Errors

Refund errors are errors purely related to processing refunds.

ErrorCode

Error Message

Further Information

R001

Could not identify the original transaction

 

R002

Transaction Exceeds original value

 

R003

Transaction has already been refunded

 

R004

Error retrieving original amount

 

R005

The amount to refund exceeds the amount available to refund

 

R006

Refund not permitted for MerchantID

Transaction requested a refund and the Merchant does not allow refunds on the credit/debit card tendered.

R007

Transaction number is not a valid number

The transaction number provided is invalid for the request and must be a valid integer.

R008

Refund Security Code invalid

The refund security code was provided but did not match the required security code for the provided merchant id

R009

Refund Security Code Not Provided

The refund security code was not provided and is required to perform a refund.

R010

Original transaction is not a valid purchase

The transaction cannot be refunded because the original transaction is not a valid purchase.

R011

Original transaction was not accepted

The transaction cannot be refunded because the original transaction was not accepted.

Security Error

The Security group defines a group of codes that identify that an error was found which could be a security risk.

ErrorCode

Error Message

Further Information

S001

Invalid Client ID

The client id provided is invalid Check the client id supplied is the correct CityPay client id.

S002

Invalid Merchant ID

The merchant id provided is invalid Check the merchant id supplied is the correct CityPay merchant id.

S003

Invalid Merchant and Client ID Combination

Either the merchant id or client id provided is invalid for this request Check the client id and merchant id that are supplied are the correct CityPay ids.

S004

General Authentication Failure

The authentication failed for the requested service. Check the authentication requirements of the service and ensure that the values are correct.

S005

Not Authorised

You are not authorised to perform the operation Check your authentication properties and contact CityPay support to ensure that these values are correct

S006

Not Licenced

You are not licenced to perform this operation Contact CityPay support or sales for confirmation on your licencing requirements and provision.

S007

Authentication Required

Authentication is required to perform this operation and no authentication was presented for authorisation. Check the values you are submitting are provided as this error is generally thrown when no data is presented for authorisation.

S008

Invalid Licence Key

The given licence key is invalid. Check the given licence key is the same that was provided by CityPay or that the key has not been superseded by a newer version.

Transaction Error

The Transaction error group defines a group of codes that identify that an error was found which could be a potential tranactional problem such as duplication. These errors are in place to protect both merchants and card holders from causing invalid processing.

ErrorCode

Error Message

Further Information

T001

Duplicate Transaction Error

A transaction with the same transaction reference and card details has been provided

T002

Transaction exceeds required level

 

T003

Transaction is not a valid capture

An invalid capture request was requested. Check the request to ensure the capture request matches the documentation

T004

Transaction is not a valid reversal

An invalid reversal request was requested. Check the request to ensure the reversal request matches the documentation

T005

3D Secure Authentication Error

Caused when the PARes fails digital signature validation. Cardholders should try another form of payment

T006

3D Secure Authentication Required

A transaction is required to be fully authorised using 3d secure by returning a valid CAVV and AuthenticationResult=Y Transactions are blocked if the transaction is not fully authenticated, this includes card schemes not participating. To allow this transaction to process, 3d secure must be bypassed or processed using a different coding.

T007

Pre-Auth not available for card scheme

Caused when the card scheme is not able to perform pre-authorisation requests. Cardholders should try another form of payment

T008

Pre-Auth not available for Acquirer

Caused when the Acquirer is not able to perform pre-authorisation requests. Cardholders should try another form of payment

T009

Transaction already cancelled

Caused when the transaction has already been cancelled A previous request for cancelling the transaction has been succesfully obtained

T010

Cannot cancel pre-auth transaction

Caused when the transaction is not available to be cancelled Normally occurs when a transaction is not set as pre-authorised and does not allow for cancellation to occur

T011

Transaction already completed

Caused when the transaction has already been completed A previous request for completing the transaction has been succesfully obtained

T012

Cannot complete pre-auth transaction

Caused when the transaction is not available to be completed Normally occurs when a transaction is not set as pre-authorised and does not allow for completions to occur

T013

Transaction was not authorised

A post authoriation action has found that the original transaction was not authorised and therefore the action cannot be completed The action cannot be completed on a non authorised transaction

Wallet Error

The Wallet group defines a group of codes that identify errors related purely to wallet style transactions. These codes identify relationships to processing, generation and loading of wallet accounts.

ErrorCode

Error Message

Further Information

W001

Tokens amount not present

 

W002

Tokens Amount Not an Integer

 

W003

Email Address Not Supplied

 

W004

PostCode/ZipCode Not Supplied

 

W005

Country Not Present

 

W006

Town/City Not Present

 

W007

First Address Line Not Supplied

 

W008

Last Name Not Supplied

 

W009

First Name Not Supplied

 

W010

Password not supplied

 

W011

Password Must be at least 8 chars

 

W012

An error occurred creating the account

 

W013

Could not find a wallet from the given criteria

 

W014

An error occurred obtaining the wallet

 

W015

Wallet is de-activated

 

W016

Password contains illegal characters

The password can only contain alphanumeric characters with no spaces

W017

Ceiling Limit Exceeded

 

W018

Error purchasing tokens

 

W019

Error redeeming tokens

 

W020

Redirect address is invalid

 

W021

Merchant ID is invalid

 

W022

Merchant ID is not supplied

 

W023

Request was from an invalid source

 

W024

Terms and conditions were not agreed to

The customer failed to check the terms and conditions checkbox.

W025

Floor limit not reached

The amount is not greater than the floor limit set for your account.