Manage baskets (v2)

Submit basket information within your payment.

Overview

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

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 v2/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 the baskets, see Basket section.

Creating a basket

To create a new basket resource, send a POST request with your desired contents in the JSON format. The SDK provides the Unzer::createBasket() method to do so.
The v2/baskets endpoint will automatically be used when the basket object has the totalValueGross property set.

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 out the basket resource in API reference for more information).

Request

$unzer = new Unzer('s-priv-xxxxxxxxxx');

$basketItem = (new BasketItem())
    ->setBasketItemReferenceId('Item-d030efbd4963')
    ->setQuantity(10)
    ->setUnit('m')
    ->setAmountPerUnitGross(20.00)
    ->setAmountDiscountPerUnitGross(1.00)
    ->setVat(19.0)
    ->setTitle('SDM 6 CABLE')
    ->setSubTitle('This is brand new Mid 2019 version')
    ->setImageUrl('https://a.storyblok.com/f/91629/x/1ba8deb8cc/unzer_primarylogo__white_rgb.svg')
    ->setType(BasketItemTypes::GOODS);

$basket = (new Basket())
    ->setTotalValueGross(190.00)
    ->setCurrencyCode('EUR')
    ->setOrderId('Order-12345')
    ->setNote('Test Basket')
    ->addBasketItem($basketItem);

$unzer->createBasket($basket);

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/authorize, types/charge).
• The order ID must be unique.

The response contains a basket ID that is 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  = new UnzerSDK\Unzer('s-priv-xxxxxxxxxx');
$basket = $unzer->fetchBasket('s-bsk-1');

Response

The fetchBasket method returns a basket instance containing the basket information.

Go to the API reference 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. To add a basket to a transaction, add the basket ID to your resources parameter list as shown in the following example:

Request

$unzer     = new UnzerSDK\Unzer('s-priv-xxxxxxxxxx');

$charge = new Charge(500.00, 'EUR', $returnUrl);
$unzer->performCharge($charge, 's-crd-9wmri5mdlqps', null, null, 's-bsk-1');

Updating a basket

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

In this case, you must update the whole basket. You can’t change specific parts of a basket. Either copy the contents of the old one, alter them and submit it using the Unzer::updateBasket method, or create a new basket.

$unzer  = new UnzerSDK\Unzer('s-priv-xxxxxxxxxx');
$basket= $unzer->fetchBasket('s-bsk-1');
$basket->setTotalValueGross(400);
$basket->getBasketItemByIndex(0)->setQuantity(4);
$unzer->updateBasket($basket);