Paylink-v3 Paylink Transaction Response Reference

Transaction Response parameters are returned in a POSTback or a redirection URL subject to configuration. 

Merchant Authentication Fields
amount:

int

The amount field specifies the total amount of the transaction in Lowest Denomination Form, inclusive of any surcharge applied.

amount_initial:

int

The amount_initial field specifies the amount of the transaction as provided in the originating Paylink Token Request, in Lowest Denomination Form.

authcode:

string

The authcode field contains the Authorisation Code returned by the Payment Card Acquirer if the transaction was successful . An Authorisation Code is an alpha-numeric string of characters and may in some cases be an empty string.

authorised:

boolean 

The authorised field authoritatively indicates that the transaction was authorised and was successful ; the authResult and errorCode fields may be used for more detailed information on the successful or failed transaction.

This value will be true for a live as well as a test transaction. It is therefore recommended to also check the mode field to ensure your system handles test transactions appropriately.

currency:

string

The currency field contains the currency of the transaction as an ISO 4217 3 digit alpha-numeric value.

errorcode:

string

The errorcode field contains an error code for the transaction Processing Request. An exhaustive list of error codes is available from API Response & Error Codes

errorid:

string

The errorid field contains a Paylink internal error code for the transaction Processing Request in the form 000.000.000 for use in correspondence in relation to Paylink support issues.

errormessage:

string

The errormessage field contains a textual, human-readable error message for the transaction Processing Request.

identifier:

string

The identifier field contains the identifier provided for the transaction in the originating Paylink Token Request.

merchantid:

int

The merchantid contains the CityPay Merchant MID that the transaction Processing Request was processed with.

mode:

string

The mode field specifies the mode of the transaction by returning " live " or " test ".

result:

int

The result field contains an integer result code that indicates the outcome of the transaction in more detail. The following result codes are an exhaustive list and cater for all transaction types, including electronic commerce, card present and mail-order telephone-order transactions. Some result codes may not be relevant to the Merchant Application or to processing in an online environment.

Value

Name

Description

0

Declined

Result code when a transaction is declined by the acquirer and no further processing is allowed

1

Accepted

Result code when a transaction is accepted by the acquirer.

2

Rejected

The transaction was rejected due to an error

3

Not Attempted

The transaction was never attempted to be processed (default)

4

Referred

Result code when a transaction has been referred for manual authorisation

5

Perform PIN Retry

Retry the PIN entry

6

Force Signature Verification

Force Signature Verification

7

Hold

Hold transaction and recheck

8

Security Error

Security Error

9

Call Acquirer

Call Acquirer

10

Do Not Honour

Do Not Honour

11

Retain Card

Retain Card

12

Expired Card

The card has expired. This normally occurs when a valid expiry date is supplied and the card has been superseded by the issuer.

13

Invalid Card No

The card number is invalid. This may occur after a valid LUHN check

14

Pin Tries Exceeded

The number of PIN entries have been exceeded

15

PIN Invalid

The PIN number entered is invalid

16

Authentication Required

Authentication required for a transaction, in an e-commerce transaction, the system will need to refer to an ACS

17

Authentication Failed

Authentication is required for the transaction. The authorisation process failed.

18

Verified

Is a business model which is used to verify that a card looks valid using AVS and CSC to check

19

Cancelled

A result which is returned when a pre-authorised transaction has been cancelled

20

Unknown

The unknown response is a value returned when the system has produced an error and the result cannot be determined

status:

string

The status field contains a single digit status of the authorisation. The status is a flag which determines how the transaction will be handled for settlement. Ordinarily the value of this is 'O' which indicates that the transaction is open for settlement. Merchants who have pre-authorisation enabled can determine that the transaction is pre-authorised by seeing a 'P' in this response.

Value

Name

Description

O

Open

The transaction is deemed as open for settlement and will be batched on the next scheduled batch run.

 

A Assigned The transaction has been assigned to a batch and will be settled on the next settlement run.
S Settled The transaction has been settled to the acquirer.
X Storage Failure This is used internally to determine if there was a problem in storage, you would not expect this value from Paylink
D Declined The transaction has been declined and will not settle
R Rejected The transaction has been rejected and will not settle
P PreAuth The transaction has been pre-authorised. The transaction will require a completion or a cancellation to settle.
C Cancelled The transaction has been cancelled and will not settle. Ordinarily a reversal would have occurred with the acquiring bank.
E Expired The transaction has expired and has automatically been reversed. The transaction will not settle.
I Initialised This is used internally to determine that the transaction has been initialised, you would not expect this value from Paylink
H Wait For Auth The transaction has been halted, waiting for authentication such as 3DSecure.
. Hold The transaction has been placed on hold and requires intervention. This is used by the grey listing of our fraud systems. (Full stop)
? Unknown This is a status which cannot be determined, you would not expect this value from Paylink
surcharge:

int

If surcharge functionality is enabled for the Merchant MID, the surcharge field contains the amount that has been added to the transaction by way of surcharge for the Payment Card selected to make the payment by the Payment Card Holder.

Surcharge functionality enables the Merchant to apply a fixed percentage charge or a fixed amount charge against a transaction to enable the Merchant to recover their costs of Payment Card processing. The actual surcharges to be applied to transactions are associated with a particular Merchant MID.
surcharge_rate:

int

If surcharge functionality is enabled for the Merchant MID, the surcharge_rate field contains the rate in which the surcharge was applied.

transno:

int

The transno contains a Merchant-unique serial number for the transaction. The transno for a test transaction is -99; and for a transaction Processing Request that generated validation and request processing errors, -1.

Card Details
cardSchemeId:

string

The cardSchemeId field contains an identifier for the card scheme of the Payment Card that was processed in the transaction.

cardScheme:

string

The cardScheme field contains a string describing the card scheme of the Payment Card that was processed in the transaction.

expMonth:

int

The month of expiry of the card 1..12

expYear:

int

The year of expiry of the card i.e. 2014

maskedPan:

string

The maskedPan field contains a masked version of the Card Number used by the Card Holder when completing the Payment Form.

The Payment Card Number is masked by providing the first 6 numbers which identify the BIN Range for the Payment Card and the last 4 digits only; all other digits are substituted by an asterisk. For example: 412312******2151.

Card Holder Details
address:

string

The address field contains the Payment Card Holder address used by the Customer when completing the Payment Form.

country:

string

The country field contains the country code that the Payment Card Holder selected when completing the Payment Form.

email:

string

The email field contains the email address that the Payment Card Holder entered when completing the Payment Form.

firstname:

string

The firstname field contains the first name of the Payment Card Holder as entered on the Payment Form.

lastname:

string

The lastname field contains the last name of the Payment Card Holder as entered in within the Payment Form.

postcode:

string

The postcode field contains the postcode that the Payment Card Holder entered when completing the Payment Form.

title:

string

The title field contains the title of the Payment Card Holder as entered on the Payment Form.

RFA Fraud Response Fields
AVSResponse:

string

The AVSResponse field contains the result of address verification by the upstream Payment Card Acquirer

Value

Description

' ' (Space)

No information

A

Address matches, post code does not

B

Postal code not verified due to incompatible formats

C

Street address and Postal code not verified due to incompatible formats

D

Street address and postal codes match

E

AVS Error

G

Issuer does not participate in AVS

I

Address information verified for international transaction

M

Street address and Postal codes match for international transaction

N

No match on address or postcode

P

Postal codes match. Street address not verified due to to incompatible formats

R

System unavailable or Timed Out

S

Service not supported by issuer or processor

U

Address information unavailable

W

9 digit post code matches, Address does not

X

Postcode and Address match

Y

Address and 5 digit post code match

Z

5 digit post code matches, Address does not

The meaning of some values are duplicated due to the source values from MasterCard and Visa.

CSCResponse:

string

The CSCResponse field contains the result of the card security code checking by the upstream Payment Card Acquirer

Value

Description

M

Card verification data matches

N

the card verification data was checked but did not match

P

The card verification data was not processed

S

The card verification data should be on a card but the merchant indicates that it is not

U

Issuer not certified, did not provide the data or both

 

No information

3DSecure Result Codes
cavv:

string

The cavv field is set to a value generated by the Card Issuer during authentication. The cavv can provide evidence of transaction authentication during an online purchase. If the transaction is authenticated, this value should be kept to receive chargeback protection.

eci:

string

The eci field contains the Electronic Commerce Indicator (ECI) which indicates the level of security applied when the cardholder provided payment card details to the Merchant. Values for the eci field are

5: set when a transaction has been fully authenticate using 3DSecure;

6: set when an attempt is made to authenticate the cardholder using 3DSecure, but the Payment Card Issuer or the Payment Card Holder were not participating in the 3DSecure scheme, or the Payment Card Issuer ACS was not able to respond to the request;

7: set when transaction authentication was unsuccessful or not attempted.

authenticationResult:

string

The authenticationResult field provides the outcome of 3DSecure authentication as follows

Y : authentication was successful;
N : authentication failed;
U : authentication could not be performed;
A : authentication was attempted but could not be performed

Authentication that could not be performed or attempted may result in a transaction that is authorised by the Acquirer. In such circumstances, the transaction may be subject to a higher risk profile and may not benefit from the shift in fraudulent transaction liability from Merchant to Customer that 3DSecure authentication generally provides.

CityPay are able to control the workflow of your transaction if you desire only fully authenticated transactions to be authorised.

Cardholder Account Fields
cac:

int

The cac field contains the results of the control path followed by Paylink 3 in response to a transaction Processing Request for a transaction which the Merchant Application indicated, by MID configuration or through the originating Paylink Token Request, that it requires to be associated with a Cardholder Account. The values returned in the cac field are as follows

0 indicates that no action has been taken;
1

indicates that the Cardholder Account referenced in the accountNo field of the originating Paylink Token Request was loaded and processed;

This result code is not usually generated in the context of a transaction progressed using the Payment Form.

2 indicates that a new Cardholder Account, with the account reference returned in the cac_id, was created successfully in circumstances where the Merchant Application has not provided an identifier in the accountNo field of the originating Paylink Token Request;
3 indicates that the Cardholder Account with the identifier given by the accountNo field in the originating Paylink Token Request was updated with cardholder details such as the billing address and postal code submitted to Paylink 3 by the Customer using the Payment Form;
4

indicates that the Cardholder Account with the identifier given by the accountNo field in the originating Paylink Token Request was deleted;

This result code is not usually generated in the context of a transaction progressed using the Payment Form.

5 indicates that the Cardholder Account with the identifier given by the accountNo field in the originating Paylink Token Request.
cac_id:

string

The cac_id field contains the identifier of the Cardholder Account associated with the transaction.

transaction Response Digests
digest:

string (deprecated - md5 is known to be broken)

The digest field contains the results of an MD5 Hash Function applied to a subset of fields in the transaction Processing Response encoded as a Base64 string. The digest comprises the following parameters

  • authcode
  • amount
  • errorcode
  • merchantid
  • transno
  • identifier
  • licencekey

 

This field is deprecated as MD5 is known to be broken. Please use sha256 instead.

sha1:

string

The sha1 field contains the results of a SHA1 Hash Function applied to a subset of fields in the transaction Processing Response encoded as a Base64 string. The digest comprises the following parameters

  • authcode
  • amount
  • errorcode
  • merchantid
  • transno
  • identifier
  • licencekey

Although SHA1 is still in wide use, it is ending the end of its life time, it is therefore recommended to use sha256 in preference.

sha256:

string

The sha256 field contains the results of a SHA256 Hash Function applied to a subset of fields in the transaction Processing Response encoded as a Base64 string. The digest comprises the following parameters

  • authcode
  • amount
  • errorcode
  • merchantid
  • transno
  • identifier
  • licencekey

Handling the Digest

A digest is used to trust the integrity of the returned data. This is performed by concatenating fields of the response with additional information not present in the response data. To handle a digest

  1. concatenate the following response fields, in order  authcodeamounterrorcodemerchantidtransnoidentifierlicencekey
  2. apply through the hash function
  3. encode the byte array result from the hash function as a base64 string
  4. compare the generated value to the value returned by Paylink
  5. if the both digests are the same, the integrity of the data is correct
  6. if the digests differ, the data should be considered as incorrect. It is up to your application whether to accept the result at this time

To test the digest, use the values "A12345", "55731", "001", "12345", "2074", "os11a3v0il9f7iqfos765o1lh21250232646", "2Y9000000007" which result in a digest values of. For instance 

var x = "A1234555731001123452074os11a3v0il9f7iqfos765o1lh212502326462Y9000000007";
// H is a digest function such as SHA-256
var digestMatched = H(x) == "digest-value"
Algorithm Example Value
MD5 6/6eA4PcNekKGUfhfjRvtw== 
SHA-1 vO3FEspL0I0vBmCtbzR6uz5eJIE=
SHA-256 VYcQXQf7l78VG52QRkCgBlhVCzTE/ztAiYPlJXaQzYQ=

Algorithm Usage

Paylink supports MD5, SHA-1 and SHA-256. Both MD5 and SHA-1 are no longer considered secure. CityPay therefore recommend checking the SHA-256 digest value returned within the sha256 parameter.

+44 (0)1534 884000