On this page:
Overview
The basket can be passed as an XML document using BasketXML.
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
<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>