Manage baskets

Submit customer information within your payment.

Overview

A basket is a collection of product information 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, Unzer Invoice Secured, and Unzer Instalment.

How it works

  1. In your eCommerce site, the customer selects the items 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.

To learn more about baskets, see Manage customer (API).

Create a basket

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

A basket resource can be created or updated using your public or private key. You can fetch a basket with your private key (see the API reference for more information).

Request

Unzer unzer  = new Unzer("s-priv-xxxxxxxxxx");
BasketItem basketItem = new BasketItem()
                .setBasketItemReferenceId("Artikelnummer4711")
                .setQuantity(5)
                .setAmountPerUnit(new BigDecimal(100.1))
                .setAmountNet(new BigDecimal(420.1))
                .setTitle("Apple iPhone");

Basket basket = new Basket()
                .setAmountTotalGross(new BigDecimal(500))
                .setCurrencyCode(Currency.getInstance("EUR"))
                .setOrderId(orderId)
                .addBasketItem();

Basket basket = unzer.createBasket(minBasket);
Order ID
  • Although it’s possible to use any character combination for the orderId, we recommend using the same orderId as for payments (created by types/authorizetypes/charge, and so on).
  • The order ID must be unique.

The response contains a basket ID, which will be saved in your basket object.

basket.getId();

Fetching a basket

To fetch a specific basket resource, use your private key and send a GET request with the basket ID.

Request

Unzer unzer  = new Unzer("s-priv-xxxxxxxxxx");
Basket basketFetched = getUnzer().fetchBasket("s-bsk-1");

Response

The fetchBasket method will return a Basket Instance containing the Basket information from the payment API response.

Go to the API reference (link to basket V1 resources) for more information.

Adding a basket to your transaction

Here you can see how to add a basket to a transaction, in our example a charge request. Add the basket ID to your resources parameter list as shown in the following example:

Request

Unzer unzer  = new Unzer("s-priv-xxxxxxxxxx");
Charge charge = unzer.charge(
  BigDecimal.valueOf(12.99),
  Currency.getInstance("EUR"),
  "s-crd-9wmri5mdlqps",
  "https://your.return.url",
  null,
  "s-bsk-1",
  null,
  null
)

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 the shipping fees changed.

In such 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 the Unzer.updateBasket method, or create a new basket.