Data Types

The following data types are used throughout the CityPay APIs and integration layers

The CityPay Payment API uses the following authorisation result codes in its response messages:

CodeName
0Declined
1Accepted
2Rejected
3NotAttempted
4Referred
5PinRetry
6ForceSigVerify
7Hold
8SecurityError
9CallAcquirer
10DoNotHonour
11RetainCard
12ExpiredCard
13InvalidCardNo
14PinTriesExceeded
15PinInvalid
16AuthReq
17AuthFail
18Verified
19Cancelled
20Unknown
21Challenged
22Decoupled
23PermissionDenied

The CityPay Payment API uses the following AVS result codes in its response messages:

CodeDescription
Z5 digit post code matches, Address does not
YAddress and 5 digit post code match
XPostcode and address match
W9 digit post code matches, Address does not
UNo AVS data available from issuer auth system
SAVS Service not supported by issuer or processor
RRetry, System unavailble or Timed Out
PPostal codes match. Street address not verified due to to incompatible formats
NNeither postcode nor address match
MStreet address and Postal codes match for international transaction
IAddress information verified for international transaction
GIssuer does not participate in AVS
EAVS Error
DStreet address and postal codes match
CStreet address and Postal code not verified due to incompatible formats
BPostal code not verified due to incompatible formats
AAddres matches, post code does not
No information

The CityPay Payment API uses the following Batch status codes in its response messages:

CodeDescription
UNKNOWNThe file is of an unknown status, that is the file can either not be determined by the information requested of the file has not yet been received
QUEUEDThe file has been queued for processing yet no processing has yet been performed
LOCKEDThe file has been locked for processing
INITIALISEDThe file has been initialised and no action has yet been performed
ERROR_IN_PROCESSINGErrors have occurred in the processing that has deemed that processing can not continue.
COMPLETEThe file has passed through the processing cycle and is determined as being complete further information should be obtained on the results of the processing
CANCELLEDThe file has been cancelled by an administrator or server process.

This API supports the following negotiated ciphers. Most modern HTTP clients will negotiate these ciphers with no additional requirements.

PriorityCipher
1ECDHE-ECDSA-AES128-GCM-SHA256
2ECDHE-RSA-AES128-GCM-SHA256
3ECDHE-ECDSA-AES128-SHA256
4ECDHE-RSA-AES128-SHA256
5ECDHE-ECDSA-AES128-SHA
6ECDHE-RSA-AES128-SHA
7ECDHE-ECDSA-AES256-GCM-SHA384
8ECDHE-RSA-AES256-GCM-SHA384
9ECDHE-ECDSA-AES256-SHA384
10ECDHE-RSA-AES256-SHA384
11ECDHE-RSA-AES256-SHA
12ECDHE-ECDSA-AES256-SHA

The CityPay Payment API uses the following CSC result codes in its response messages:

CodeDescription
UThe card issuer is not certified
SThe card verification data should be on the card but the merchant indicates that it is not
PCard verification was not processed
NCard verification data was checked but did not match
MCard verification data matches
No information

The CityPay Payment API uses the following response codes in its response messages:

CodeMessageDescription
000Accepted TransactionThe transaction was accepted.
001Test TransactionThe transaction was marked as being a test transaction and was successfully returned.
002Accepted RefundThe refund was successful
003Accepted Void TransactionThe transaction was successfully voided
011Signature Verification
012Hold
013Pin Invalid
014Pin Retry
015Pin Tries Exceeded
030Cannot AuthoriseInvalid Card Number
031Cannot AuthoriseExpired Card
032Processing Server UnavailableA delegating processing server was unavailable and failover servers were retried, processing cannot continue
040Transaction verification passedThe transaction returned was verified succesfully
041Transaction verification failedThe transaction returned has failed to be verified
044Ping OKA ping request was received and the server is replying to it
050Waiting Authorisation
064Mandated DeclineThe transaction was declined due to an enforced mandate by the card scheme or acquirer
065Soft DeclinedThe transaction was declined however may be reprocessed with authentication
071Transaction already voidedThe transaction was previously voided
072Transaction already refundedThe transaction was previously refunded to the full amount
080Transaction cancelledThe transaction was cancelled
081Transaction timed outThe transaction timed out while processing
082Terminal allocation timed outThe transaction timed out while allocating a terminal id
083Transaction timed outThe transaction timed out while connecting to the acquirer
084Transaction timed outThe transaction timed out while awaiting a response from the acquirer
085Concurrency Limit ReachedThe transaction could not be processed as the concurrency levels have been met
087Revocation of OrderThe transaction has been revoked by the card holder, and must not retry with the same card details. Alternative payment details should be provided
088Retain Card
089Referred
090Declined TransactionThe transaction was declined by the card issuer.
091Declined TransactionThe transaction was declined due to the card failing the fraud check
092Declined RefundThe refund was declined
093Declined Void TransactionThe void transaction was declined
094Declined TransactionTransaction Declined. CSC Failure
095Declined TransactionTransaction Declined. AVS Failure
096Declined TransactionTransaction Declined. AVS Failure
097Declined TransactionTransaction Declined. AVS Failure
098Declined TransactionTransaction Declined. Authentication Failure
B001Batch Processing unavailableOccurs when batch processing is unavailable for processing
B002Batch does not existOccurs when a batch requested does not exist
B003No batch ids providedThe request expects a batch id however no id was found
B004Invalid Batch IdOccurs when a batch id is an invalid format
B005No transactions on batchThe batch requested has no transactions included
B006Transaction invalid in batchA transaction has been found to be invalid within the batch preventing processing
B007Batch date is invalidThe batch date provided cannot be parsed or is an invalid date value
B008Batch failed duplication checksThe batch is a duplicate and cannot be processed
B009Batch maximum number of transactions reachedThe batch can contain up to 10,000 transactions on production and 100 in sandbox.
C001Card number contains non-numeric character
C002LUHN Check failureConsider the possibility that the card number was keyed incorrectly
C003Card number missing
C004Card number is an invalid length
C005Card is not yet validThe start date is in the future.
C006Card has expiredThe expiry date is in the past.
C007Card expiry month is not a valid monthMonths should be an integer value between 1 and 12
C008Card expiry year is not a valid yearYear values should be either a 2 digit or 4 digit number
C009Expiry date is not YYMMWhen providing an expiry date as a String the format should be 2 digit YEAR and 2 digit MONTH (YYMM) for example 0412
C010Expiry data missing
C011Issue number is not numeric
C012CSC Not an Integer
C013CSC is longer than 4 characters
C014CSC Not Present
C015Start date is not YYMMWhen providing an expiry date as a String the format should be 2 digit YEAR and 2 digit MONTH (YYMM) for example 0412
C016Card start date month is not a valid monthMonths should be an integer value between 1 and 12
C017Card start date year is not a valid yearYear values should be either a 2 digit or 4 digit number
C018Card has previously been charged back
C019Invalid expiry dateThe 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.
C020Invalid Start DateThe card start date contains an invalid date, invalid characters or has not been entered when required.
C021Card number is invalidThe card number is not a valid number
C022Bin range not foundThe card number provided cannot be used for this transaction
C023Unexpected Issue NumberAn unexpected issue number is present in the card details
C024Expected Issue NumberAn expected issue number is not present in the card details
C025Invalid Issue NumberAn invalid issue number is present in the card details
C026CSC Length is invalid for CardThe 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.
C027Card has expiredThe card is recognised as being expired.
C028Card holder name is mandatoryThe card holder name is mandatory and is not supplied.
D001Gateway Not Configured ErrorThe gateway is not available as there is no configuration data available.
D002Gateway Configuration ErrorThe gateway is not available as there is a problem with the configuration.
D003Fraud Module Configuration ErrorThe fraud module is not available as there is a problem with the configuration.
D004Class Instantiation ErrorAn internal gatway problem.
D005Class Illegal Access ErrorAn internal gateway problem.
D006Unkown TerminalThe terminal configuration information is invalid.
D007Unauthorised to use this TerminalThe user is not authorised to use this terminal.
D008Terminal InactiveThe terminal being used is currently inactive.
D009Password InvalidThe password being used is invalid.
D010User InvalidThe user is invalid.
D011User does not have permission to perform this operationUser does not have permission to perform this operation
D012Hostile card list is not availableThe system cannot retrieve details from the hostile card list
D013Merchant is not foundThe merchant number is invalid
D014Card holder must be presentThe card holder must be present for this transaction
D015Invalid Currency CodeThe currency code provided is not a valid currency code
D016Card type or currency for merchant not foundThe card bin range or currency code is not valid for the given merchant.
D017Cardholder must be presentThe cardholder must be pressent for this transaction.
D018Card must be presentThe card must be pressent for this transaction.
D019Manual entry not allowed for this merchantThe merchant is not allowed to perform a manual entry.
D020Invalid Transaction TypeThe transaction type requested is invalid.
D021Transaction not allowed for cardThe transaction is not allowed for the given card.
D022Transaction not found for merchant with given trasaction numberA transaction cannot be found for the merchant using the given transaction number.
D023Transaction not found for merchant with given identifierA transaction cannot be found for the merchant using the given identifier.
D024Decryption currently unavailableThe crypto server cannot be contacted for decryption, decryption requests are unavailable.
D025Encryption currently unavailableThe crypto server cannot be contacted for encryption, encryption requests are unavailable.
D026No batch id presentedA batch id was required to perform the action and was not preset.
D027No client id presentedA client id was required to perform the action and was not preset.
D028None ASCII characters found in datanone ASCII encoded data was found when the data is restricted to the ASCII type.
D029Invalid Encoding ErrorThe data contains an invalid encoding that is not allowed for the resource.
D030Batch does not contain transactionsThe batch presented for processing does not contain any transactions.
D031Store is not foundThe store id is invalid
D032Store is inactiveThe store defined by the store id is inactive
D033Field value is an invalid signed integer valueThe maximum integer value is 0x7fffffff. The provided value is too large
D034Field value is an invalid signed long valueThe maximum integer value is 0x7fffffffffffffff. The provided value is too large
D035Field value is an invalid signed short valueThe maximum integer value is 32767. The provided value is too large
D036The Card Scheme could not be determinedCheck the card pan to confirm that the pan number is correct and that the bin range entry for this card is available
D037Acquirer is unavailableThe acquirer for this request is currently unavailable
D038Gateway route is unavailableThe gateway route for this transaction is currently unavailable. This may be caused by a configuration change, technical fault or planned works
D039No Terminal ID availableA 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.
D040Acquirer Dataset is not found for transactionNo acquirer dataset is configured to handle this transaction
D0413DSecure Currently UnavailableThe ecommerce transaction requires 3DSecure for processing and the Merchant Plug In is currently unavailable. Please retry later
D0423DSecure Enrollment ErrorThe account is not enrolled fully for 3DSecure
D0433DSecure Configuration ErrorThe account contains invalid or no configuration information which prevented a 3DSecure session from continuing
D0443DSecure Merchant URI InvalidThe Merchant URI is either blank or invalid for 3DSecure authentication
D0453DSecure Accept Headers InvalidThe Accept Headers is either blank or invalid for 3DSecure authentication
D0463DSecure User Agent InvalidThe User Agent is either blank or invalid for 3DSecure authentication
D0473DSecure Directory Server Comms FailureA communication failure was realised while contacting the 3dsecure directory server
D048Account Id is InvalidThe account id supplied is not in the required format. Account ids must contain URL sensitive characters only such as [a-zA-Z0-9-_.~]
D049Account Already ExistsThe account id provided, already exists and does not allow for accounts with the same id
D050Test ErrorAn error used for testing purposes
D101Data is not foundThe requested data does not exist
D102Data is lockedThe requested data exists however it is currently locked from access
F001Unknown Error
F002Data Error
F003System Error
F004Null error occurred
F005Unknown Transaction Type
F006Upstream Communication ErrorThe service could not connect to its upstream service. This is normally an indication that an upstream service has a problem. An engineer will be looking into the failure and retry your call later.
F007TID Allocation Timeout
L200The Paylink Session was CompletedThe Paylink session has already been processed and is now complete
L201The Paylink Session has expired and can no longer be usedThe paylink session is no longer available and has expired
L204The Paylink Session was not foundThe session identified by the token appears a valid token but is not found
L401The Paylink Session has been rejected due to a security failureSecurity checks have found a problem continuing with the session and prevented further access
L402The requested function on the Paylink Session failed validationValidation failed for the request possibly due to the parameters used.
L403The Paylink Session is locked.Field guards reattempts have been breached and may retry later. Field guards have access controls which prevents brute force attacks
P001Response type not set
P002Merchant ID Not Supplied
P003Merchant ID Is Invalid
P004Amount is not supplied
P005Amount is invalidThe transaction amount sent in the transaction request is invalid because it is too long or contains characters other than digits.
P006Amount is not supplied in the lowest denomination
P007The request is not from an accepted source
P008The referal source is unknownThis error occurs when the system cannot identify the source of the request (IP or HTTP Header).
P009AVS Postcode is not supplied
P010AVS Postcode greater than 8 charactersThe AVS value contains too many numeric values
P011AVS Address is not supplied
P012AVS Address greater than 8 charactersThe AVS value contains too many numeric values
P013Transaction Id or Identifier not Present
P014Transaction Id not NumericThe transaction ID should be a numeric value
P015Ceiling Limit ExceededThe transaction amount for this transaction request is above the ceiling limit for the relevant Merchant.
P016Identifier is greater than 50 charactersThe identifier must be an alphanumeric value up to 50 characters in length
P017LicenceKey is greater than 255 charactersThe licencekey value must be an alphanumeric value up to 255 characters in length
P018Invalid transaction typeThe transaction type is not allowed for this merchant
P019Validation Code ErrorThe request failed the validation code test and is deemed to be an insecure request
P020Cashback amount is invalidThe cash amount sent in the transaction request is invalid because it is too long or contains characters other than digits.
P021Cashback transaction not permittedTransaction requested cashback and the Merchant does not allow cashback transactions for the credit/debit card tendered.
P022Cashback ceiling limit exceededThe cash amount for this transaction request is above the ceiling limit for the relevant MerchantID.
P023Invalid transaction type codeThe transaction request does not have a valid Transaction Type code.
P024Void Transaction failed, invalid orginal transactionThe request for a void transaction failed due to the original transaction not being valid.
P025Void Transaction failed, no valid original authcodeThe request for a void transaction failed due to the original transaction not hvaing a valid authorisation code.
P026Identifier is not suppliedThe transaction identifier was not supplied by the merchant.
P027Email address is not suppliedThe email address is required and was not supplied by the merchant.
P028Product information is not suppliedProduct Information is required for this transaction and was not supplied by the merchant.
P029Authorisation key is not suppliedAn authorisation key is required for this request and was not supplied
P030Authorisation invalid
P031Unsupported transaction typeThe transaction type requested is not supported by the gateway.
P032Transaction type not available for processingThe transaction type is not configured for the merchant.
P033Card scheme not available for processingThe card scheme is not configured for the merchant.
P034Invalid CurrencyThe currency specified is invalid.
P035Licence key is not suppliedThe Licence key is required for processing and was not supplied.
P036Licence key does not matchThe Licence key was supplied but did not match the key required for processing.
P037Licence key invalidThe Licence key was supplied and was not a valid key.
P038Floor limit not reachedThe floor limit was not reached for processing the transaction.
P039Identifier is less than 5 charactersThe identifier must be an alphanumeric value 5 or more characters in length
P040Account Number Not SuppliedA card holder account number was not supplied and therefore the transaction cannot continue
P041Account Number is an invalid lengthA card holder account number is an invalid length
P042Account Number contains invalid charactersA card holder account number contains non ascii characters or contains spaces surrounding the value
P043Account Number not foundA card holder account was not found for the given request. Please check the account number and/or password is correct
P044Field not providedThe given field was not provided and is required. Please check the documentation provided with your installation instructions.
P045Field value invalidThe given field value is invalid. Please check the documentation provided with your installation instructions.
P046Cart Invalid ModeThe given cart mode is not valid
P047Cart Contains No ItemsThe cart items are required for the cart mode and contains no items
P048Cart Amount InvalidThe amounts in the cart are not valid, please ensure each amount is > 0
P049Account is Not ActiveThe card holder account is not active and cannot be used used.
P050Account has not been verifiedThe card holder account has not yet been verified. Please verify before using the account.
P051Token has expiredThe payment token has expired and can no longer be used
P052Token is not validThe token is not valid and cannot be decoded
P053Token card not foundThe token has been understood but no active card has been found that can be used for this token
R001Could not identify the original transaction
R002Transaction Exceeds original value
R003Transaction has already been refunded
R004Error retrieving original amount
R005The amount to refund exceeds the amount available to refund
R006Refund not permitted for MerchantIDTransaction requested a refund and the Merchant does not allow refunds on the credit/debit card tendered.
R007Transaction number is not a valid numberThe transaction number provided is invalid for the request and must be a valid integer.
R008Refund Security Code invalidThe refund security code was provided but did not match the required security code for the provided merchant id
R009Refund Security Code Not ProvidedThe refund security code was not provided and is required to perform a refund.
R010Original transaction is not a valid purchaseThe transaction cannot be refunded because the original transaction is not a valid purchase.
R011Original transaction was not acceptedThe transaction cannot be refunded because the original transaction was not accepted.
S001Invalid Client IDThe client id provided is invalid
S002Invalid Merchant IDThe merchant id provided is invalid
S003Invalid Merchant and Client ID CombinationEither the merchant id or client id provided is invalid for this request
S004General Authentication FailureThe authentication failed for the requested service.
S005Not AuthorisedYou are not authorised to perform the operation
S006Not LicencedYou are not licenced to perform this operation
S007Authentication RequiredAuthentication is required to perform this operation and no authentication was presented for authorisation.
S008Invalid Licence KeyThe given licence key is invalid.
S009Risk Generation Threshold Limit Reached.Risk has determined that the request cannot be completed due to too many attempts during the period.
S010Invalid MacThe provided Message Authentication Code is not valid and the integrity of the request is not confirmed.
T001Duplicate Transaction ErrorA transaction with the same transaction reference and card details has been provided
T002Transaction exceeds required level
T003Transaction is not a valid captureAn invalid capture request was requested.
T004Transaction is not a valid reversalAn invalid reversal request was requested.
T0053D Secure Authentication ErrorCaused when the PARes fails digital signature validation.
T0063D Secure Authentication RequiredA transaction is required to be fully authorised using 3d secure by returning a valid CAVV and AuthenticationResult=Y
T007Pre-Auth not available for card schemeCaused when the card scheme is not able to perform pre-authorisation requests.
T008Pre-Auth not available for AcquirerCaused when the Acquirer is not able to perform pre-authorisation requests.
T009Transaction already cancelledCaused when the transaction has already been cancelled
T010Cannot cancel pre-auth transactionCaused when the transaction is not available to be cancelled
T011Transaction already completedCaused when the transaction has already been completed
T012Cannot complete pre-auth transactionCaused when the transaction is not available to be completed
T013Transaction was not authorisedA post authorisation action has found that the original transaction was not authorised and therefore the action cannot be completed
W001Tokens amount not present
W002Tokens Amount Not an Integer
W003Email Address Not Supplied
W004PostCode/ZipCode Not Supplied
W005Country Not Present
W006Town/City Not Present
W007First Address Line Not Supplied
W008Last Name Not Supplied
W009First Name Not Supplied
W010Password not supplied
W011Password Must be at least 8 chars
W012An error occurred creating the account
W013Could not find a wallet from the given criteria
W014An error occurred obtaining the wallet
W015Wallet is de-activated
W016Password contains illegal charactersThe password can only contain alphanumeric characters with no spaces
W017Ceiling Limit Exceeded
W018Error purchasing tokens
W019Error redeeming tokens
W020Redirect address is invalid
W021Merchant ID is invalid
W022Merchant ID is not supplied
W023Request was from an invalid source
W024Terms and conditions were not agreed toThe customer failed to check the terms and conditions checkbox.
W025Floor limit not reachedThe amount is not greater than the floor limit set for your account.
Z001The requested service is not availableThe service that has been requested is not licenced or enabled on the given account. Retrying will not alter the result.
Z002The requested service is not activeThe service that has been requested is licenced however it is not enabled on the given account. Retrying will not alter the result.
Z003The requested service is not permittedThe service that has been requested is not permitted based on your current call this may be due to the source of your call or the environment used.