Skeleton code

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.