Checking available payment methods

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.

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
}