BasketXML

On this page:

Overview
Validation
XML Tags
Example

Overview

The basket can be passed as an XML document using BasketXML.

Important: The Basket and BasketXML fields are optional and each conditional on the other. Only one field is processed. For example, when Basket has a value, then BasketXML must be empty.

Advantages

The additional information available enables:

Presenting your customer with more details about the transaction when paying using PayPal.
Presenting your customer with more details about the transaction in MySagePay.
Presenting your customer with more details on the payment page.
Adding a delivery charge and deducting one or more discounts. You can add multiple discounts to the order. The discount is at the order level rather than item level and is a fixed amount discount.

The XML document also improves our fraud screening through ReD including additional details on the:

Recipient
Items
Shipping arrangements

Validation

Data validation rules are described in the following XML Tags table.

Important: We do not validate the totals in the basket. You must ensure:

That all amounts are correct.
That the total of the basket matches the transaction amount sent in the Registration.

XML Tags

The XML tags should follow the order they are listed in the following table.

Note: TRIPs data may be submitted as part of the BasketXML. Refer to the TRIPS section.

Name	Description	Mandatory	Valid Characters	Max Length	Allowed Values
basket	The root element for all other basket elements.	No
agentId	The ID of the seller if using a phone payment.	No	Letters, digits, plus, and spaces	16
item	There can be as many Items are you like in the BasketXML, each holding a different item and recipient. The sum of all TotalGrossAmount in all item elements and the deliveryGrossAmount amount must match the Amount field sent with the transaction.
description	Description of the item.	Yes	Letters including accents, digits, ampersand, comma, apostrophes, forward and back slashes, hyphens, periods, spaces, colons, parentheses, and plus	100
productSku	Item SKU. This is your unique product identifier code.	No	Letters, digits, hyphens, plus, and spaces	12
productCode	Item product code.	No	Letters, digits, hyphens, plus, and spaces	12
quantity	Quantity of the item ordered.	Yes	Digits and periods	12
unitNetAmount	Cost of the item before tax containing minor digits formatted to two decimal places where appropriate. e.g. 5.10 or 3.29. Note: Values such as 3.235 will be rejected. Minimum for no minor unit currencies like JPY is 1. Amounts must be in the UK currency format. The period must be used to indicate the decimal place.	Yes	Digits, periods, and commas	14
unitTaxAmount	Amount of tax on the item containing minor digits formatted to two decimal places where appropriate. e.g. 5.10 or 3.29. Note: Values such as 3.235 will be rejected. Minimum for no minor unit currencies like JPY is 1. Amounts must be in the UK currency format. The period must be used to indicate the decimal place. The comma must only be used to separate groups of thousands.	Yes	Digits, periods, and commas	14
unitGrossAmount	unitNetAmount + unitTaxAmount	Yes	Digits, periods, and commas	14
totalGrossAmount	unitGrossAmount * quantity	Yes	Digits, periods, and commas	14
recipientFName	The first name of the recipient of this item.	No	Letters, digits, apostrophes, forward and back slashes, hyphens, periods, spaces, and parentheses	20
recipientLName	The last name of the recipient of this item.	No	Letters, digits, apostrophes, forward and back slashes, hyphens, periods, spaces, and parentheses	20
recipientMName	The middle initial of the recipient of this item.	No	Letters	1
recipientSal	The salutation of the recipient of this item.	No	Letters	4
recipientEmail	The email of the recipient of this item.	No	RFC532N	45
recipientPhone	The phone number of the recipient of this item.	No	Letters, digits, hyphens, spaces, parentheses, and plus Az 0-9 - SPACE ( ) +	20
recipientAdd1	The first address line of the recipient of this item.	No	Letters, digits, ampers, comma, apostrophes, forward and back slashes, hyphens, periods, spaces, colons, parentheses, plus, and CR/LF	100
recipientAdd2	The second address line of the recipient of this item.	No	Letters, digits, ampers, comma, apostrophes, forward and back slashes, hyphens, periods, spaces, colons, parentheses, plus, and CR/LF	100
recipientCity	The city of the recipient of this item.	No	Letters, digits, ampers, comma, apostrophes, forward and back slashes, hyphens, periods, spaces, colons, parentheses, plus, and CR/LF	40
recipientState	If in the US, the 2 letter code for the state of the recipient of this item.	No	Letters	2
recipientCountry	The 2 letter country code (ISO 3166) of the recipient of this item.	No	ISO3166	2
recipientPostCode	The postcode of the recipient of this item.	No	Letters, digits, hyphens, and spaces	9
itemShipNo	The shipping item number.	No	Letters, digits, hyphens, pluse, and spaces	19
itemGiftMsg	Gift message associated with this item.	No	Letters, digits, plus, and spaces	160
deliveryNetAmount	Cost of delivery before tax containing minor digits formatted to 2 decimal places where appropriate. e.g. 5.10 or 3.29. Values such as 3.235 will be rejected. Minimum for no minor unit currencies like JPY is 1. Amounts must be in the UK currency format. The period must be used to indicate the decimal place. The comma must only be used to separate groups of thousands.	No	Digits, periods, and commas	14
deliveryTaxAmount	Amount of tax on delivery containing minor digits formatted to 2 decimal places where appropriate. e.g. 5.10 or 3.29. Values such as 3.235 will be rejected. Minimum for no minor unit currencies like JPY is 1. Amounts must be in the UK currency format. The period must be used to indicate the decimal place. The comma must only be used to separate groups of thousands.	No	Digits, periods, and commas	14
deliveryGrossAmount	deliveryNetAmount + deliveryTaxAmount	No	Digits, periods, and commas	14
discounts	The root element for all other discount elements.
discount	There can be multiple discount elements.	Yes
fixed	This is the monetary value of the discount. The value sent will be subtracted from the overall total.	Yes	Digits, periods, and commas	14	Zero or greater
description	This is the description of the discount. It will appear on the payment pages, MySagePay, and the PayPal checkout pages, if appropriate.	No	HTML	100
shipId	The ship customer ID.	No	Letters, digits, plus, and spaces	16
shippingMethod	The shipping method used.	No	Uppercase letters	1	C- Low Cost D – Designated by customer I – International M – Military N – Next day/overnight O – Other P – Store pickup T – 2-day service W – 3 day service
shippingFaxNo	Shipping fax number.	No	Letters, digits, hyphens, spaces, parentheses, and plus	20

Example

An example of Basket XML which just contains products and no TRIPs data

Important: The line breaks in the below example are included for readability only. No line breaks are needed.

<basket>
 <agentId>johnsmith</agentId>
 <item>
  <description>Flowers</description>
  <productSku>c0</productSku>
  <productCode>1234567</productCode>
  <quantity>2</quantity>
  <unitNetAmount>24.50</unitNetAmount>
  <unitTaxAmount>00.50</unitTaxAmount>
  <unitGrossAmount>25.00</unitGrossAmount>
  <totalGrossAmount>50.00</totalGrossAmount>
  <recipientFName>firstname</recipientFName>
  <recipientLName>lastname</recipientLName>
  <recipientMName>M</recipientMName>
  <recipientSal>MR</recipientSal>
  <recipientEmail>firstname.lastname @test.com</recipientEmail>
  <recipientPhone>1234567890</recipientPhone>
  <recipientAdd1>add1</recipientAdd1>
  <recipientAdd2>add2</recipientAdd2>
  <recipientCity>city</recipientCity>
  <recipientState>CA</recipientState>
  <recipientCountry>GB</recipientCountry>
  <recipientPostCode>ha412t</recipientPostCode>
  <itemShipNo>1123</itemShipNo>
  <itemGiftMsg>Happy Birthday</itemGiftMsg>
 </item>
 <item>
  <description>chocolates</description>
  <productSku>c1</productSku>
  <productCode>1234567</productCode>
  <quantity>1</quantity>
  <unitNetAmount>24.99</unitNetAmount>
  <unitTaxAmount>00.99</unitTaxAmount>
  <unitGrossAmount>25.98</unitGrossAmount>
  <totalGrossAmount>25.98</totalGrossAmount>
  <recipientFName>firstname</recipientFName>
  <recipientLName>lastname</recipientLName>
  <recipientMName>M</recipientMName>
  <recipientSal>MR</recipientSal>
  <recipientEmail> firstname.lastname @test.com</recipientEmail>
  <recipientPhone>1234567890</recipientPhone>
  <recipientAdd1>add1</recipientAdd1>
  <recipientAdd2>add2</recipientAdd2>
  <recipientCity>city</recipientCity>
  <recipientState>CA</recipientState>
  <recipientCountry>GB</recipientCountry>
  <recipientPostCode>ha412t</recipientPostCode>
  <itemShipNo>1123</itemShipNo>
  <itemGiftMsg>Congrats</itemGiftMsg>
 </item>
 <deliveryNetAmount>4.02</deliveryNetAmount>
 <deliveryTaxAmount>20.00</deliveryTaxAmount>
 <deliveryGrossAmount>24.02</deliveryGrossAmount>
 <discounts>
  <discount>
   <fixed>5</fixed>
   <description>Save 5 pounds</description>
  </discount>
  <discount>
   <fixed>1</fixed>
   <description>Spend 5 pounds and save 1 pound</description>
  </discount>
 </discounts>
 <shipId>SHIP00002</shipId>
 <shippingMethod>N</shippingMethod>
 <shippingFaxNo>1234567890</shippingFaxNo>
</basket>