Itemized Fees and Discounts Overview

We’ve updated the create_payment_session API to accept additional details about any fees and discounts you’re applying, at both the order-level and item-level. This allows us to display the information provided on our payment page to provide a better breakdown of the total payment amount to users.

All fields added are optional, and should only be provided if the partner is applying discounts or additional charges

• all existing requests will continue to function as usual.

This page gives a general overview of the changes required to your requests. Our checkout page will display an itemized breakdown of each item and the cart if any itemized info is provided. Partners can also test that we are storing the information on a payment by using the payment_session_status or list_payment_sessions APIs. These have been updated to return the amount_details objects provided on payment creation.

When providing amount details, they must satisfy the following equation:

Example Scenario: Order-Level Charges

Let’s walk through an example scenario:

1. The total payment amount is $1000
2. There are 3 items being purchased:
   1. 1x “Item A” with a unit price of $55
      • A $45 additional charge named “Color Upgrade”
      • A $10 discount named “Ten Dollars Off”
   2. 2x “Item B” with a unit price of $150
   3. 4x “Item C” with a unit price of $20
      • A $5 discount named “Summer Sale”
3. There is a tax of $50, a handling fee of $100, and a shipping cost of $275 applied to the order

To provide the 3 additional charges to us for display on our payment page, the request would include the fields below (note that you will be providing additional fields in the request - this is a slimmed down version for clarity).

1
{
2
    "total_amount": 100000,
3
    "order_items": [
4
        {
5
            "name": "Item A",
6
            "quantity": 3,
7
            "price": 5500,
8
            "sku": "Item A SKU",
9
            "amount_details": {
10
                "total_additional_charges": 4500,
11
                "additional_charges_details": [
12
                  {"name": "Color Upgrade", "amount": 4500}
13
                ],
14
                "total_discounts": 1000,
15
                "discounts_details": [
16
                  {"name": "Ten Dollars Off", "amount": 1000}
17
                ]
18
            }
19
        },
20
        {
21
            "name": "Item B",
22
            "quantity": 2,
23
            "price": 15000,
24
            "sku": "Item B SKU"
25
        },
26
        {
27
            "name": "Item C",
28
            "quantity": 4,
29
            "price": 2000,
30
            "sku": "Item C SKU",
31
            "amount_details": {
32
                "total_discounts": 500,
33
                "discounts_details": [
34
                  {"name": "Summer Sale", "amount": 500}
35
                ]
36
            }
37
        }
38
    ],
39
    "amount_details": {
40
        "total_additional_charges": 42500,
41
        "additional_charges_details": [
42
          {"name": "Tax", "amount": 5000},
43
          {"name": "Handling", "amount": 10000},
44
          {"name": "Shipping", "amount": 27500}
45
        ]
46
    }
47
}

In this example scenario, there are no discounts provided at the order level, so total_discounts and discounts_details are omitted. There are also no item level fees or discounts for Item B, so amount_details is omitted from that order item. With this information, we can display each additional charge on our payment page.

The important points to note are:

1. Each additional charge detail amount must be $\geq 0$
   • Partners are allowed to provide an additional charge with an amount of 0 to indicate that the charge is free
2. All additional charge amounts sum up to the total_additional_charges field
3. The sum of each item’s subtotal (quantity × price + item-level charges - item-level discounts) + any order-level additional charges - any order-level discounts must equal the payment’s total_amount

For the example scenario above: