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:

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

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

Code	Description
Z	5 digit post code matches, Address does not
Y	Address and 5 digit post code match
X	Postcode and address match
W	9 digit post code matches, Address does not
U	No AVS data available from issuer auth system
S	AVS Service not supported by issuer or processor
R	Retry, System unavailble or Timed Out
P	Postal codes match. Street address not verified due to to incompatible formats
N	Neither postcode nor address match
M	Street address and Postal codes match for international transaction
I	Address information verified for international transaction
G	Issuer does not participate in AVS
E	AVS Error
D	Street address and postal codes match
C	Street address and Postal code not verified due to incompatible formats
B	Postal code not verified due to incompatible formats
A	Addres matches, post code does not
	No information

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

Code	Description
UNKNOWN	The 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
QUEUED	The file has been queued for processing yet no processing has yet been performed
LOCKED	The file has been locked for processing
INITIALISED	The file has been initialised and no action has yet been performed
ERROR_IN_PROCESSING	Errors have occurred in the processing that has deemed that processing can not continue.
COMPLETE	The file has passed through the processing cycle and is determined as being complete further information should be obtained on the results of the processing
CANCELLED	The 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.

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

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

Code	Description
U	The card issuer is not certified
S	The card verification data should be on the card but the merchant indicates that it is not
P	Card verification was not processed
N	Card verification data was checked but did not match
M	Card verification data matches
	No information

API Definitions

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

Code	Message	Description
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
031	Cannot Authorise	Expired Card
032	Processing Server Unavailable	A delegating processing server was unavailable and failover servers were retried, processing cannot continue
040	Transaction verification passed	The transaction returned was verified succesfully
041	Transaction verification failed	The transaction returned has failed to be verified
044	Ping OK	A ping request was received and the server is replying to it
050	Waiting Authorisation
064	Mandated Decline	The transaction was declined due to an enforced mandate by the card scheme or acquirer
065	Soft Declined	The transaction was declined however may be reprocessed with authentication
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
082	Terminal allocation timed out	The transaction timed out while allocating a terminal id
083	Transaction timed out	The transaction timed out while connecting to the acquirer
084	Transaction timed out	The transaction timed out while awaiting a response from the acquirer
085	Concurrency Limit Reached	The transaction could not be processed as the concurrency levels have been met
087	Revocation of Order	The transaction has been revoked by the card holder, and must not retry with the same card details. Alternative payment details should be provided
088	Retain Card
089	Referred
090	Declined Transaction	The transaction was declined by the card issuer.
091	Declined Transaction	The transaction was declined due to the card failing the fraud check
092	Declined Refund	The refund was declined
093	Declined Void Transaction	The void transaction was declined
094	Declined Transaction	Transaction Declined. CSC Failure
095	Declined Transaction	Transaction Declined. AVS Failure
096	Declined Transaction	Transaction Declined. AVS Failure
097	Declined Transaction	Transaction Declined. AVS Failure
098	Declined Transaction	Transaction Declined. Authentication Failure
B001	Batch Processing unavailable	Occurs when batch processing is unavailable for processing
B002	Batch does not exist	Occurs when a batch requested does not exist
B003	No batch ids provided	The request expects a batch id however no id was found
B004	Invalid Batch Id	Occurs when a batch id is an invalid format
B005	No transactions on batch	The batch requested has no transactions included
B006	Transaction invalid in batch	A transaction has been found to be invalid within the batch preventing processing
B007	Batch date is invalid	The batch date provided cannot be parsed or is an invalid date value
B008	Batch failed duplication checks	The batch is a duplicate and cannot be processed
B009	Batch maximum number of transactions reached	The batch can contain up to 10,000 transactions on production and 100 in sandbox.
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.
C006	Card has expired	The expiry date is in the past.
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.
C020	Invalid Start Date	The card start date contains an invalid date, invalid characters or has not been entered when required.
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.
C028	Card holder name is mandatory	The card holder name is mandatory and is not supplied.
D001	Gateway Not Configured Error	The gateway is not available as there is no configuration data available.
D002	Gateway Configuration Error	The gateway is not available as there is a problem with the configuration.
D003	Fraud Module Configuration Error	The fraud module is not available as there is a problem with the configuration.
D004	Class Instantiation Error	An internal gatway problem.
D005	Class Illegal Access Error	An internal gateway problem.
D006	Unkown Terminal	The terminal configuration information is invalid.
D007	Unauthorised to use this Terminal	The user is not authorised to use this terminal.
D008	Terminal Inactive	The terminal being used is currently inactive.
D009	Password Invalid	The password being used is invalid.
D010	User Invalid	The user is invalid.
D011	User does not have permission to perform this operation	User does not have permission to perform this operation
D012	Hostile card list is not available	The system cannot retrieve details from the hostile card list
D013	Merchant is not found	The merchant number is invalid
D014	Card holder must be present	The card holder must be present for this transaction
D015	Invalid Currency Code	The currency code provided is not a valid currency code
D016	Card type or currency for merchant not found	The card bin range or currency code is not valid for the given merchant.
D017	Cardholder must be present	The cardholder must be pressent for this transaction.
D018	Card must be present	The card must be pressent for this transaction.
D019	Manual entry not allowed for this merchant	The merchant is not allowed to perform a manual entry.
D020	Invalid Transaction Type	The transaction type requested is invalid.
D021	Transaction not allowed for card	The transaction is not allowed for the given card.
D022	Transaction not found for merchant with given trasaction number	A transaction cannot be found for the merchant using the given transaction number.
D023	Transaction not found for merchant with given identifier	A transaction cannot be found for the merchant using the given identifier.
D024	Decryption currently unavailable	The crypto server cannot be contacted for decryption, decryption requests are unavailable.
D025	Encryption currently unavailable	The crypto server cannot be contacted for encryption, encryption requests are unavailable.
D026	No batch id presented	A batch id was required to perform the action and was not preset.
D027	No client id presented	A client id was required to perform the action and was not preset.
D028	None ASCII characters found in data	none ASCII encoded data was found when the data is restricted to the ASCII type.
D029	Invalid Encoding Error	The data contains an invalid encoding that is not allowed for the resource.
D030	Batch does not contain transactions	The batch presented for processing does not contain any transactions.
D031	Store is not found	The store id is invalid
D032	Store is inactive	The store defined by the store id is inactive
D033	Field value is an invalid signed integer value	The maximum integer value is 0x7fffffff. The provided value is too large
D034	Field value is an invalid signed long value	The maximum integer value is 0x7fffffffffffffff. The provided value is too large
D035	Field value is an invalid signed short value	The maximum integer value is 32767. The provided value is too large
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
D037	Acquirer is unavailable	The acquirer for this request is currently unavailable
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
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.
D040	Acquirer Dataset is not found for transaction	No acquirer dataset is configured to handle this transaction
D041	3DSecure Currently Unavailable	The ecommerce transaction requires 3DSecure for processing and the Merchant Plug In is currently unavailable. Please retry later
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
D048	Account Id is Invalid	The account id supplied is not in the required format. Account ids must contain URL sensitive characters only such as [a-zA-Z0-9-_.~]
D049	Account Already Exists	The account id provided, already exists and does not allow for accounts with the same id
D050	Test Error	An error used for testing purposes
D101	Data is not found	The requested data does not exist
D102	Data is locked	The requested data exists however it is currently locked from access
F001	Unknown Error
F002	Data Error
F003	System Error
F004	Null error occurred
F005	Unknown Transaction Type
F006	Upstream Communication Error	The 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.
F007	TID Allocation Timeout
L200	The Paylink Session was Completed	The Paylink session has already been processed and is now complete
L201	The Paylink Session has expired and can no longer be used	The paylink session is no longer available and has expired
L204	The Paylink Session was not found	The session identified by the token appears a valid token but is not found
L401	The Paylink Session has been rejected due to a security failure	Security checks have found a problem continuing with the session and prevented further access
L402	The requested function on the Paylink Session failed validation	Validation failed for the request possibly due to the parameters used.
L403	The Paylink Session is locked.	Field guards reattempts have been breached and may retry later. Field guards have access controls which prevents brute force attacks
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.
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.
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.
P027	Email address is not supplied	The email address is required and was not supplied by the merchant.
P028	Product information is not supplied	Product Information is required for this transaction and was not supplied by the merchant.
P029	Authorisation key is not supplied	An authorisation key is required for this request and was not supplied
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.
P039	Identifier is less than 5 characters	The identifier must be an alphanumeric value 5 or more 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.
P046	Cart Invalid Mode	The given cart mode is not valid
P047	Cart Contains No Items	The cart items are required for the cart mode and contains no items
P048	Cart Amount Invalid	The amounts in the cart are not valid, please ensure each amount is > 0
P049	Account is Not Active	The card holder account is not active and cannot be used used.
P050	Account has not been verified	The card holder account has not yet been verified. Please verify before using the account.
P051	Token has expired	The payment token has expired and can no longer be used
P052	Token is not valid	The token is not valid and cannot be decoded
P053	Token card not found	The token has been understood but no active card has been found that can be used for this token
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.
S001	Invalid Client ID	The client id provided is invalid
S002	Invalid Merchant ID	The merchant id provided is invalid
S003	Invalid Merchant and Client ID Combination	Either the merchant id or client id provided is invalid for this request
S004	General Authentication Failure	The authentication failed for the requested service.
S005	Not Authorised	You are not authorised to perform the operation
S006	Not Licenced	You are not licenced to perform this operation
S007	Authentication Required	Authentication is required to perform this operation and no authentication was presented for authorisation.
S008	Invalid Licence Key	The given licence key is invalid.
S009	Risk Generation Threshold Limit Reached.	Risk has determined that the request cannot be completed due to too many attempts during the period.
S010	Invalid Mac	The provided Message Authentication Code is not valid and the integrity of the request is not confirmed.
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.
T004	Transaction is not a valid reversal	An invalid reversal request was requested.
T005	3D Secure Authentication Error	Caused when the PARes fails digital signature validation.
T006	3D Secure Authentication Required	A transaction is required to be fully authorised using 3d secure by returning a valid CAVV and AuthenticationResult=Y
T007	Pre-Auth not available for card scheme	Caused when the card scheme is not able to perform pre-authorisation requests.
T008	Pre-Auth not available for Acquirer	Caused when the Acquirer is not able to perform pre-authorisation requests.
T009	Transaction already cancelled	Caused when the transaction has already been cancelled
T010	Cannot cancel pre-auth transaction	Caused when the transaction is not available to be cancelled
T011	Transaction already completed	Caused when the transaction has already been completed
T012	Cannot complete pre-auth transaction	Caused when the transaction is not available to be completed
T013	Transaction was not authorised	A post authorisation action has found that the original transaction was not authorised and therefore the action cannot be completed
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.
Z001	The requested service is not available	The service that has been requested is not licenced or enabled on the given account. Retrying will not alter the result.
Z002	The requested service is not active	The service that has been requested is licenced however it is not enabled on the given account. Retrying will not alter the result.
Z003	The requested service is not permitted	The 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.