Important information

The API reference is now available here.
The deprecated API reference is available here.


Manage basket (v2)

Submit product information within your payment.


Baskets are used for adding the additional information for the products that a customer is buying. It gives a more transparent and clear picture regarding their shopping details. Generally, a basket is optional, but some payment methods require such information for risk analysis, and insurance, such as Unzer Direct Debit and Unzer Invoice for instance. The advantages are:

  • The customer can review their shopping summary on our payment page before making a payment.
  • It helps with risk assessment and this can lead to improved acceptance rates.

Types of baskets

Based on your business requirements, you can implement the following basket APIs:

Standard basket

A standard basket contains the necessary details about the items, such as discounts, vouchers, or shipment costs. If you want to offer secured payment methods, a more comprehensive set of fields is required.


  • Essential details about the items, such as vouchers, discounts, and shipment cost
  • Basket item amounts are validated

Basket for marketplace usage

If you are processing transactions via our marketplace solution, you can provide a comprehensive set of details and the participant IDs for all the participants who are selling their products and services on your ecommerce platform.


  • Contains all the details of the Standard basket and the participant ID
  • Supports marketplace payment methods

Integration options for basket API for various payment methods

You can use the basket feature with payment pages, UI components, and server-side-only integration options.

Payment methods supporting basket API

Payment Type Name Payment Type Standard basket Marketplace basket
Unzer Direct Debit sepa-direct-debit Y X
Unzer Direct Debit sepa-direct-debit-secured Y X
Unzer Installment installment-secured Y X
Unzer Invoice invoice Y X
Unzer Invoice invoice-secured Y X
Unzer Prepayment prepayment Y X
Card card Y Y
PayPal paypal Y X
Sofort sofort Y Y
Giropay giropay Y X
Przelewy24 przelewy24 Y X
iDeal ideal Y X
EPS eps Y X
Alipay alipay Y X
WeChat wechatpay Y X
Apple Pay applepay Y X
Bancontact bancontact Y X
Post Finance eFinance post-finance-efinance Y X
Post Finance Card post-finance-card Y X
icon info
Once a basket is created, you cannot delete it.

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.
  2. A unique basket ID is created.
  3. The newly generated 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. For example, you can add more items, remove items, but cannot update the basket ID. A basket resource can be created or updated using your public or private key. Fetching a basket is only possible with your private key.

Although it’s possible to use any character combination for the orderId, we recommend that you use the same orderId as for payments (created by types/authorize, types/charge, and so on). The order ID should be unique to easily search and identify the transaction.

For more information, see API reference guide.

Updating a basket

If you want to update a basket, you must update all the contents of the basket. You cannot change individual items of a basket resource.

You can copy the contents of the old one, alter them, and submit it using a PUT command or create a new basket.

Replacing baskets for a specific payment

Currently, you cannot replace a basket with another basket for a transaction that is already initiated. So, once you create a charge or authorize request, it is not possible to change the basket ID.

The basket ID is generated for a specific payment and hence cannot be replaced.

Error codes for basket API

The basket related error codes begin with For more on the basket API, see the API reference.

See also