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 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.
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:
|
Yes |
Digits, periods |
14 |
|
unitTaxAmount |
Amount of tax on the item. Validation:
|
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 |
Digits, periods |
14 |
|
deliveryTaxAmount |
Amount of tax on delivery. Validation:
|
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:
|
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:
|
No |
Uppercase letters |
1 |
|
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
<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>