Transaction Payment Items structure

Most transaction-related requests in the Bango Payment API let you include a paymentItems body parameter with the request. This is a structure that represents goods for sale on your store, including prices in various currencies. The structure is used for authorizing, capturing and refunding transactions. This page defines the Payment Items structure, which is built from lower-level structures: the Price structure, and the Payment Item structure.

The Price structure

The Price structure describes pricing information for an item in a specific currency. Here's an example in JSON format:

{
    "currencyIso3": "USD",
    "grossAmount": "0.99",
    "financialBreakdown": {
        "taxAmount": "0.00",
        "shippingAmount": "0.00"
    }
}

In full, the Price structure consists of:

• currencyIso3: Mandatory, string, three-character ISO 4217 currency code. The currency applicable to all price values in the structure. For the list of supported codes, see ISO 4217 Currency Codes.
• grossAmount: Mandatory, string, at most two decimal digits. Gross price (tax included) without currency specifier. The total amount the user will be charged.
• financialBreakdown: Optional, object. If specified, contains special financial breakdown values that may be required depending on the commercial agreements with Bango and the payment provider. Bango recommends you include all values, if possible, to maximize payment success rates. Properties are:
• taxAmount: Optional, string. Indicates the tax amount.
• shippingAmount: Optional, string. Indicates the shipping value.

The Payment Item structure

The Payment Item structure describes all details, including pricing information, for a single item in your store. JSON example:

{
    "itemName": "Item title",
    "itemDescription": "Item description",
    "itemCategory": "1",
    "externalPaymentItemId": "abcd-1234",
    "submerchantReferenceKey": "defg-5678",
    "priceList": [
        {
            "grossAmount": "0.99",
            "currencyIso3": "USD",
            "financialBreakdown": {
                "taxAmount": "0.00"
            }

        },
        {
            "grossAmount": "0.89",
            "currencyIso3": "EUR",
            "financialBreakdown": {
                "taxAmount": "0.00"
            }
        },
        {
            "grossAmount": "0.79",
            "currencyIso3": "GBP",
            "financialBreakdown": {
                "taxAmount": "0.00"
            }
        }
    ]
}

The Payment Item structure consists of:

• itemName: Optional, string. Descriptive name of the item on sale. Appears in the user's bill or statement if supported by the payment provider.
• itemDescription: Optional, string. Long description of the item on sale.
• itemCategory: Optional, string. Category of the item on sale. The list of possible category values can be configured, and is agreed between you and Bango. See below.
• externalPaymentItemId: Optional, string. Your custom identifier for this item within the transaction. Recommended, to help Bango process refunds if necessary.
• submerchantReferenceKey: Optional, string. For merchants that require different processes (such as financial reporting and reconciliation) for different departments or financial entities, the Bango Platform can be configured to enable "submerchants". Contact Bango Support if you need this feature.
• priceList: Mandatory, array of Price structures, at least one member. All the relevant prices you support for the item. The Bango Platform automatically selects the most appropriate price for the user.

The Payment Items structure

The overall Payment Items structure consists of an array of Payment Item structures.

Currently, the array must contain exactly one member (in other words, you can pass exactly one item for sale on your store to the Bango Platform). The Bango Platform may be extended later to support arrays with more than one member.

Item categories

A Mobile Network Operator's Direct Carrier Billing system might require information about what's being sold. This could be for tax reasons, or to restrict payment for age-restricted items, or to allow different revenue-sharing or marketing-reimbursement models that you agree with the operator. To support this requirement your store can place items into a category, which Bango automatically maps to the appropriate category for the operator if applicable. Bango maintains a list of category names or codes used by operators.

For example, the category for "Music" (audio recordings that represent vocal or instrumental sounds) might have different category mappings across operators: "Musique", "Musika", "CAT-03", "Musik", and so on.

The Mobile Network Operators define which items should appear in which categories (and this might be covered by your agreement with each operator).

If you omit category information, Bango places an item in a "general" category for the operator. If you require a special category for some of your items to implement contract requirements with an operator, Bango can create one for you and pass the category to the operator billing system or record it for future analysis.