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:
- You, the merchant, create a basket.
- You receive a basket ID from Unzer.
- The newly generated
basketId
can now be passed on to a payment creating the reference to the basket. - 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.
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"
}
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.
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 allbasketItems.amountGross
amountTotalDiscount
should be equal to the sum of allbasketItems.amountDiscount
amountTotalVat
should be equal to the sum of allbasketItems.amountVatAmount
basketItems.amountVatAmount
should be equal to the multiplication ofbasketItems.amountVat
andbasketItems.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
.