Unzer

Manage basket (v1)

Submit product information within your payment.

Overview

A basket is a collection of product information inside baskets for each transaction. It is not a mandatory resource, but some payment methods require this information for risk analysis, such as Unzer 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](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 Code Description
300.100.200 no basket ID given
300.100.201 no basket items given
300.100.202 no basket given
300.100.300 no valid basket ID given
300.200.400 basket parse error
300.200.401 basket request parse error
300.200.500 basket processing error occurred
300.200.600 unsupported media type

References

Parameter Type Description
amountTotalGross

(required)
number Total amount (including VAT) of the whole basket in the unit of the currency.
amountTotal

(deprecated)
number Total amount of the basket in the unit of the currency. This is now deprecated.
amountTotalDiscount number Total discount amount of the whole basket in unit of the currency.
amountTotalVat number Total 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
note String (3900) A note sent from the shop backend
basketItems

(required)
Object Set of basket items
basketItems.basketItemReferenceId string (255) Unique basket item reference id (within the basket)
basketItems.unit string (255) Unit description of the item e.g. “Pc.”
basketItems.quantity

(required)
number Quantity of the basket item
basketItems.amountDiscount number Discount amount for the basket item
basketItems.vat number(0-100) VAT

value for the basket item in percent
basketItems.amountGross number Gross amount (= amountNet + amountVat) in smallest unit of the currency.
Equals amountNet if the VAT value is 0
basketItems.amountVat number VAT amount. Equals 0 if the VAT value is 0
basketItems.amountPerUnit

(required)
number Amount per unit
basketItems.amountNet

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

(required)
string (255) Title of the basket item
basketItems.subTitle string (255) Subtitle of the basket item
basketItems.imageUrl string (255) URL to the basket item image, only used for the payment page
basketItems.type string(255) Type of the basket item, for example, goods, shipment, voucher, digital or physical

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.