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

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 NamePayment TypeStandard basket
Unzer Direct Debitsepa-direct-debitY
Unzer Direct Debitsepa-direct-debit-securedY
Unzer Installmentinstallment-securedY
Unzer InvoiceinvoiceY
Unzer Invoiceinvoice-securedY
Unzer PrepaymentprepaymentY
Apple PayapplepayY
Post Finance eFinancepost-finance-efinanceY
Post Finance Cardpost-finance-cardY
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