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

Node/Element

Description

Mandatory

Format and Valid Characters

Max Length

Allowed Values

basket

The root element for all other basket elements.

No

Node

 

 

agentId

The ID of the seller when using a phone payment.

No

Letters, digits, plus, and spaces

   

 

16 

 

item

Add as many items as you want in the BasketXML. Each holds 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

 

XML container element

 

 

description

Item description

Yes

Letters including accents, digits, ampersand, comma, apostrophes, forward and back slashes, hyphens, periods, spaces, colons, parentheses, and plus
            

100 

 

productSku

Item SKU, 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. Validation:

  • No more than 2 decimal places. For example, 5.67.

  • 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 

 

unitTaxAmount

Amount of tax on the item. Validation:

  • No more than 2 decimal places. For example, 5.67.

  • 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 multiplied by quantity

Yes

Digits, periods, and commas
  

14 

 

recipientFName

The item recipient's first name.

No

Letters, digits, apostrophes, forward and back slashes, hyphens, periods, spaces, and parentheses

       

20 

 

recipientLName

The item recipient's last name.

No

Letters, digits, apostrophes, forward and back slashes, hyphens, periods, spaces, and parentheses
       

20 

 

recipientMName

The item recipient's middle initial.

No

Letters

 

recipientSal

The item recipient's salutation.

No

Letters

 

recipientEmail

The item recipient's email address.

No

RFC532N

45 

 

recipientPhone

The item recipient's phone number.

No

Letters, digits, hyphens, spaces, parentheses, and plus

Az 0-9 -  SPACE ( ) +
     

 

 

20 

 

recipientAdd1

The item recipient's first line of their postal address.

No

Letters, digits, ampers, comma, apostrophes, forward and back slashes, hyphens, periods, spaces, colons, parentheses, plus, and CR/LF
            

100 

 

recipientAdd2

The item recipient's second line of their postal address.

No

Letters, digits, ampers, comma, apostrophes, forward and back slashes, hyphens, periods, spaces, colons, parentheses, plus, and CR/LF
            

100 

 

recipientCity

The item recipient's city.

No

Letters, digits, ampers, comma, apostrophes, forward and back slashes, hyphens, periods, spaces, colons, parentheses, plus, and CR/LF
            

40 

 

recipientState

When the item recipient is in the US, the 2 letter code for the state.

No

Valid 2-letter US States

US

 

recipientCountry

The item recipient's ISO 3166 (2 letter) country code.

No

ISO3166

 

 

recipientPostCode

The item recipient's postcode.

No

Letters, digits, hyphens, and spaces

   

 

itemShipNo

The item shipping number.

No

Letters, digits, hyphens, spaces, and plus

    

19 

 

itemGiftMsg

Any gift message associated with this item.

No

Letters, digits, plus, and spaces

   

160 

 

deliveryNetAmount

Cost of delivery before tax. Validation:

  • No more than 2 decimal places. For example, 5.67.

  • 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. Validation:

  • No more than 2 decimal places. For example, 5.67.

  • 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 discount elements.

No

 

 

 

discount

You can use one or more discount elements.

Yes

 

 

 

fixed

This is the monetary value of the discount. The value sent will be subtracted from the overall total. Validation:

  • No more than 2 decimal places. For example, 5.67.

  • 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.

  • The value must be 0 or greater.

Yes

Digits, periods, and commas
  

14 

 

description

The discount description. This will be presented on our payment pages, on MySagePay, and on a PayPal checkout page.

No

HTML

100 

 

shipId

The ship customer ID.

No

Letters, digits, plus, and spaces

   

16 

 

shippingMethod

The shipping method used:

  • 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

No

Uppercase letters

  • C

  • D

  • I

  • M

  • N

  • O

  • P

  • T

  • W

shippingFaxNo

Shipping fax number

No

Letters, digits, hyphens, spaces, parentheses, and plus
     

 

20 chars

 

 

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>