Skip to main content

Basket Details

TransactDirect supports flexible basket details through the Payments API and Checkout Page.

The Basket should be construted using the JSON format described in this article and then Base64 encoded and sent along with the payment request in the Basket field.

Basket Format​

The Basket JSON object is made up of the following elements

Field NameDescriptionReq'd
taxTypeIndicates the tax type for all amounts in this basket. See Tax Types. Defaults to Inclusive if not set.O
itemsA list of all items in the basket. See Item Object.M
discountsA list of any discounts applied to the basket. See Discount Object.O
taxesA list of transaction level tax summaries applied to the basket. See Tax Object.O
deliveryDelivery details for this basket. See Delivery Object.O
invoiceAdditional information related to the invoice for this basket. See InvoiceO

Tax Types​

Tax TypeDescription
InclusiveAll line item, discount, and delivery amounts must be supplied inclusive of all taxes.
Additional tax details are recommended but not required.
ExclusiveAll line item, discount, and delivery amounts must be supplied exclusive of any taxes.
Tax code, tax rate, and tax amount are required.
ExemptOrder is tax exempt. No additional tax details are expected for this basket.

Notes​

  • When not specified taxType defaults to Inclusive.
  • Taxes can be supplied at either:
    • Line level on each individual item, discount, and delivery.
    • Transaction level tax totals in the taxes collection.
warning

Tax details must only be supplied once, at either line level OR summarised at transaction level.

Item Object​

Field NameDescriptionReq'dType
descriptionThe product description for this item.MA
quantityThe quantity of this item on this order line.MN
unitPriceThe unit price for this product in major currency. e.g. 3.99MN
unitOfMeasureThe unit of measure for this product. e.g. litres, metres.OA
totalThe total price for this order line. If not supplied it will be calculated automatically.ON
taxCodeThe tax code applied to this line.C*A
taxRateThe tax rate applied to this line.C*A
taxAmountThe tax amount applied to this line.C*A
skuThe stock code for this product.OA
commodityCodeThe 4-digit standard commodity code for this product. See Commodity CodesO*A4

Notes​

  • When taxType is set to Inclusive all items must be supplied with their unitPrice and total inclusive of all taxes.
  • When taxType is set to Exclusive all items must be supplied with their unitPrice and total exclusive of any taxes.
  • When tax details are included for a line item taxCode, taxRate, and taxAmount all become mandatory.
  • commodityCode is typically only required for advanced basket integrations. e.g. LTI.

Discount Object​

Field NameDescriptionReq'dType
codeThe discount code.OA
descriptionThe description for this discount.MA
rateThe rate of discount applied. e.g. 5.0ON
amountThe amount of discount in major currency. e.g. 1.99MN
taxCodeThe tax code applied to this discount.C*A
taxRateThe tax rate applied to this discount.C*A
taxAmountThe tax amount applied to this discount.C*A

Notes​

  • When taxType is set to Inclusive discounts must be supplied with their amount inclusive of all taxes.
  • When taxType is set to Exclusive discounts must be supplied with their amount exclusive of any taxes.
  • When tax details are included for a line item taxCode, taxRate, and taxAmount all become mandatory.

Tax Object​

Field NameDescriptionReq'dType
codeThe tax code.MA
descriptionDescription of this tax item.OA
rateThe rate at which this tax item is applied.MN
amountThe amount of tax applied in major currency. e.g. 2.50MN

Notes​

  • When taxType is set to Inclusive all basket amounts must be supplied inclusive of the tax items specified here.
  • When taxType is set to Exclusive all basket amounts must be supplied exclusive of the tax items specified here.
  • If taxes are supplied at transaction level in the taxes collection the individual taxCode, taxRate, and taxAmount fields should not be populated on individual items.

Delivery Object​

Field NameDescriptionReq'dType
carrierThe carrier used for delivery.MA
amountThe cost for this delivery in major currency. e.g. 2.50MN
taxCodeThe tax code applied to this delivery cost.C*A
taxRateThe tax rate applied to this delivery cost.C*A
taxAmountThe tax amount applied to this delivery cost.C*A

Notes​

  • When taxType is set to Inclusive delivery details must be supplied with the amount inclusive of all taxes.
  • When taxType is set to Exclusive delivery details must be supplied with the amount exclusive of any taxes.
  • When tax details are included for a line item taxCode, taxRate, and taxAmount all become mandatory.

Invoice Object​

Field NameDescriptionReq'dType
invoiceNumberThe invoice number.OA
orderNumberThe order number.OA
addresseeThe addressee name.OA
taxRegistrationNumberThe addressee's tax registration number.OA
isTaxExemptIndicates if this invoice is for a tax exempt organisation (e.g. Government.). true or false (default)OB
dueDateThe due date of this invoice.OISO 8601
issueDateThe issue date of this invoice.OISO 8601
orderDateThe order date for this basket of goods.OISO 8601

Request Samples​

Basket in JSON format​

Examples below for different tax types.

This example shows a simple basket with all tax inclusive amounts but no specific tax details

Basket total value £13.99

{
  "taxType": "inclusive",
  "items": [
    {
      "sku": "AP001",
      "commodityCode": "3200",
      "description": "White Matt Paint",
      "quantity": 1,
      "unitPrice": 12.99,
      "unitOfMeasure": "5 litre pot",
      "total": 12.99
    }
  ],
  "discounts": [
    {
      "code": "PAINT",
      "description": "Paint Promo",
      "amount": 0.99
    }
  ],
  "delivery": {
    "carrier": "Royal Mail Tracked 48\u2122",
    "amount": 1.99
  },
  "invoice": {
    "invoiceNumber": "JONES123123",
    "orderNumber": "MSPS2138",
    "addressee": "Mr Smith's Paint Shop",
    "taxRegistrationNumber": "GB12345678",
    "isTaxExempt": false,
    "dueDate": "2025-04-01T12:00:00",
    "issueDate": "2025-03-01T12:00:00",
    "orderDate": "2025-03-01T12:00:00"
  }
}

Base64​

eyJ0YXhUeXBlIjoiaW5jbHVzaXZlIiwiaXRlbXMiOlt7InNrdSI6IkFQMDAxIiwiY29tbW9kaXR5Q29
kZSI6IjMyMDAiLCJkZXNjcmlwdGlvbiI6IldoaXRlIE1hdHQgUGFpbnQiLCJxdWFudGl0eSI6MSwidW
5pdFByaWNlIjoxMi45OSwidW5pdE9mTWVhc3VyZSI6IjUgbGl0cmUgcG90IiwidG90YWwiOjEyLjk5f
V0sImRpc2NvdW50cyI6W3siY29kZSI6IlBBSU5UIiwiZGVzY3JpcHRpb24iOiJQYWludCBQcm9tbyIs
ImFtb3VudCI6MC45OX1dLCJkZWxpdmVyeSI6eyJjYXJyaWVyIjoiUm95YWwgTWFpbCBUcmFja2VkIDQ
4PyIsImFtb3VudCI6MS45OX0sImludm9pY2UiOnsiaW52b2ljZU51bWJlciI6IkpPTkVTMTIzMTIzIi
wib3JkZXJOdW1iZXIiOiJNU1BTMjEzOCIsImFkZHJlc3NlZSI6Ik1yIFNtaXRoJ3MgUGFpbnQgU2hvc
CIsInRheFJlZ2lzdHJhdGlvbk51bWJlciI6IkdCMTIzNDU2NzgiLCJpc1RheEV4ZW1wdCI6ZmFsc2Us
ImR1ZURhdGUiOiIyMDI1LTA0LTAxVDEyOjAwOjAwIiwiaXNzdWVEYXRlIjoiMjAyNS0wMy0wMVQxMjo
wMDowMCIsIm9yZGVyRGF0ZSI6IjIwMjUtMDMtMDFUMTI6MDA6MDAifX0=

Character Encoding​

To ensure correct display on the Checkout Page, JSON requires that some characters are encoded. Including, but not limited to, those below.

CharacterDescriptionEncoding
£Pound symbol\u00A3
™Trademark symbol\u2122

Commodity Codes​

Standard commodity codes. Typically only required for advanced Basket integrations.

CodeDescriptionNotes
0100LIVE ANIMALS
0200MEAT/MEAT PRODUCTS
0300FISH/SEAFOOD PRODUCTS
0400DAIRY PRODUCE
0600PLANTS, SHRUBS AND TREES
0700VEGETABLES AND VEGETABLE PRODUCTS
0800FRUIT AND FRUIT PRODUCTS
0900BEVERAGES - NON-ALCOHOLIC
1200ANIMAL FEEDING STUFFS
2200ALCOHOLIC BEVERAGES
2260PUBLISHING SERVICES
2261PRINTING SERVICES
2400TOBACCO/TOBACCO PRODUCTS
2500BUILDING AGGREGATES
2700SOLID FUEL; HEATING/ INDUSTRIAL/ AGRICULTURAL OILS
2701PETROL/DIESEL - ROAD FUELUK Only
2702LUBRICATING OILS
2703DIESEL/PETROL – ROAD FUELROI Only
2800CHEMICALS/ACIDS
3000FIRST AID PRODUCTS
3100AGRICULTURAL FERTILISERS
3200PAINTS/VARNISHES
3400CLEANING PRODUCTS
3600INDUSTRIAL EXPLOSIVES
3700PHOTOGRAPHIC FILM PRODUCTS
3760WASTE DISPOSAL SERVICES
3800INSECTICIDES/FUNGICIDES/DISINFECTANTS
4000RUBBER PRODUCTS
4001TYRES - MOTOR VEHICLES
4200LEATHER CASES AND BAGS
4560CONSTRUCTION/DEMOLITION SERVICES
4561ROOFING SERVICES
4562ELECTRICAL CONTRACTING
4563PLUMBING, HEATING AND DRAINAGE SERVICES
4564PLASTERING SERVICES
4565JOINERY SERVICES
4566PAINTING/GLAZING SERVICES
4700WOOD, TIMBER PRODUCTS, PULP AND PAPER PRODUCTS
4800OFFICE STATIONERY
4801NEWSPRINT
4802WALLPAPER
4900BOOKS: PRINTED MATERIAL
5060MOTOR VEHICLE REPAIR/MAINTENANCE SERVICES
5560HOTEL/RESTAURANT SERVICES
5561CATERING SERVICES
5600ROPE, CABLE, NETTING
5700CARPETS/FLOOR COVERINGS
6060PASSENGER TRANSPORT
6061FREIGHT TRANSPORT SERVICESVisa Only
6200CLOTHING
6300PACKING MATERIALS/SACKS/BAGS
6360STORAGE/WAREHOUSING SERVICES
6361TRAVEL AGENCY SERVICES
6362FREIGHT / CARRIAGE CHARGES (NON-COURIER / DELIVERY SERVICE PROVIDERS)Visa Only
6400FOOTWEAR
6460COURIER SERVICES (COURIER / DELIVERY SERVICES PROVIDERS)
6461TELECOMMUNICATIONS SERVICES
6500HEADGEAR
6560FINANCIAL SERVICES (NON-INSURANCE)
6561EQUIPMENT LEASING SERVICES
6562CAR LEASING SERVICES: QUALIFYING CARSUK Only
6563COMMERCIAL VEHICLE LEASING SERVICES
6564FACTORING SERVICES
6565CAR LEASING SERVICES: NON - QUALIFYING CARSUK Only
6600UMBRELLAS AND WALKING STICKS
6660INSURANCE SERVICES - GENERAL
6760FINANCIAL ADMINISTRATION SERVICES
6761PENSION ADVISORY/ADMINISTRATION SERVICES
6900BUILDING BRICKS/TILES/STONES
6901SINKS, BATHS, WASHBASINS; OTHER PLUMBING/HEATING PRODUCTS
7000GLASSWARE
7060PROPERTY RENTALS
7061ESTATE AGENCY SERVICES
7062PROPERTY MANAGEMENT SERVICES
7100INDUSTRIAL METALS (BASE/PROCESSED)
7160CAR HIRE SERVICES: QUALIFYING CARS
7161RENTAL OF AGRICULTURAL MACHINERY
7162RENTAL OF CONSTRUCTION EQUIPMENT
7163COMPUTER/OFFICE MACHINE RENTAL
7164RENTAL OF SPORTS/RECREATIONAL EQUIPMENT
7260COMPUTER CONSULTANCY SERVICES
7261DATA PROCESSING SERVICES
7262MAINTENANCE/REPAIR - OFFICE EQUIPMENT
7300BARBED WIRE/FENCING
7460LEGAL SERVICES - LAWYERS/SOLICITORS
7461ACCOUNTING/TAX CONSULTANCY SERVICES
7462MARKET RESEARCH SERVICES
7463MANAGEMENT CONSULTANCY SERVICES
7464ADVERTISING AND MARKETING SERVICES
7465TECHNICAL ANALYSIS SERVICES
7466EMPLOYMENT BUREAU SERVICES
7467SITE SECURITY SERVICES
7468CLEANING SERVICES
7469PHOTOGRAPHIC SERVICES
7470PACKING SERVICES
7471SECRETARIAL/TRANSLATION SERVICES
7472OTHER BUSINESS SERVICES
7560STATUTORY CHARGES/LICENSES
8060DRIVING TUITION SERVICES
8061EMPLOYEE TRAINING
8200HAND TOOLS
8201MACHINE TOOLS
8202MACHINE/HAND TOOL PARTS
8300PADLOCKS, LOCKS, KEYS. SAFES, STRONG BOXES, OTHER IRONMONGERY PRODUCTS
8400INDUSTRIAL MECHANICAL APPLIANCES/PARTS
8401INDUSTRIAL ENGINES/PLANT: PARTS
8402INDUSTRIAL PLANT/EQUIPMENT
8403KITCHEN EQUIPMENT
8404FIRE EXTINGUISHERS
8405COMPUTER HARDWARE
8406COMPUTER SOFTWARE
8407VENDING MACHINES
8500GENERATORS/ELECTRIC MOTORS
8501TELEPHONES
8502RECORD/CASSETTE/CD PLAYERS
8503TAPE RECORDERS/ANSWERING MACHINES
8504VIDEO RECORDERS
8505RADIOS
8506TELEVISION SETS
8507BURGLAR & FIRE ALARMS
8508ELECTRICAL SWITCHES/FUSES/PLUGS/CIRCUITS
8509ELECTRIC LAMPS
8560MEDICAL SERVICES
8600RAILWAY LOCOMOTIVE PARTS
8700MOTOR CARS
8701COMMERCIAL MOTOR VEHICLES
8702SPECIAL PURPOSE VEHICLES
8703MOTOR VEHICLE PARTS (EXCLUDING TYRES)
8704MOTORCYCLES/SIDECARS
8705BICYCLES/TRICYCLES
8706TRAILERS/TRAILER PARTS
8800AIRCRAFT PARTS
9000BINOCULARS/TELESCOPES
9001CAMERAS/FLASHES
9002PHOTOCOPIERS
9003MICROSCOPES
9004MEASURING EQUIPMENT
9100CLOCKS, WATCHES & PARTS
9160MEMBERSHIP SUBSCRIPTIONS
9200MUSICAL INSTRUMENTS
9260MEDIA/NEWS AGENCY SERVICES
9261LIBRARY/ARCHIVING SERVICES
9360EMPLOYEE WELFARE SERVICES
9400OFFICE FURNITURE
9500TOYS, GAMES AND MODELS
9999VAT: INSURANCE REPAIRS