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. Identifying users
  3. Skeleton code

Skeleton code

Speaking the identity protocol

To identify a user, your store repeatedly posts a request to the Bango Payment API's Identity resource, and then acts on the response, until an end state is reached. Request parameters help the Bango Platform choose the best approach for identifying the user.

Here's some sample code in a C/Java-like language: adapt this code to your needs. Use the same API endpoint prefix with test credentials and with production credentials. Test credentials mean you won't charge anyone real money during the development/test cycle.

Some functions referenced in the skeleton code, such as send_sms_from_device, are not defined. You need to implement these where possible.

function get_bango_id () {
    // *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 bango_id = null;

    try {
        // We start without a session ID. The first request will allocate one,
        // which we reuse in subsequent requests until we reach a terminal state.
        let session_id = '';

        // Flag which is set true when we can't perform a requested action.
        let send_cancel = false;

        const request_body_params = {
            // Add request parameters as necessary here
        };

        while (bango_id == null) {
            // Tell the Bango Platform we can't perform
            // the requested action if necessary.
            if (send_cancel) {
                request_body_params.set("action", "cancel");
                send_cancel = false;
            } else {
                request_body_params.delete('action');
            }

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

            // The responseCode tells us what to do next.
            switch (response.responseCode) {
                // Success: we have the identity.
                case "OK":
                    bango_id = response.bangoUserId;
                    break;

                // Failure: unable to identify the user.
                case "USER_CANCELLED": // User declined to supply details
                case "NOT_AVAILABLE": // No identification methods were found
                    throw "User cannot be identified";

                // Merchant problems
                // These indicate issues in your code, not the Bango Platform.
                case "BAD_REQUEST":   // Invalid request
                case "UNAUTHORIZED":  // Check your credentials
                case "NOT_FOUND":     // Invalid session ID, or session expired
                    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"

                // More to do: The store must take action, then send another request
                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.
                            redirect_device_to({
                                url: response.parameters.url,
                            });
                            break;

                        case "SEND_SMS":
                            // Send an SMS on behalf of the user.
                            send_sms_from_device({
                                message: response.parameters.text,
                                to: response.parameters.shortcode,
                            });
                            break;

                        case "WAIT":
                            // Wait for a short period of time.
                            sleep({
                                milliseconds: response.parameters.suggestedWaitTimeMilliseconds,
                            });
                            break;

                        default:
                            // Unrecognized action. In the next request,
                            // we ask the Bango Platform to use a different method.
                            send_cancel = true;
                            break;
                    }

                    break;

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

            // The Bango Platform has allocated an ID for this identification session.
            session_id = response.sessionId;
        }

    } 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 bango_id;
}

Notice how the code uses the value of responseCode to decide what to do, in both success and error cases.

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

FAQ
Which request parameters should I set?

The skeleton code sets request_body_params to be empty. You might be able to supply more parameters in your production code. For example:

  • deviceCapabilitySendSms (default the string true) lets your store tell the Bango Platform if the user's device can't send SMS messages.
  • identificationMethodKey lets your store tell the Bango Platform which Mobile Network Operator the user's device uses.
  • thirdPartyUserId lets your store tell the Bango Platform of any bespoke user identifier.

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

Do I have to handle every possible response?

You might not need to implement everything in the skeleton code. Bango configures the Bango Platform according to the needs of each merchant, which means some stores might never receive a response CLIENT_ACTION_REQUIRED with action REDIRECT, for example. Other stores might always receive a Bango ID in the response of the first API request.

Contact Bango Support if you're unsure what you need to implement.

What should I do if I can't perform an action?

The Bango Platform may be extended at any time to support new identification methods. This may mean the response code CLIENT_ACTION_REQUIRED might start to reference actions your code doesn't currently handle – and possibly cannot ever handle, due to device limitations.

The skeleton code shows how to deal with this scenario: if you don't recognize or can't perform a CLIENT_ACTION_REQUIRED action, send the parameter action with string value cancel in the next request to the Identity resource, and let the conversation continue.

If you don't handle unrecognized actions in this way, your store may stop working when Bango introduces new identification methods.

What if none of my supported devices can send SMS?

In this scenario, include the parameter "deviceCapabilitySendSms": "false" with your requests to the Identity resource. You don't need to handle the SEND_SMS action in this case: treat it as an unrecognized action.

Copyright © 2000–2021 Bango.net Limited