alt

Important information

Please be advised that there will be a scheduled downtime across our API network on November 05 and November 07, 2024. For more information, visit our platform status portal.:
- Scheduled maintenance on November 5, 2024
- Scheduled maintenance on November 7, 2024

Unzer

[Deprecated] Manage baskets (v1)

Submit product information within your payment.

icon info
  • Basket v1 is now deprecated.
  • Update to basket v2 to get the latest features of the basket.
  • For Unzer Invoice, basket v2 is required.

Overview

A basket is a collection of product information for all the items of a transaction. It is not a mandatory resource, but some payment methods require this information for risk analysis, such as Direct Debit Secured and Unzer Invoice.

How it works

  1. In your ecommerce site, the customer selects the items that they want to purchase. You send a POST request to create the basket resource. A unique basket ID is created.
  2. This basketId can now be used when the payment is initiated.

Once a basket has been created, it cannot be replaced or deleted. If you haven’t assigned a basket to a transaction yet, you can update it. This means you cannot change specific attributes, but you can provide new basket details. For example, you can add more items, remove items, but cannot update the basket ID.

Creating a basket

To create a new basket resource, send a POST request with your desired contents in the JSON format.

icon info
A basket resource can be created or updated using your public or private key. Fetching a basket is only possible with your private key (check the API reference for more information).

POST https://api.unzer.com/v1/baskets
Body:
{
  "amountTotal": 200.00,
  "amountTotalDiscount": 0.00,
  "amountTotalVat": 0.00,
  "currencyCode": "EUR",
  "orderId": "136d24be-12b0",
  "note": "merchantwebshop.com basket for masterpass",
  "basketItems": [
    {
      "basketItemReferenceId": "xxxxx",
      "unit":"Pc.",
      "quantity": 2,
      "amountDiscount": 100.00,
      "vat": 0,
      "amountGross": 200.00,
      "amountVat": 0,
      "amountPerUnit": 100.00,
      "amountNet": 200.00,
      "title": "Macbook pro",
      "type": "goods"
      "subTitle": "This is brand new Mid 2019 version", //optional
      "imageUrl": "https://www.unzer.com/typo3conf/ext/Unzer_site/Resources/Public/Images/Unzer-Logo_weiss.svg" //optional, is used in payment page 
    }
  ]
}
icon info
Order ID
  • Although it’s possible to use any character combination for the orderId, we recommend using the same orderId as for payments (created like types/authorize, types/charge).
  • The order ID must be unique.

The response contains a basket ID.

{
    "id":"s-bsk-1"
}

Fetching or reviewing a basket

To review a specific basket resource, use your private key and send a GET request with the basket ID that you want to review.

GET https://api.unzer.com/v1/baskets/s-bsk-1

Your response should look similar to this:

{
  "id": "s-bsk-1",
  "amountTotal": 200.00,
  "amountTotalDiscount": 0.00,
  "amountTotalVat": 0.00,
  "currencyCode": "EUR",
  "orderId": "136d24be-12b0",
  "note": "merchantwebshop.com basket for masterpass",
  "basketItems": [
    {
      "basketItemReferenceId": "xxxxx",
      "unit":"Pc.",
      "quantity": 2,
      "amountDiscount": 100.00,
      "vat": 0,
      "amountGross": 200.00,
      "amountVat": 0,
      "amountPerUnit": 100.00,
      "amountNet": 200.00,
      "title": "Macbook pro",
      "type": "goods"
    }
  ]
}

Adding a basket to your transaction

Here you can see how simple it is to add a basket to a transaction, in our example a charge request. You just have to add the basket ID to your resources parameter list as shown in the following example:

POST https://api.unzer.com/v1/payments/charges
{
  "amount": 100.00,
  "currency": "EUR",
  "returnUrl" "http://www.unzer.com",
  "resources": [
    {
      "typeId": "s-crd-fm7tifzkqewy",
      "basketId": "s-bsk-1"
    }
  ]
}

Updating a basket

In some cases, it might be necessary to change an already created basket, for example if the user added a voucher or shipping fees changed.

In that case, you have to change the whole content of the basket - it’s not possible to change individual parts of a basket resource. Either copy the contents of the old one, alter them and submit it using a PUT request , or create a new request.

Changing baskets on payments

Changing a basket that was used in a payment (charge or authorize) is not possible. As soon as you create a payment with a particular basket, the basket is associated to it.

If you want to update (basically override) a basket, execute a PUT request on the correct basket ID, like so:

UnzerAPI - Updating a basket

PUT https://api.unzer.com/v1/baskets/s-bsk-1

Body:
{
  "id": "s-bsk-1",
  "amountTotal": 100.00,
  "amountTotalDiscount": 0.00,
  "amountTotalVat": 0.00,
  "currencyCode": "EUR",
  "orderId": "136d24be-12b0",
  "note": "merchantwebshop.com basket for masterpass",
  "basketItems": [
    {
      "basketItemReferenceId": "xxxxx",
      "unit":"Pc.",
      "quantity": 1,
      "amountDiscount": 100.00,
      "vat": 0,
      "amountGross": 100.00,
      "amountVat": 0,
      "amountPerUnit": 100.00,
      "amountNet": 100.00,
      "title": "Macbook pro",
      "type": "goods"
    }
  ]
}

Check the API reference for more information and specific examples.

Error Codes for a basket

The following list describes some basket-specific error codes:

Error CodeDescription
300.100.200no basket ID given
300.100.201no basket items given
300.100.202no basket given
300.100.300no valid basket ID given
300.200.400basket parse error
300.200.401basket request parse error
300.200.500basket processing error occurred
300.200.600unsupported media type

References

ParameterTypeDescription
amountTotalGross

(required)
floatThe total basket value (including VAT) of all basket items after deducting all discounts.
amountTotal

(deprecated)
floatTotal amount of the basket in the unit of the currency. This is now deprecated.
amountTotalDiscountfloatTotal discount amount of the whole basket in unit of the currency.
amountTotalVatfloatTotal VAT amount of the basket in the unit of the currency.
currencyCode

(required)
string (3)Currency code in ISO_4217 format
orderId

(required)
string (255)A basket or shop reference ID sent from the shop backend.
Recommended: paymentId
notestring (3900)A note sent from the shop backend
basketItems

(required)
ObjectSet of basket items
basketItems.basketItemReferenceIdstring (255)Unique basket item reference ID (within the basket)
basketItems.unitstring (255)Unit description of the item, such as “Pc”.
basketItems.quantity

(required)
numberQuantity of the basket item
basketItems.amountDiscountfloatDiscount amount for the basket item
basketItems.vatnumber(0-100)VAT
value for the basket item in percent
basketItems.amountGrossfloatGross amount (= amountNet + amountVat) in smallest unit of the currency.
Equals amountNet if the VAT value is 0
basketItems.amountVatfloatVAT amount. Equals 0 if the VAT value is 0
basketItems.amountPerUnit

(required)
numberAmount per unit
basketItems.amountNet

(required)
numberNet amount. Equals amountGross if VAT value is 0
basketItems.title

(required)
string (255)Title of the basket item
basketItems.subTitlestring (255)Subtitle of the basket item
basketItems.imageUrlstring (255)URL to the basket item image, only used for the payment page
basketItems.typestring(255)The type of this basket item. The valid values are goods, digital, shipment, and voucher.

Validating a basket

When creating or updating the basket, there are several validations which should be considered:

  • amountTotalGross must be equal to the sum of all basketItems.amountGross
  • amountTotalDiscount must be equal to the sum of all basketItems.amountDiscount
  • amountTotalVat must be equal to the sum of all basketItems.amountVatAmount
  • basketItems.amountVatAmount must be equal to the multiplication of basketItems.amountVat and basketItems.amountNet for every basket item

Additionally, the currencyCode of the basket must be the same as the currency provided in the authorize and charges calls. The amount provided in these calls must equal the difference of amountTotalGross and amountTotalDiscount.