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

Authorizing a payment

Starting a transaction to reserve funds for a user purchase

In the Bango Platform, transactions are two-step: in the first step your store authorizes payment, and in the second step your store captures payment. To authorize payment, you create a transaction by making a POST request to the Bango Payment API.

As part of the API request, you supply:

  • The user's identified Bango ID
  • A structure representing the item the user wants to purchase
  • At least one URL that the Bango Platform might use to pass your store a transaction ID asynchronously
  • Optionally, the payment methods you would like to be offered
  • Optionally, custom transaction data

(You might want to check payment methods before creating the transaction.)

The API response is a structure that contains:

  • Either a unique, opaque, persistent transaction ID (the payment is authorized)
  • Or a reason why the transaction can't be created (the payment is not authorized)
  • Or a request for the store to perform an action (the payment is not yet authorized: a transaction ID or failure may be passed to your store asynchronously by a URL notification)

A payment might not be authorized if, for example, the user has exceeded a spending limit, or is barred, or has spent too much money in a short time.

Sequence diagrams
Successful authorization

The Bango Platform authorizes payment, and returns the transaction ID in the response to the API request:

Failed authorization

The Bango Platform denies authorization for payment, and returns the reason in the response to the API request:

Redirect to web-based authorization flow

The Bango Platform needs your store to redirect the user to a payment authorization flow URL to determine whether the payment is authorized or not. You redirect the user, and when the user completes the payment authorization flow the Bango Platform tells your store whether payment is authorized or not – either using a user redirection, or by direct server-to-server communication.

Skeleton code

function get_transaction_id () {
    // *Always* use this endpoint prefix for the Bango Payment API.
    const base_url = "";

    // This is what we're trying to find.
    let transaction_id = 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"

        // Store's custom transaction id for correlation/idempotency, if necessary
        externalTransactionId: "my-unique-tx-id-12345678",

        // Store's custom URL: the Bango Platform POSTs asynchronously
        // to this URL on authorization, if the response can't be
        // returned synchronously due to REDIRECT action
        extensionData: {
            notificationUrl: ""

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

        // The responseCode tells us the result.
        switch (response.responseCode) {
            // Success: payment is authorized, transaction created
            case "OK":
                transaction_id = response.transactionId;

            // More to do: The store must take action
            case "CLIENT_ACTION_REQUIRED":
                // This response parameter tells us what we need to do.
                switch (response.parameters.action) {
                    case "REDIRECT":
                        // Send the user to a particular web page.
                        // request_body_params must include either
                        // notificationUrl or callbackUrl to ensure
                        // the store receives the result asynchronously
                            url: response.parameters.url,

                        // Unrecognized action.
                        // Check the documentation again.
                        throw "Unrecognized client action";


            // 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
            case "DECLINED": // Payment provider declined authorization
            case "SPEED_LIMIT": // Request too soon after previous payment
            case "USER_BARRED": // User not allowed to use payment method
            case "USER_INSUFFICIENT_CREDIT": // User cannot afford purchase
            case "USER_NOT_ENABLED": // Payment provider not enabled user
            case "USER_SPEND_LIMIT": // User reached limit imposed by provider
            case "USER_SUSPENDED": // User temporarily barred from payment method
                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 "CONNECT_ERROR":
            case "FAILURE":
            case "SERVICE_UNAVAILABLE":
            case "CONNECT_TIMEOUT":
                throw "Bango Platform unavailable"

            // This might indicate Bango has added a new response code.
            // Check the documentation again.
                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!");

    // null if payment not authorized or user redirected.
    // In the redirect case, a transaction ID might be set asynchronously
    // through the notificationUrl or callbackUrl parameter.
    return transaction_id;
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, to check whether the prices are supported price points for the payment provider, and to reserve the appropriate funds to authorize payment.

You must set at least one of the extensionData.notificationUrl and extensionData.callbackUrl parameters in the request, to support asynchronous notification of transaction IDs.

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.

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

In the redirect case, how do I receive the authorization result?

If the payment provider or payment method requires the user to be directed to a web-based payment flow, the Bango Platform responds to an authorization request with the responseCode value CLIENT_ACTION_REQUIRED and parameters.action value REDIRECT (other actions might be supported in future). In this case, the response does not include a transaction ID as the payment has not yet been authorized.

When the user completes the payment flow, the Bango Platform generates a structure similar to an authorization API response, including the parameters responseCode, transactionId (0 on failure), and externalTransactionId (if specified in the authorization request). Valid values for responseCode are as for the authorization API response, except that CLIENT_ACTION_REQUIRED is never used.

The Bango Platform then sends a POST request to the extensionData.notificationUrl, if specified in your store's original authorization request, including this structure as the notification POST body. For example:

    "externalTransactionId": "my-unique-tx-id-12345678",
    "transactionId": "9876543210",
    "responseCode": "OK"

You can also (or alternatively) specify extensionData.callbackUrl in the authorization request. If a callback URL is specified, the Bango Platform redirects the user to the URL after they complete the payment flow. The Bango Platform adds the parameters externalTransactionId, transactionId, and responseCode to the callback URL.

Copyright © 2000–2021 Limited