[Deprecated] Manage baskets (v1)

Submit product information within your payment.

• Basket v1 is now deprecated.
• Update to basket v2 to get the latest features of the basket.
• For Unzer Invoice, basket v2 is required.

Overview

A basket is a collection of product information for all the items of a transaction. It is not a mandatory resource, but some payment methods require this information for risk analysis, such as 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.

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
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 
    }
  ]
}

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:

References

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.