Transaction Cloning
If a new transaction request is received with the Cross Reference (xref) of an existing transaction, then the values of certain fields in the existing transaction will be used to initialise the new transaction where new values have not been provided in the new request. This copying of fields from a base transaction is termed ‘transaction cloning’, and the copied-over value is termed the ‘cloned value’.
The Cloned Fields section shows all the fields whose values can be copied over from the existing transaction. To allow for easy addition of future fields, the fields are grouped into logical groupings and each group is given a name, given in brackets after the group title.
Certain groups of fields, such as address fields, can only be copied as a whole entity and any new value provided in the new request will prevent the whole group from being copied from the existing transaction. These fields are marked with an asterisk after the field name. This is explained in the Compound Groups section.
By default, the values of all the fields listed in the Cloned Fields section are copied from the existing transaction where appropriate. However, you can control exactly which fields are copied using the cloneFields field in the new request. The value of cloneFields should be a comma separated list of field names or group names that should be copied over. Alternatively, if you wish to specify a list of fields not to copy, then prefix the list with a single exclamation mark (!).
| Field Name | Mandatory? | Description |
|---|---|---|
| cloneFields | N | Comma separated list of field names or group names whose values should be cloned. |
Examples
To copy over only the value of customerName and any values for the fields in the customerAddressFields group:
cloneFields=”customerName, customerAddressFields”
To copy over the values of all supported fields apart from the value of customerName and merchantName:
cloneFields=”!customerName,merchantName”
Cloned Fields
Transaction fields currently cloned are as follows:
Order Details Fields (orderFields)
o type
o countryCode
o currencyCode
o amount
o grossAmount
o netAmount
o taxRate
o taxAmount
o taxReason
o discountAmount
o discountReason
o handlingAmount
o insuranceAmount
o surchargeAmount
Order Reference Fields (orderRefFields)
o transactionUnique
o orderRef
o orderDate
Card Fields (cardFields)
o paymentMethod
o paymentToken
o cardToken
o cardNumber
o cardExpiryDate*
o cardExpiryMonth*
o cardExpiryYear*
o cardStartDate*
o cardStartMonth*
o cardStartYear*
o cardIssueNumber
Cardholder Fields (cardholderFields)
o customerName
o customerAddress
o customerPostcode
o customerEmail
o customerPhone
Purchase Fields (purchaseFields)
o items
Statement Narrative Fields (narrativeFields)
o statementNarrative1
o statementNarrative2
AVS/CV2 Fields (avscv2Fields)
o avscv2Required
o cv2CheckPref
o addressCheckPref
o postcodeCheckPref
o customerAddress
o customerPostcode
Risk Check Fields (riskCheckFields)
o riskCheckRequired
o riskCheckPref
o riskCheckOptions
3-D Secure Fields (threedsFields)
o threeDSRequired
o threeDSPolicy
o threeDSCheckPref
o threeDSRedirectURL
o threeDSOptions
o scaExemption
Merchant Email Notification Fields (notifyFields)
o notifyEmailRequired
o notifyEmail
Customer Receipt Fields (cReceiptFields)
o customerReceiptsRequired
o customerEmail
Merchant Information Fields (merchantFields)
o merchantName
o merchantCompany
o merchantAddress*
o merchantTown*
o merchantCounty*
o merchantPostcode*
o merchantCountryCode*
o merchantPhone
o merchantMobile
o merchantFax
o merchantEmail
o merchantWebsite
o merchantData
o merchantOrderRef
o merchantCustomerRef
o merchantTaxRef
o merchantOriginalOrderRef
o merchantCategoryCode
o merchantAccountNo
o merchantType
Customer Information Fields (customerFields)
o customerName
o customerCompany
o customerAddress*
o customerTown*
o customerCounty*
o customerPostcode*
o customerCountryCode*
o customerPhone
o customerMobile
o customerFax
o customerEmail
o customerDateOfBirth
o customerOrderRef
o customerMerchantRef
o customerTaxRef
Supplier Information Fields (supplierFields)
o supplierName
o supplierCompany
o supplierAddress*
o supplierTown*
o supplierCounty*
o supplierPostcode*
o supplierCountryCode*
o supplierPhone
o supplierMobile
o supplierFax
o supplierEmail
o supplierOrderRef
o supplierAccountNo
Receiver Information Fields (receiverFields)
o receiverName
o receiverCompany
o receiverAddress*
o receiverTown*
o receiverCounty*
o receiverPostcode*
o receiverCountryCode*
o receiverPhone
o receiverMobile
o receiverFax
o receiverEmail
o receiverAccountNo
o receiverDateOfBirth
Delivery Information Fields (deliveryFields)
o deliveryName
o deliveryCompany
o deliveryAddress*
o deliveryTown*
o deliveryCounty*
o deliveryPostcode*
o deliveryCountryCode*
o deliveryPhone
o deliveryMobile
o deliveryFax
o deliveryEmail
Shipping Information Fields (shippingFields)
o shippingMethod
o shippingTrackingRef
o shippingAmount
o shippingGrossAmount
o shippingNetAmount
o shippingTaxRate
o shippingTaxAmount
o shippingTaxReason
o shippingDiscountAmount
o shippingDiscountReason
MCC 6012 Additional Authorisation Data (mcc6012Fields)
o receiverName
o receiverPostcode
o receiverAccountNo
o receiverDateOfBirth
Payment Facilitator Data (facilitatorFields)
o subMerchantID
o facilitatorID
o facilitatorName
o isoID
Surcharge Data (surchargeFields)
o surchargeRequired
o surchargeAmount
o surchargeRules
Device Data (deviceFields)
o deviceType
o deviceChannel
o deviceIdentity
o deviceTimeZone
o deviceCapabilities
o deviceAcceptContent
o deviceAcceptCharset
o deviceAcceptEncoding
o deviceAcceptLanguage
o deviceScreenResolution
o deviceOperatingSystem
Acquirer Data (acquirerFields)
o acquirerOptions
[1] 3-D Secure fields are only cloned if both the existing and new transaction support 3-D Secure.
[2] Payment facilitator fields are only cloned if the existing transaction uses the same merchantID as the new transaction.
Cloned Groups
To allow for easy future addition of new fields, the existing fields are grouped into logic groupings. Each group is given a name (as shown in brackets after the group title). It is recommended that this group name be used in any cloneFields value instead of listing all the fields separately.
Compound Groups
To help maintain transaction integrity, certain groups of fields, such as address fields, can only be copied as a whole entity and any new value provided in the new request will prevent the whole group from being copied from the existing transaction.
These compound fields are marked with an asterisk in the Cloned Fields section and can be referred to in cloneFields as logical groups using the following group names; merchantAddressFields,`` ``customerAddressFields,`` ``deliveryAddressFields,`` ``supplierAddressFields``and``receiverAddressFields.
Line-Item Data
Any line-item data (items) is copied over in its entirety and there is no way to merge the line item from an existing transaction with any sent in a new transaction.
Amount Consistency
The Gateway does not validate that the various sub-amount fields, such as netAmount, grossAmount, all add up to the actual requested amount. Therefore, these fields are currently not treated as a compound group.
If a new amount value is passed that is different from the value in the existing transaction, then the following fields should also be passed so that they tally with the new amount.
· grossAmount
· netAmount
· taxRate
· discountAmount