Checkout with discounts and tax


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


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 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 '' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <secret-key>' \
--data-raw '{
"amount": 900,
"currency": "ZAR",
"totalDiscount": 100,
"totalTaxAmount": 117,
"subtotalAmount": 1000

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


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)


HTTP: 200 OK
"id": "ch_9LVKD8GnAj7f39DFbn4F16bE",
"redirectUrl": "",
"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": null,
"externalId": null,
"processingMode": "live"