1 User identification

Introduction

User identification can require one or more calls to the API depending on device capabilities and identification methods available.

Action	Possible responses
Initial request sent to https://api.bango.net/v5/identity Example request: { "deviceCapabilitySendSms": "true", "identificationMethodKey": "{identification-method-key-provided-by-Bango}", "callbackUrl": "{callback-url}", "notificationUrl": "{notification-URL}" }	URL redirect required No identification methods available Error returned from payment provider Bad Request (invalid request received from merchant) Connect Timeout Unauthorized Service unavailable Internal error Example reponse: { "responseCode": "OK", "responseMessage": "Success.", "sessionId": "{sessionId}", "parameters": { } }

If 2 or more calls are required to complete the identification process, the session id returned in the first response must be appended to the URL for any subsequent calls.

Action	Possible responses
Subsequent requests sent to https://api.bango.net/v5/identity/{sessionId}	URL redirect required User cancelled Wait No identification methods available Error returned from payment provider Bad Request (invalid request received from merchant) Not found (invalid session id) Unauthorized Service unavailable Internal error

We recommend testing that different sequences of responses can be handled.

For example a WAIT may be returned at any stage if a user action or payment provider response is pending.

Redirect via Bango MT flow

1.1 URL redirect via Bango MT flow, then user identified

Bango test details
identificationMethodKey	GBR_BANGO	This can be used to generate UserIds for non-redirect payment flow testing
identificationMethodKey	GBR_BANGOREDIRECT	This can be used to generate UserIds for redirect payment flow testing

Test	Action	Expected result
1	Send a valid POST request to https://api.bango.net/v5/identity Optional: include a notificationUrl to be notified when the user completes the redirect process. E.g. { "deviceCapabilitySendSms": "true", "identificationMethodKey": "{identification-method-key-provided-by-Bango}", "callbackUrl": "{callback-url}", "notificationUrl": "{notification-URL}" }	An HTTP response code 200 (OK) should be returned with the following body: { "responseCode": "CLIENT_ACTION_REQUIRED", "responseMessage": "An action is required in the client.", "sessionId": "{sessionId}", "bangoUserId": null, "parameters": { "action": "REDIRECT", "url": "{redirect-url}" } }
2	Send the user to the URL provided.	Bango identity flow: After the user has completed any manual actions required they should be sent to your specified "callbackUrl". The Bango API will also send a POST to the "notificationUrl" if one is provided in the initial request. { "bangoUserId": {bango-user-id}, "identificationSessionId": {identification-session-id} }
3	When the user has reached the return URL resend the POST request to https://api.bango.net/v5/identity/{sessionId}	An HTTP response code 200 (OK) should be returned with the following body: { "responseCode": "OK", "responseMessage": "Success.", "sessionId": "{sessionId}", "bangoUserId": "123456789", "parameters": { } }

1.2 User cancels during redirect flow

Test

Action

Expected result

1

Send a valid POST request to https://api.bango.net/v5/identity

E.g.

{
   "deviceCapabilitySendSms": "true",
   "identificationMethodKey": "{identification-method-key-provided-by-Bango}",
   "callbackUrl": "http://your.callback.url",
   "notificationUrl": "{notification-URL}"
}

An HTTP response code 200 (OK) should be returned with the following body:

{
    "responseCode": "CLIENT_ACTION_REQUIRED",
    "responseMessage": "An action is required in the client.",
    "sessionId": "{sessionId}",
    "bangoUserId": null,
    "parameters": 
    {
        "action": "REDIRECT",
        "url": "{redirect-url}"
    }
}

2

User cancels during redirect flow

User cancels on Bango Enter mobile number page:

User cancels on Bango Enter PIN page:

User redirected to the callback URL

3

Resend POST request to https://api.bango.net/v5/identity/{sessionId}

An HTTP response code 202 (Accepted) should be returned with the following body:

{
  "responseCode": "USER_CANCELLED",
  "responseMessage": "The user cancelled the identification flow.",
  "sessionId": "9c7b9891-c871-4dd5-bdcc-ac25ff2412b7",
  "bangoUserId": null,
  "parameters": {}
}

1.3 User does not return from URL redirect

This scenario could be caused by the user closing their browser or experiencing network connectivity issues.

Test

Action

Expected result

1

Send a valid POST request to https://api.bango.net/v5/identity

E.g.

{
   "deviceCapabilitySendSms": "true",
   "identificationMethodKey": "{identification-method-key-provided-by-Bango}",
   "callbackUrl": "http://your.callback.url",
   "notificationUrl": "{notification-URL}"
}

An HTTP response code 200 (OK) should be returned with the following body:

{
    "responseCode": "CLIENT_ACTION_REQUIRED",
    "responseMessage": "An action is required in the client.",
    "sessionId": "{sessionId}",
    "bangoUserId": null,
    "parameters": 
    {
        "action": "REDIRECT",
        "url": "{redirect-url}"
    }
}

2

Resend POST request to https://api.bango.net/v5/identity/{sessionId}

An HTTP response code 200 (OK should be returned with the following body:

{
    "responseCode": "CLIENT_ACTION_REQUIRED",
    "responseMessage": "An action is required in the client.",
    "sessionId": "{sessionId}", 
    "bangoUserId": null,
    "parameters":
    {
        "action": "WAIT"
        "suggestedWaitTimeMilliseconds": "3600"
    }
}

3

Test that different sequences of responses can be handled in subsequent POST requests to https://api.bango.net/v5/identity/{sessionId} including 'NOT_AVAILABLE'.

Redirect via Header enrichment URL

1.4 URL redirect via Operator for header enrichment, then user identified

Bango test details
identificationMethodKey	GBR_BANGO	This can be used to generate UserIds for non-redirect payment flow testing
identificationMethodKey	GBR_BANGOREDIRECT	This can be used to generate UserIds for redirect payment flow testing

Test	Action	Expected result
1	Send a valid POST request to https://api.bango.net/v5/identity Optional: include a notificationUrl to be notified when the user completes the redirect process. E.g. { "deviceCapabilitySendSms": "true", "identificationMethodKey": "{identification-method-key-provided-by-Bango}", "callbackUrl": "{callback-url}", "notificationUrl": "{notification-URL}" }	An HTTP response code 200 (OK) should be returned with the following body: { "responseCode": "CLIENT_ACTION_REQUIRED", "responseMessage": "An action is required in the client.", "sessionId": "{sessionId}", "bangoUserId": null, "parameters": { "action": "REDIRECT", "url": "{redirect-url}" } }
2	Send the user to the URL provided.	Bango identity flow: After the user has completed any manual actions required they should be sent to your specified "callbackUrl". The Bango API will also send a POST to the "notificationUrl" if one is provided in the initial request. { "bangoUserId": {bango-user-id}, "identificationSessionId": {identification-session-id} }
3	When the user has reached the return URL resend the POST request to https://api.bango.net/v5/identity/{sessionId}	An HTTP response code 200 (OK) should be returned with the following body: { "responseCode": "OK", "responseMessage": "Success.", "sessionId": "{sessionId}", "bangoUserId": "123456789", "parameters": { } }

1.5 User does not return from identification provider during URL redirect

Test

Action

Expected result

1

Send a valid POST request to https://api.bango.net/v5/identity

E.g.

{
   "deviceCapabilitySendSms": "true",
   "identificationMethodKey": "{identification-method-key-provided-by-Bango}",
   "callbackUrl": "http://your.callback.url",
   "notificationUrl": "{notification-URL}"
}

An HTTP response code 200 (OK) should be returned with the following body:

{
    "responseCode": "CLIENT_ACTION_REQUIRED",
    "responseMessage": "An action is required in the client.",
    "sessionId": "{sessionId}",
    "bangoUserId": null,
    "parameters": 
    {
        "action": "REDIRECT",
        "url": "{redirect-url}"
    }
}

2

Resend POST request to https://api.bango.net/v5/identity/{sessionId}

An HTTP response code 200 (OK) should be returned with the following body:

{
    "responseCode": "CLIENT_ACTION_REQUIRED",
    "responseMessage": "An action is required in the client.",
    "sessionId": "{sessionId}", 
    "bangoUserId": null,
    "parameters":
    {
        "action": "WAIT"
        "suggestedWaitTimeMilliseconds": "3600"
    }
}

3

Test that different sequences of responses can be handled in subsequent POST requests to https://api.bango.net/v5/identity/{sessionId} including 'NOT_AVAILABLE'.

1.6 User not identified

This scenario can be tested using Prefer Headers.

Test

Action

Expected result

1

Send a valid POST request to https://api.bango.net/v5/identity

E.g.

{
   "deviceCapabilitySendSms": "true",
   "identificationMethodKey": "{identification-method-key-provided-by-Bango}",
   "callbackUrl": "http://your.callback.url",
   "notificationUrl": "{notification-URL}"
}

An HTTP response code 200 (OK) should be returned with the following body:

{
    "responseCode": "CLIENT_ACTION_REQUIRED",
    "responseMessage": "An action is required in the client.",
    "sessionId": "{sessionId}",
    "bangoUserId": null,
    "parameters": 
    {
        "action": "REDIRECT",
        "url": "{redirect-url}"
    }
}

2

Resend POST request to https://api.bango.net/v5/identity/{sessionId}

Include the following headers in the request:

Prefer:status=502
preference-extension:responseCode=FAILURE

An HTTP response code 502 (FAILURE) should be returned with the following body:

{
    "responseCode": "FAILURE",
    "responseMessage": "The identity provider returned an unspecified failure."
}

General failure scenarios

1.7 No identification methods available

Test

Action

Expected result

1

Send a valid POST request to https://api.bango.net/v5/identity with an invalid identificationMethodKey

E.g.

{
   "deviceCapabilitySendSms": "true",
   "identificationMethodKey": "{invalid-identification-method-key}",
   "callbackUrl": "http://your.callback.url",
   "notificationUrl": "{notification-URL}"
}

An HTTP response code 202 (Accepted) should be returned with the following body:

{
    "responseCode": "NOT_AVAILABLE",
    "responseMessage": "Invalid Identification Method Key.",
    "parameters": {},
    "sessionId": null,
    "bangoUserId": null
}

1.8 Invalid sessionId or session expired

Test

Action

Expected result

1

Send a valid POST request to https://api.bango.net/v5/identity

E.g.

{
   "deviceCapabilitySendSms": "true",
   "identificationMethodKey": "{identification-method-key-provided-by-Bango}",
   "callbackUrl": "http://your.callback.url",
   "notificationUrl": "{notification-URL}"
}

An HTTP response code 200 (OK) should be returned with the following body:

{
    "responseCode": "CLIENT_ACTION_REQUIRED",
    "responseMessage": "An action is required in the client.",
    "sessionId": "{sessionId}",
    "bangoUserId": null,
    "parameters": 
    {
        "action": "REDIRECT",
        "url": "{redirect-url}"
    }
}

2

Resend POST request with an invalid sessionId to https://api.bango.net/v5/identity/{invalid-sessionId}

An HTTP response code 200 (OK should be returned with the following body:

{
  "responseCode": "NOT_FOUND",
  "responseMessage": "Invalid session id or session expired."
}

1.9 Error response from identity provider

This scenario can be tested using Prefer Headers.

Test

Action

Expected result

1

Send a valid POST request to https://api.bango.net/v5/identity

E.g.

{
   "deviceCapabilitySendSms": "true",
   "identificationMethodKey": "{identification-method-key-provided-by-Bango}",
   "callbackUrl": "http://your.callback.url",
   "notificationUrl": "{notification-URL}"
}

Include the following headers in the request:

Prefer:status=502
preference-extension:responseCode=FAILURE

An HTTP response code 202 (Accepted) should be returned with the following body:

{ 
    "responseCode": "FAILURE", 
    "responseMessage": "The identity provider returned an unspecified failure",
}

1.10 Connect error

This scenario can be tested using Prefer Headers.

Test

Action

Expected result

1

Send a valid POST request to https://api.bango.net/v5/identity

E.g.

{
   "identificationMethodKey": "{identification-method-key-provided-by-Bango}",
   "callbackUrl": "http://your.callback.url",
   "notificationUrl": "{notification-URL}"
}

Include the following headers in the request:

Prefer:status=502
preference-extension:responseCode=CONNECT_ERROR

An HTTP response code 502 (Connect error) should be returned with the following body:

{
  "responseCode": "CONNECT_ERROR",
  "responseMessage": "Connection error submitting the identification 
request to the identity provider."
}

1.11 Connect timeout

This scenario can be tested using Prefer Headers.

Test

Action

Expected result

1

Send a valid POST request to https://api.bango.net/v5/identity

E.g.

{
   "identificationMethodKey": "{identification-method-key-provided-by-Bango}",
   "callbackUrl": "http://your.callback.url",
   "notificationUrl": "{notification-URL}"
}

Include the following header in the request:

Prefer:status=504

An HTTP response code 502 (Connect timeout) should be returned with the following body:

{
  "responseCode": "CONNECT_TIMEOUT",
  "responseMessage": "Connection timeout submitting the identification 
request to the identity provider."
}

1.12 Unauthorized

This scenario can be tested using Prefer Headers.

Test	Action	Expected result
1	Send a valid POST request to https://api.bango.net/v5/identity E.g. { "identificationMethodKey": "{identification-method-key-provided-by-Bango}", "callbackUrl": "http://your.callback.url", "notificationUrl": "{notification-URL}" } Option 1: Include the following header in the request: Prefer:status=401 Option 2: Include the following header in the request: Authorization:{unauthorised base64 encoded string}	An HTTP response code 401 (Connect error) should be returned with the following body: { "responseCode": "UNAUTHORIZED", "responseMessage": "Invalid access credentials." }

1.13 Service unavailable

This scenario can be tested using Prefer Headers.

Test

Action

Expected result

1

Send a valid POST request to https://api.bango.net/v5/identity

E.g.

{
   "identificationMethodKey": "{identification-method-key-provided-by-Bango}",
   "callbackUrl": "http://your.callback.url",
   "notificationUrl": "{notification-URL}"
}

Include the following header in the request:

Prefer:status=503

An HTTP response code 502 (Connect error) should be returned with the following body:

{
  "responseCode": "SERVICE_UNAVAILABLE",
  "responseMessage": "The server is undergoing maintenance and is not 
available. Please, try again later."
}

1.14 Internal error

This scenario can be tested using Prefer Headers.

Test

Action

Expected result

1

Send a valid POST request to https://api.bango.net/v5/identity

E.g.

{
   "identificationMethodKey": "{identification-method-key-provided-by-Bango}",
   "callbackUrl": "http://your.callback.url",
   "notificationUrl": "{notification-URL}"
}

Include the following header in the request:

Prefer:status=500

An HTTP response code 502 (Connect error) should be returned with the following body:

{
  "responseCode": "INTERNAL_ERROR",
  "responseMessage": "The server encountered an unexpected condition 
which prevented it from fulfilling the request."
}