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.

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

Response:
{
    "id":"s-bsk-1"
}

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.

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:

References

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.