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

**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.	Yes	Digits, periods	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.	Yes	Digits, periods	14
unitGrossAmount	unitNetAmount + unitTaxAmount	Yes	Digits, periods	14
totalGrossAmount	unitGrossAmount multiplied by quantity	Yes	Digits, periods	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	1
recipientSal	The item recipient's salutation.	No	Letters	4
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	2
recipientCountry	The item recipient's ISO 3166 (2 letter) country code.	No	ISO3166	2
recipientPostCode	The item recipient's postcode.	No	Letters, digits, hyphens, and spaces	9
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.	No	Digits, periods	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.	No	Digits, periods	14
deliveryGrossAmount	deliveryNetAmount + deliveryTaxAmount	No	Digits, periods	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 value must be 0 or greater.	Yes	Digits, periods	14
description	The discount description. This will be presented on our payment pages, on MyOpayo, 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	1	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>