BasketXML

On this page:

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:

  1. Presenting your customer with more details about the transaction when paying using PayPal.
  2. Presenting your customer with more details about the transaction in MySagePay.
  3. Presenting your customer with more details on the payment page.
  4. 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.

BasketXML tags

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>