Skip to main content

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 NameMandatory?Description
cloneFieldsNComma 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