Checkout with line items, discounts and tax

Request

In the following request we will create a Checkout session with lineItems, totalDiscount, totalTaxAmount and subtotalAmount.

caution

Here's a breakdown of these values:

  • The amount is required and represents the total to collect for payment after discounts, inclusive of taxes.
  • The subtotalAmount represents the total before any discounts, inclusive of taxes.
  • The totalDiscount represents the reduction in price applied across all the products or services.
  • The totalTaxAmount represents the total tax added to the price of the products or services.

The lineItems, totalDiscount, totalTaxAmount and subtotalAmount values are optional and these values are for display purposes only and do not have an effect on the amount collected.

curl --location --request POST 'https://payments.yoco.com/api/checkouts' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <secret-key>' \
--data-raw '{
"amount": 900,
"currency": "ZAR",
"lineItems": [
{
"displayName": "Chips",
"quantity": 1,
"pricingDetails": {
"price": 1000
}
}
],
"totalDiscount": 100,
"totalTaxAmount": 117,
"subtotalAmount": 1000
}'
important

Replace <secret-key> with your secret API integration key. For more information, see here.

important

Given the amount to collect and totalDiscount to apply, the subtotalAmount and totalTaxAmount can be calculated as follows:

  • subtotalAmount = amount + totalDiscount
  • totalTaxAmount = amount - (amount)/(1.15)

Response

HTTP: 200 OK
{
{
"id": "ch_9LVKD8GnAj7f39DFbn4F16bE",
"redirectUrl": "https://c.yoco.com/checkout/ch_9LVKD8GnAj7f39DFbn4F16bE",
"status": "created",
"amount": 900,
"currency": "ZAR",
"paymentId": null,
"cancelUrl": null,
"successUrl": null,
"failureUrl": null,
"metadata": {
"checkoutId": "ch_9LVKD8GnAj7f39DFbn4F16bE",
"paymentFacilitator": "yoco-online-checkout"
},
"merchantId": "1687579359397-9ecd46a3-83f9-4563-8def-20ac11p67087",
"totalDiscount": 100,
"totalTaxAmount": 117,
"subtotalAmount": 1000,
"lineItems": [
{
"displayName": "Chips",
"quantity": 1,
"pricingDetails": {
"price": 1000
}
}
],
"externalId": null,
"processingMode": "live"
}
}