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 API response is a structure that contains:
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.
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
}