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 API
  2. API reference

User identification API

Details of the API for discovering Bango IDs

This page describes methods of the Bango Payment API's Identity resource used to determine Bango IDs for users.

Identifying a user might take several requests. For the first request, you can supply parameters to help the Bango Platform choose the best approach to identifying the user. These aren't required (but can be included) in any subsequent requests you might need to make. Both the initial request and all subsequent requests return the same set of possible responses: either including the Bango ID, or reporting a failure of some kind, or requesting the store perform an action and then make another identification request. (See Bango Payment API / Identifying users / Skeleton code for some discussion.)

Every API request must comply with the requirements in Bango Platform / Connectivity and security. All request body parameters and responses are encoded as UTF-8 JSON objects.

Get a user's Bango ID (initial request)

POST https://api.bango.net/v5/identity
Path parametersNone
Header parameters
Authorization string

Your Bango Payment API credentials encoded for HTTP Basic Authentication. See Bango Platform / Connectivity and security / Basic authentication.

Query parametersNone
Body parameters
identificationMethodKey string

Indicates which Mobile Network Operator the user's device is currently using, which the Bango Platform can use to help identify the user. See Bango Grid for allowed values. Special values are used for Bango TestPay.

thirdPartyUserId string

Lets your store tell the Bango Platform of any bespoke identifier your store maintains for the user. This improves cross-device billing, allowing users to share billing credentials for payments on their phone, tablet, or PC, for example.

deviceCapabilitySendSms string

Default value true. Lets your store tell the Bango Platform if the user's device can't send SMS messages. If you set this to the string false then the Bango Platform won't send a CLIENT_ACTION_REQUIRED response with the action SEND_SMS.

msisdn string

Lets your store tell the Bango Platform the user's phone number, if known. This improves the user experience where the Bango Identity Flow is used.

callbackUrl string

Absolute URL. If the user was redirected to a URL as part of the identification process, then the Bango Platform redirects the user to callbackUrl (if specified) when identification is complete. callbackUrl may contain any query parameters but not bangoUserId, identificationSessionId, sessionId, or responseCode. The Bango Platform will add the query parameter sessionId, so your code at the callback URL can use this to send a final POST request to get the user's Bango ID. See also Bango Payment API / API reference / Callbacks and notifications.

notificationUrl string

Absolute URL. If specified, the Bango Platform sends a POST request to notificationUrl on a successful identification. notificationUrl may contain any query parameters but not bangoUserId, identificationSessionId, sessionId, or responseCode. The Bango Platform POST will contain body parameters bangoUserId and identificationSessionId. See also Bango Payment API / API reference / Callbacks and notifications.

Sample requests
Use all optional parameters
POST https://api.bango.net/v5/identity HTTP/1.1

{
    "identificationMethodKey": "SOME_NETWORK_NAME",
    "thirdPartyUserId": "my-custom-id-123456789",
    "deviceCapabilitySendSms": "false",
    "msisdn": "447710900120",
    "callbackUrl": "https://mystore.example.com/on-id?foo=abcde",
    "notificationUrl": "https://mystore.example.com/notify"
}

Start an identification session for a user with a known phone number, who can't send SMS. The store's own unique identifier for the user is my-custom-id-123456789, and the device is connected to the SOME_NETWORK_NAME Mobile Network Operator. If the user is redirected to a web-based identification flow, at the end of that flow they'll be redirected to https://mystore.example.com/on-id?foo=abcde&sessionId=sessionId, where sessionId is a unique session ID. Also, the Bango Platform will POST bangoUserId and identificationSessionId to https://mystore.example.com/notify.

Specify a callback only
POST https://api.bango.net/v5/identity HTTP/1.1

{
    "callbackUrl": "https://mystore.example.com/on-id?foo=abcde"
}

A much smaller request body that doesn't supply any user or device information. If the user is redirected to a web-based identification flow, at the end of that flow they'll be redirected to https://mystore.example.com/on-id?foo=abcde&sessionId=sessionId, where sessionId is a unique session ID.

Response body
responseCode string

The status of the identification session. Use this in your code to determine your store's next action. Possible values: OK, CLIENT_ACTION_REQUIRED, USER_CANCELLED, NOT_AVAILABLE, BAD_REQUEST, UNAUTHORIZED, NOT_FOUND, INTERNAL_ERROR, CONNECT_ERROR, FAILURE, SERVICE_UNAVAILABLE, CONNECT_TIMEOUT. See sample responses for more information.

responseMessage string

A short human-readable message describing responseCode. Not for use by code.

sessionId string2xx

The unique identifier for the identification session. If you need to make another request to identify the user, you must supply this session ID as the path parameter.

bangoUserId string or null2xx

If responseCode is OK, contains the user's Bango ID. Otherwise, the value is null.

parameters object2xx

Keys and values that depend on responseCode. See sample responses.

Sample responses
200OKSuccessful identification
{
    "responseCode": "OK",
    "responseMessage": "Success.",
    "sessionId": "9c7b9891-c871-4dd5-bdcc-ac25ff2412b7",
    "bangoUserId": "123456789",
    "parameters": {}
}

The Bango Platform identified the user. The bangoUserId property contains the user's Bango ID.

Testing
Prefer: status=200
202CLIENT_ACTION_REQUIRED: REDIRECTStore must redirect the user to the URL provided
{
    "responseCode": "CLIENT_ACTION_REQUIRED",
    "responseMessage": "An action is required in the client.",
    "sessionId": "9c7b9891-c871-4dd5-bdcc-ac25ff2412b7",
    "bangoUserId": null,
    "parameters": {
        "action": "REDIRECT",
        "url": "http://www.example.com/id?param=6bd6305c"
    }
}

To identify the user, the Bango Platform needs more information. The parameters.action value is REDIRECT, meaning the store must redirect the user's device to the URL given in parameters.url. After redirecting the user, the store should make another identification request, supplying the session ID.

Testing
Prefer: status=202
preference-extension: responseCode=CLIENT_ACTION_REQUIRED; action=REDIRECT
202CLIENT_ACTION_REQUIRED: SEND_SMSStore must send an SMS on behalf of the user
{
    "responseCode": "CLIENT_ACTION_REQUIRED",
    "responseMessage": "An action is required in the client.",
    "sessionId": "9c7b9891-c871-4dd5-bdcc-ac25ff2412b7",
    "bangoUserId": null,
    "parameters": {
        "action": "SEND_SMS",
        "shortcode": "12345",
        "text": "8774b33a-8a8f-4f8c-bb4a-b60c6e96df16"
    }
}

To identify the user, the Bango Platform needs more information. The parameters.action value is SEND_SMS, meaning the store must send an SMS on behalf of the user (or, if the device does not allow this to happen automatically, ask the user to send the SMS). The parameters.shortcode value is the phone number to send the SMS to. The parameters.text value is a unique code that must be included in the SMS message body. After sending the SMS, the store should make another identification request, supplying the session ID.

Testing
Prefer: status=202
preference-extension: responseCode=CLIENT_ACTION_REQUIRED; action=SEND_SMS
202CLIENT_ACTION_REQUIRED: WAITStore must wait a few milliseconds
{
    "responseCode": "CLIENT_ACTION_REQUIRED",
    "responseMessage": "An action is required in the client.",
    "sessionId": "9c7b9891-c871-4dd5-bdcc-ac25ff2412b7",
    "bangoUserId": null,
    "parameters": {
        "action": "WAIT"
        "suggestedWaitTimeMilliseconds": "3600"
    }
}

To identify the user, the Bango Platform is waiting for information to be received (from the user or a third party). The parameters.action value is WAIT, meaning the store must wait for a short period of time. The parameters.suggestedWaitTimeMilliseconds value is the number of milliseconds to wait. After waiting, the store should make another identification request, supplying the session ID.

Testing
Prefer: status=202
preference-extension: responseCode=CLIENT_ACTION_REQUIRED; action=WAIT
202USER_CANCELLEDUser has declined to be identified
{
    "responseCode": "USER_CANCELLED",
    "responseMessage": "The user cancelled the identification flow.",
    "sessionId": "9c7b9891-c871-4dd5-bdcc-ac25ff2412b7",
    "bangoUserId": null,
    "parameters": {}
}

The Bango Platform couldn't identify the user, as the user chose not to supply required information. Your store should show a suitable message to the user.

Testing
Prefer: status=202
preference-extension: responseCode=USER_CANCELLED
202NOT_AVAILABLENo identification methods found
{
    "responseCode": "NOT_AVAILABLE",
    "responseMessage": "No valid identification methods were found.",
    "sessionId": "",
    "bangoUserId": null,
    "parameters": {}
}

The Bango Platform couldn't identify the user, as none of the possible identification methods were suitable or available (your store should show a suitable message to the user). This may indicate the request contained an invalid identificationMethodKey value: check your store code.

Testing
Prefer: status=202
preference-extension: responseCode=NOT_AVAILABLE
400BAD_REQUESTStore sent an invalid API request
{
    "responseCode": "BAD_REQUEST",
    "responseMessage": "Invalid request."
}

The Bango Platform was unable to process the request. This indicates an implementation problem in your store code.

Testing
Prefer: status=400
401UNAUTHORIZEDIP address or access credentials are invalid
{
    "responseCode": "UNAUTHORIZED",
    "responseMessage": "Invalid access credentials."
}

The Bango Platform didn't process the request as the supplied credentials were invalid, or the request was not from an authorized IP address. This indicates an implementation problem in your store code or a configuration issue. See Bango Platform / Connectivity and security / Basic authentication and Bango Platform / Connectivity and security / IP whitelisting.

Testing
Prefer: status=401
404NOT_FOUNDSession ID invalid or expired
{
    "responseCode": "NOT_FOUND",
    "responseMessage": "Invalid session id or session expired."
}

The Bango Platform didn't process the request as the session ID was invalid or had expired.

Testing
Prefer: status=404
500INTERNAL_ERRORUnexpected server issue
{
    "responseCode": "INTERNAL_ERROR",
    "responseMessage": "The server encountered an unexpected condition."
}

The Bango Platform couldn't respond to the request. Your store should show a suitable message to the user.

Testing
Prefer: status=500
502CONNECT_ERRORUnexpected connection issue with identity provider
{
    "responseCode": "CONNECT_ERROR",
    "responseMessage": "Connection error submitting request to identity provider."
}

The Bango Platform couldn't respond to the request, as there was an issue connecting to an identity provider. Your store should show a suitable message to the user.

Testing
Prefer: status=502
preference-extension: responseCode=CONNECT_ERROR
502FAILUREUnexpected issue with identity provider
{
    "responseCode": "FAILURE",
    "responseMessage": "The identity provider returned an unspecified failure."
}

The Bango Platform couldn't respond to the request, as there was a failure with an identity provider. Your store should show a suitable message to the user.

Testing
Prefer: status=502
preference-extension: responseCode=FAILURE
503SERVICE_UNAVAILABLEBango Platform undergoing maintenance
{
    "responseCode": "SERVICE_UNAVAILABLE",
    "responseMessage": "The server is undergoing maintenance."
}

The Bango Platform is undergoing maintenance and is not currently available. The store should show a suitable message to the user and perhaps try again later.

Testing
Prefer: status=503
504CONNECT_TIMEOUTUnexpected timeout with identity provider
{
    "responseCode": "CONNECT_TIMEOUT",
    "responseMessage": "Connection timeout with identity provider."
}

The Bango Platform couldn't respond to the request, as the identity provider timed out. Your store should show a suitable message to the user.

Testing
Prefer: status=504

Get a user's Bango ID (subsequent requests)

POST https://api.bango.net/v5/identity/{sessionId}
Path parameters
sessionId string

The value of the sessionId parameter in the response to the initial request. Example: 9c7b9891-c871-4dd5-bdcc-ac25ff2412b7

Query parametersNone
Body parametersAlso all body parameters supported for the initial request
action string

Use cancel if the store cannot perform the CLIENT_ACTION_REQUIRED action specified in the previous response (for example, if the Bango Platform asked your store to send an SMS, and the user's device can't do that).

Sample requests
Cancel requested action
POST https://api.bango.net/v5/identity/9c7b9891-c871-4dd5-bdcc-ac25ff2412b7 HTTP/1.1

{
    "action": "cancel"
}

Tell the Bango Platform that the store can't perform the required action.

Supply a custom user identifier
POST https://api.bango.net/v5/identity/9c7b9891-c871-4dd5-bdcc-ac25ff2412b7 HTTP/1.1

{
    "thirdPartyUserId": "my-custom-id-abcde"
}

Update the Bango Platform with a custom user identifier.

Ask for current status
POST https://api.bango.net/v5/identity/9c7b9891-c871-4dd5-bdcc-ac25ff2412b7 HTTP/1.1

No body parameters: ask the Bango Platform for the current status of the identification session.

Response bodySame as the initial response
Copyright © 2000–2019 Bango.net Limited