Introduction
Cross reference transactions are primarily used so that the merchant can run subsequent transactions against previous transactions without having to store the credit card details from the original transaction. These transactions may be subsequent sales (used for recurring billing), full or partial collection of funds (if the initial transaction was a pre-authorisation), or full or partial refunds (if the initial transaction was a sale or a collection)
Request
Below are the details for the request message to initiate a cross reference transaction.
|
Tag/Attribute Name |
Data Type |
Max Length |
Mandatory (Default) |
Comments |
|||
|
PaymentMessage |
Yes |
||||||
|
MerchantAuthentication |
Yes |
||||||
|
MerchantID |
A |
15 |
Yes |
The gateway account merchant ID issued (not to be confused with the MMS username) |
|||
|
Password |
A |
15 |
Yes |
The gateway account password |
|||
|
TransactionDetails |
Yes |
||||||
|
Amount (attribute) |
N |
15 |
No (False) |
The transaction amount in minor currency – e.g. for £10.00, it must be submitted as 1000. Mandatory for all TransactionTypes except VOID. Zero (0) is only supported where the TransactionType is PREAUTH. |
|||
|
CurrencyCode (attribute) |
N |
3 |
No (False) |
ISO 4217 e.g. GBP: 826. Mandatory for all TransactionTypes except VOID |
|||
|
OrderID |
A |
50 |
Yes |
A merchant side ID for the order – primarily used to for determining duplicate transactions. Pulled forward from the previous transaction if not set & NewTransaction is false |
|||
|
OrderDescription |
A |
256 |
No (See comment) |
A description for the order. Pulled forward from the previous transaction if not set & NewTransaction is false |
|||
|
MessageDetails |
|||||||
|
TransactionType (attribute) |
– |
– |
Yes |
Must be either COLLECTION, REFUND, PREAUTH, SALE, VOID or RETRY |
|||
|
|
NewTransaction (attribute) |
B |
– |
No (True) |
Instructs the gateway to treat this transaction as a new transaction |
|||
|
|
CrossReference (attribute) |
A |
25 |
Yes |
The cross reference for the previous transaction |
|||
|
|
LineItemDetails |
No |
|
|||||
|
|
SalesTaxAmount (attribute) |
N |
15 |
No |
The sales tax amount in minor currency – e.g. for £10.00, it must be submitted as 1000 |
|||
|
|
SalesTaxDescription |
A |
50 |
No |
A description of the sales tax (e.g. “VAT (20%)” |
|||
|
|
LineItems |
No |
|
|||||
|
|
|
LineItem (multiple) |
No |
|
||||
|
|
Quantity (attribute) |
N |
15 |
No |
The quantity of a single line item |
|||
|
|
Amount (attribute) |
N |
15 |
No |
The amount of a single line item in minor currency – e.g. for £10.00, it must be submitted as 1000 |
|||
|
|
Description |
A |
100 |
No |
The description of a single line item |
|||
|
|
TransactionControl |
No |
|
|||||
|
|
EchoCardType |
B |
– |
No (False) |
Instructs the gateway to include the card type of the transaction in the message response |
|||
|
|
EchoAVSCheckResult |
B |
– |
No (False) |
Instructs the gateway to include the AVS results for the transaction in the message response |
|||
|
|
EchoCV2CheckResult |
B |
– |
No (False) |
Instructs the gateway to include the CV2 results for the transaction in the message response |
|||
|
|
EchoAmountReceived |
B |
– |
No (False) |
Instructs the gateway to include the amount that was passed to it in the message response |
|||
|
|
EchoExternalData |
B |
– |
No (False) |
Instructs the gateway to include the transaction identifiers of the bank’s external system in the message response |
|||
|
|
DuplicateDelay |
N |
3 |
No (60) |
Sets the amount of time (in seconds) that any orders to the same gateway account with the same OrderID and CardNumber should be rejected |
|||
|
|
AVSOverridePolicy |
– |
4 |
No (As set in MMS) |
Sets an override AVS checking policy for this transaction. (See Appendix 3 for details) |
||
|
|
CV2OverridePolicy |
– |
2 |
No (As set in MMS) |
Sets an override CV2 checking policy for this transaction. (See Appendix 3 for details) |
||
|
|
ThreeDSecureOverridePolicy |
B |
– |
No (False) |
Sets an override for 3D Secure checking for this transaction FALSE = Do not perform 3D Secure enrolment check TRUE = Perform 3D Secure enrolment check |
||
|
|
OverrideCardDetails |
No |
|
||||
|
|
CardName |
A |
100 |
No (See comment) |
The name on the customer’s card. Only submit to override the value for the previous transaction (submit “blank” to not use the value from the previous transaction) |
||
|
|
CardNumber |
N |
20 |
No (See comment) |
The customer’s card number. Only submit to override the value for the previous transaction |
||
|
|
ExpiryDate |
No |
|
||||
|
|
Month |
N |
2 |
No (See comment) |
The month of the expiry date in 2 digit numeric format – e.g. for July, must be submitted as 07. Only submit to override the value for the previous transaction (submit -1 to not use the value from the previous transaction) |
||
|
|
Year |
N |
2 |
No (See comment) |
The year of the expiry date in 2 digit numeric format – e.g. for 2007, must be submitted as 07. Only submit to override the value for the previous transaction (submit -1 to not use the value from the previous transaction) |
||
|
|
CV2 |
N |
4 |
No (See comment) |
The security number (also called CVV or CVV2) printed on the customer’s card – usually the last 3 or 4 digits printed on the signature strip. Only submit to override the value for the previous transaction (submit -1 to not use the value from the previous transaction) |
||
|
|
IssueNumber |
N |
2 |
No (See comment) |
The issue number printed on the customer’s card. Only submit to override the value for the previous transaction (submit -1 to not use the value from the previous transaction) |
||
|
|
CustomerDetails |
No |
|
||||
|
|
|
BillingAddress |
No |
|
|||
|
|
Address1 |
A |
100 |
No (See comment) |
Customer’s billing address line 1. Only pulled forward from previous transaction if NONE of the address fields have been set |
||
|
|
Address2 |
A |
50 |
No (See comment) |
Customer’s billing address line 2. Only pulled forward from previous transaction if NONE of the address fields have been set |
||
|
|
Address3 |
A |
50 |
No (See comment) |
Customer’s billing address line 3. Only pulled forward from previous transaction if NONE of the address fields have been set |
||
|
|
Address4 |
A |
50 |
No (See comment) |
Customer’s billing address line 4. Only pulled forward from previous transaction if NONE of the address fields have been set |
||
|
|
City |
A |
50 |
No (See comment) |
Customer’s billing address city. Only pulled forward from previous transaction if NONE of the address fields have been set |
||
|
|
State |
A |
50 |
No (See comment) |
Customer’s billing address state. Only pulled forward from previous transaction if NONE of the address fields have been set |
||
|
|
PostCode |
A |
50 |
No (See comment) |
Customer’s billing address post code. Only pulled forward from previous transaction if NONE of the address fields have been set |
|||
|
|
CountryCode |
N |
3 |
No (See comment) |
ISO 3166-1 e.g. United Kingdom: 826. Only pulled forward from previous transaction if NONE of the address fields have been set |
|||
|
|
EmailAddress |
E |
100 |
No (See comment) |
The email address of the customer – NOTE: anything passed in here is validated as an email address, so anything passed in must be a valid email address. Pulled forward from previous transaction if not set |
|||
|
|
PhoneNumber |
A |
30 |
No (See comment) |
The customer’s phone number. Pulled forward from previous transaction if not set |
|||
|
|
CustomerIPAddress |
I |
15 |
No |
The IP address of the customer (NOT the IP address of the merchant’s website). This is used to determine the customer’s country of origin. The format is xxx.xxx.xxx.xxx |
|||
|
|
DateOfBirth |
D |
10 |
No |
The date of birth of the customer. Must be in the format YYYY-MM- DD |
|||
|
|
PrimaryAccountDetails |
No |
|
|||||
|
|
Name |
A |
100 |
No |
The name of the primary account holder (used for MCC 6012 accounts only) |
|||
|
|
AccountNumber |
A |
50 |
No |
The account number of the primary account holder (used for MCC 6012 accounts only) |
|||
|
|
DateOfBirth |
D |
10 |
No |
The date of birth of the primary account holder (used for MCC 6012 accounts only) |
|||
|
|
AddressDetails |
No |
|
|||||
|
|
PostCode |
A |
50 |
No |
The post code of the primary account holder (used for MCC 6012 accounts only) |
|||
|
|
ShippingDetails |
No |
|
|||||
|
|
|
ShippingAddress |
No |
|
||||
|
|
Address1 |
A |
100 |
No |
Shipping recipient’s address line 1 |
|||
|
|
Address2 |
A |
50 |
No |
Shipping recipient’s address line 2 |
|||
|
|
Address3 |
A |
50 |
No |
Shipping recipient’s address line 3 |
|
|
Address4 |
A |
50 |
No |
Shipping recipient’s address line 4 |
|
|
City |
A |
50 |
No |
Shipping recipient’s address city |
|
|
State |
A |
50 |
No |
Shipping recipient’s address state |
|
|
PostCode |
A |
50 |
No |
Shipping recipient’s address post code |
|
|
|
CountryCode |
N |
3 |
No |
ISO 3166-1 e.g. United Kingdom: 826 |
|
|
|
Name |
A |
100 |
No |
Shipping recipient’s name |
|
|
|
EmailAddress |
A |
100 |
No |
The email address of the shipping recipient – NOTE: anything passed in here is validated as an email address, so anything passed in must be a valid email address |
|
|
|
PhoneNumber |
A |
30 |
No |
Shipping recipient’s phone number |
|
Things to Note
-
The Amount can be zero (0) if the TransactionType is passed as PREAUTH.
-
If the previous CardDetailsTransaction or CrossReferenceTransaction message was submitted with TransactionType PREAUTH and Amount as Zero (0), the linked CrossReferenceTransaction message will be only allowed to process with TransactionType as SALE.
Response
Below are the details for the response that will be received after sending a CrossReferenceTransaction request.
|
Tag/Attribute Name |
Data Type |
Max Length |
Always Present |
Comments |
||||
|
CrossReferenceTransactionResponse |
Yes |
|
||||||
|
|
CrossReferenceTransactionResult |
Yes |
|
|||||
|
|
AuthorisationAttempted (attribute) |
B |
– |
Yes |
This indicates whether the transaction was actually sent to the acquirer for authorisation, or whether it failed before authorisation |
|||
|
|
StatusCode |
N |
– |
Yes |
This indicates the status of the transaction |
|||
|
|
Message |
A |
– |
Yes |
This gives a more detailed description of the status of the transaction |
|||
|
|
ErrorMessages |
No |
|
|||||
|
|
|
MessageDetail |
Yes |
|
||||
|
|
Detail (multiple) |
A |
256 |
Yes |
If there were multiple error messages(e.g.multipleinput variable validation errors, then they will be detailed here) |
|||
|
|
PreviousTransactionResult |
No |
|
|||||
|
|
StatusCode |
N |
|
Yes |
If the transaction was deemed to be a duplicate transaction, this indicates the status of the previous transaction |
|||
|
|
Message |
A |
|
Yes |
If the transaction was deemed to be a duplicate transaction, this gives a more detailed description of the status of the previous transaction |
|||
|
|
TransactionOutputData |
No |
|
|||||
|
|
CrossReference (attribute) |
A |
25 |
Yes |
This is the unique cross reference for this transaction. If the card has been determined as requiring 3D Secure authentication this must be used as the merchant reference. If the transaction was rejected as a duplicate transaction, this value will hold the cross reference of the previous transaction |
|||
|
|
ExternalCrossReference (attribute) |
A |
– |
No |
If requested in the CrossReferenceTransaction request message, this gives the unique cross reference of the transaction passed back by the bank’s external system to the Payment Gateway. |
|
|
|
ExternalClientReference (attribute) |
A |
– |
No |
If requested in the CrossReferenceTransaction request message, this gives the unique client reference of the transaction passed back by the bank’s external system to the Payment Gateway. |
|
|
|
ExternalTransactionUID (attribute) |
A |
– |
No |
If requested in the CrossReferenceTransaction request message, this gives the unique identifier of the transaction passed back by the bank’s external system to the Payment Gateway. |
|
|
|
AuthCode |
A |
15 |
No |
If the transaction was successful, then the auth code is passed out here |
|
|
|
AddressNumericCheckResult |
– |
– |
No |
If requested in the CrossReferenceTransaction request message, this gives the results of the address numeric check – will be PASSED, FAILED, PARTIAL, NOT_CHECKED or UNKNOWN |
|
|
|
PostCodeCheckResult |
– |
– |
No |
If requested in the CrossReferenceTransaction request message, this gives the results of the post code check – will be PASSED, FAILED, PARTIAL, NOT_CHECKED or UNKNOWN |
|
|
|
CV2CheckResult |
– |
– |
No |
If requested in the CrossReferenceTransaction request message, this gives the results of the CV2check – will be PASSED, FAILED, NOT_CHECKED or UNKNOWN |
|
|
|
CardTypeData |
|
|
|||
|
|
CardType |
A |
– |
Yes |
If requested in the CrossReferenceTransaction request message, this gives the card type for the transaction. (See Appendix 4 for details) |
|
|
|
Issuer |
A |
100 |
No |
The card issuer (if known) |
|
|
|
AmountReceived |
N |
15 |
No |
If requested in the CrossReferenceTransaction request message, this gives the amount that was passed to the gateway via the request message |
||
|
|
ThreeDSecureOutputData |
No |
|
||||
|
|
PaREQ |
A |
– |
Yes |
If the card has been determined as requiring 3D Secure authentication, this gives the base64 encoded payment request that must be passed to the ACS for authentication. This must be sent to the ACS as ‘PaReq’ |
||
|
|
ACSURL |
A |
– |
Yes |
If the card has been determined as requiring 3D Secure authentication, this gives the URL of the ACS server that the PaREQ must be sent to |
||
|
|
GatewayEntryPoints |
Yes |
|
||||
|
|
|
GatewayEntryPoint (multiple) |
Yes |
|
|||
|
|
EntryPointURL (attribute) |
A |
256 |
Yes |
The URL of the active gateway entry point |
||
|
|
Metric (attribute) |
N |
5 |
Yes |
A metric value giving an indication of whether transactionsshouldbesent to this gateway entry point |
||
Things to Note
-
We do not store the CV2 values of any transactions, so they are not available to be pulled forwards from the previous transaction. This means that the unless the CV2 is supplied as part of the OverrideCardDetails in the CrossReferenceTransaction message then the results returned will always be UNKNOWN
-
If requested, the AmountReceived will always echo the amount passed to the gateway regardless of the outcome of the transaction (apart from if the message could not be validated due to content errors)
-
If the address or the post code information is not submitted in the CrossReferenceTransaction message then the AddressNumericCheckResult and the PostCodeCheckResult will be deemed to be UNKNOWN rather than FAILED
-
If this transaction is marked as not a new transaction in the CrossReferenceTransaction message, then the OrderID and OrderDescription will be pulled forward from the previous transaction unless they are present in this message
-
If this transaction is marked as a new transaction in the CrossReferenceTransaction message, then the OrderID and OrderDescription will not be pulled forward from the previous transaction.