Bango uses cookies to give you the best website experience. By using this website you agree to let Bango use cookies. More info
OK
Bango Developer
  1. Bango Payment
  2. Transactions
  3. Checking available payment methods

Checking available payment methods

Improving the user experience before purchase

The Bango Platform currently supports a number of different payment methods, and more may be added. To determine which payment methods are available for a particular user at the time of purchase, and perhaps limit the payment methods to a subset of those supported, you can make an OPTIONS request to the Bango Payment API. The response includes information to help you improve the user experience.

As part of the API request, you supply:

  • The user's identified Bango ID
  • A structure representing the item the user wants to purchase
  • Optionally, the payment methods you would like to be offered
  • Optionally, custom transaction data

The API response is a structure that contains:

  • Either the payment methods you can use (for display in your user interface)
  • Or a reason why the purchase is not possible

A purchase might not be possible if, for example, the user has exceeded a spending limit.

The response is time-sensitive: the available payment methods may change over time. For example, the user may exceed the spending limit by other means. Avoid caching responses for too long, to avoid transaction errors later.

Sequence diagrams
Purchase is possible

The Bango Platform determines that the purchase is possible, and includes the available payment methods in the API response:

Purchase is not possible

The Bango Platform determines that the purchase isn't possible, and supplies a reason:

Skeleton code

function get_payment_methods () {
    // *Always* use this endpoint prefix for the Bango Payment API.
    const base_url = "https://api.bango.net/v5/";

    // This is what we're trying to find.
    let payment_methods = null;

    const request_body_params = {
        // The user's identity.
        // In production you would probably pass this as an argument
        // to the function.
        bangoUserId: "123456789",

        // An array of strings, one for each supported payment method
        // you would like the Bango Platform to consider.
        // For example:
        paymentMethods: [
            "OPERATORBILLING", // Direct Carrier Billing payment
            "INTERNET", // Internet-based payment
        ],

        // The item to be purchased.
        // (Always use an array of one item: multiple items might
        // be supported at a later date.)
        // In production you would probably pass this as an argument
        // to the function.
        paymentItems: [
            {
                itemName: "My item",
                itemDescription: "My item description",
                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"
                        }
                    }
                ]
            }
        ]
    };

    try {
        // send UTF-8 JSON to the Bango Payment API and parse the JSON response
        let response = rest_client_call({
            method: "OPTIONS",
            url: base_url + "transaction/",
            headers: {
                "Authorization": get_authorization_header(),
                "Content-Type": "application/json",
            },
            body: make_json_string(request_body_params),
        }).from_json();

        // The responseCode tells us the result.
        switch (response.responseCode) {
            // Success: at least one payment method is available.
            case "OK":
                // See below for details of this structure.
                payment_methods = response.availablePaymentMethods;
                break;

            // Failure: unable to proceed with purchase
            case "NOT_AVAILABLE": // None of the requested methods is available
            case "PRICE_NOT_SUPPORTED": // Payment methods don't support supplied prices
            case "USER_EXCEEDED_LIMIT": // User cannot spend more money
                throw "Unable to purchase item";

            // Merchant problems
            // These indicate issues in your code, not the Bango Platform.
            case "BAD_REQUEST":   // Invalid request
            case "INVALID_BANGOUSERID":  // Bango ID not recognized
            case "UNAUTHORIZED":  // Check your credentials
                throw "Merchant implementation error";

            // Bango Platform issues
            // These likely indicate transient problems.
            // In production code, you might want to try the request again
            // after a delay, ultimately falling back to an error state.
            case "INTERNAL_ERROR":
            case "SERVICE_UNAVAILABLE":
                throw "Bango Platform unavailable"

            // This might indicate Bango has added a new response code.
            // Check the documentation again.
            default:
                throw "Unrecognized response code";
        }

    } catch (exception) {
        // Production code might want to notify the merchant in some way,
        // and/or log full details of the exception for later analysis,
        // and degrade gracefully for the user.
        output("An error occurred!");
        output(exception);
    }

    return payment_methods; // null if payment cannot proceed
}
FAQ
Which request parameters should I set?

You must set the bangoUserId and paymentItems parameters, to allow the Bango Platform to check whether the user is permitted to purchase the item, and to check whether the prices are supported price points for the payment provider.

You can omit paymentMethods if you want the Bango Platform to consider all possible payment methods.

See Bango Payment / Merchant API reference / API reference overview for detailed information on all request parameters.

What are all the possible API response structures?

All responses contain a responseCode string that indicates the result of the request. Use this code to determine how to react. For each distinct responseCode, the response might include other useful values.

The most interesting case is when responseCode is OK. In this case, the response object includes a property availablePaymentMethods that describes which payment methods are permitted for the purchase.

See Bango Payment / Merchant API reference / API reference overview for detailed information on all responses.

Copyright © 2000–2021 Bango.net Limited