Basket

Submit product information within your payment.

Introduction

Unzer provides you with a basket feature, so that you can submit product information inside baskets for every individual transaction. Generally the use of baskets is optional, but some payment methods need such information for risk analysis, like Unzer Direct Debit Secured and Unzer Invoice Secured for instance.

General procedure

Here’s how the Basket API operates:

  1. You, the merchant, create a basket.
  2. You receive a basket ID from Unzer.
  3. The newly generated basketId can now be passed on to a payment creating the reference to the basket.
  4. As soon as a transaction is completed (regardless of the result), the basket cannot be replaced.

If a basket has been created, it cannot be replaced, nor deleted. If you haven’t assigned a basket to a payment yet, you can update (“override”) an existing basket. This means you cannot alter specific attributes but you can provide new basket data for the given ID. For more information, see the updating a basket chapter.

Creating a basket

To create a new basket resource, simply execute a POST request with your desired contents in JSON format. Note: A basket resource can be created/updated using your public or private key. Fetching a basket is only possible with your private key (check out the API reference for more information).

Here is an example:

UnzerAPI - Creating a basket

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

As you can see, you can pass a lot of parameters to the JSON object. In the references section, you can see if these are optional or mandatory, what type they are and a short description for them.

Order ID
Although it’s possible to use any character combination for the orderId, we highly recommend you use the same orderId as for payments (created by types/authorize, types/charge, …).
Note: The order ID has to be unique.

This is how your response to a request like the one above should look like:

Response:
{
    "id":"s-bsk-1"
}
Private Key
A basket can only be fetched using your private key!

Fetching a basket

To fetch a specific basket resource, execute a GET request with the basket ID you want to fetch. Again, you have to use your private key, otherwise the request won’t go through (check out the API reference for more information).

Just add the basket ID at the end of the URL, like so:

UnzerAPI - Fetching a basket

GET https://api.unzer.com/v1/baskets/s-bsk-1

Your response should look similar to this:

Response:
{
  "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, like we did here:

UnzerAPI - Executing a charge

POST https://api.unzer.com/v1/payments/charges

This is how the request body should look like, note the basketId in the resources section:

{
  "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 command or create an entirely new one altogether.

Changing baskets on payments
Keep in mind: 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 tied 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 concrete examples.

Error Codes

In case you run into some errors, here are explanations for basket-specific error codes:

Error Code Description
300.100.200 no basket id given
300.100.201 no basket items given
300.100.202 no basket given
300.100.300 no valid basket id given
300.200.400 basket parse error
300.200.401 basket request parse error
300.200.500 basket processing error occurred
300.200.600 unsupported media type

References

name format condition description
amountTotalGross number Mandatory Total amount (excluding vat) of the whole basket in unit of the currency.
amountTotal number Deprecated
amountTotalDiscount number Optional Total discount amount of the whole basket in unit of the currency.
amountTotalVat number Optiona Total VATamount of the basket in the unit of the currency.
currencyCode String (3) Mandatory Currency code in ISO_4217 format
orderId String (255) Mandatory & Unique A basket or shop reference id sent from the shop backend.
Recommended: paymentId
note String (3900) Optional A note sent from the shop backend
basketItems Object[] Mandatory Set of basket items
basketItems.basketItemReferenceId String (255) Mandatory Unique basket item reference id (within the basket)
basketItems.unit String (255) Optional Unit description of the item e.g. “Pc.”
basketItems.quantity number Mandatory Quantity of the basket item
basketItems.amountDiscount number Optional Discount amount for the basket item
basketItems.vat number(0-100) Optional VATvalue for the basket item in percent
basketItems.amountGross number Optional Gross amount (= amountNet + amountVat) in smallest unit of the currency.
Equals amountNet if VATvalue is 0
basketItems.amountVat number Optional VATamount. Equals 0 if VATvalue is 0
basketItems.amountPerUnit number Mandatory Amount per unit
basketItems.amountNet number Mandatory Net amount. Equals amountGross if VATvalue is 0
basketItems.title String (255) Mandatory Title of the basket item
basketItems.subTitle String (255) Optional Subtitle of the basket item
basketItems.imageUrl String (255) Optional URL to the basket item image, only used for the payment page
basketItems.type String(255) Optional Type of the basket item, e. g. “goods”, “shipment”, “voucher”, “digital” or “physical”

Validation

When creating or updating the basket there are several validations which should be considered:

  • amountTotalGross should be equal to the sum of all basketItems.amountGross
  • amountTotalDiscount should be equal to the sum of all basketItems.amountDiscount
  • amountTotalVat should be equal to the sum of all basketItems.amountVatAmount
  • basketItems.amountVatAmount should be equal to the multiplication of basketItems.amountVat and basketItems.amountNet for every basket item

Additionally the currencyCode of the basket should be the same as the currency provided in the authorize and charges calls. The amount provided in these calls should equal the difference of amountTotalGross and amountTotalDiscount.