Retrieve an identity verification session

curl --request GET \
  --url https://some-prod-tbd.bango.com/ns/{nsid}/identity/verifications/{ridOrAlias} \
  --header 'Authorization: Basic <encoded-value>'

const options = {method: 'GET', headers: {Authorization: 'Basic <encoded-value>'}};

fetch('https://some-prod-tbd.bango.com/ns/{nsid}/identity/verifications/{ridOrAlias}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://some-prod-tbd.bango.com/ns/{nsid}/identity/verifications/{ridOrAlias}"

headers = {"Authorization": "Basic <encoded-value>"}

response = requests.get(url, headers=headers)

print(response.text)

{
  "rid": "581b2e40-741c-4683-ae66-46c9fe6f4d5e",
  "lastUpdate": "2022-12-21T08:59:32Z",
  "flow": "none",
  "state": "authorizing",
  "partnerSessionId": "e9342a9f-ff3f-44ad-8e30-8a6f9a820060",
  "private": {
    "partnerCustomerId": "6789812A",
    "OTHER": "<unknown>"
  },
  "shared": {
    "nextAction": "none",
    "merchantToPaymentProvider": {
      "authSuccessRedirectUrl": "https://example.com/merchant/user-login-ok",
      "authFailureRedirectUrl": "https://example.com/merchant/user-login-failed"
    },
    "paymentProviderToMerchant": {
      "authRedirectUrl": "https://example.com/payment-provider/login"
    }
  },
  "result": {
    "code": "token-created",
    "reasons": [
      {
        "code": "missing-parameter",
        "meta": {
          "param": "<string>"
        },
        "message": "A required parameter was missing from the request",
        "url": "https://developer.bango.com/error-codes/missing-parameter"
      }
    ]
  }
}

{
  "errors": [
    {
      "code": "invalid-credentials",
      "meta": {},
      "message": "The supplied credentials are not valid",
      "url": "https://developer.bango.com/error-codes/invalid-credentials"
    }
  ]
}

{
  "errors": [
    {
      "code": "permission-denied",
      "meta": {},
      "message": "The client is not permitted to perform this operation",
      "url": "https://developer.bango.com/error-codes/permission-denied"
    }
  ]
}

{
  "errors": [
    {
      "code": "not-found",
      "meta": {},
      "message": "The requested resource was not found",
      "url": "https://developer.bango.com/error-codes/not-found"
    }
  ]
}

{
  "errors": [
    {
      "code": "too-many-requests",
      "meta": {},
      "message": "Request limit reached. Please try again later",
      "url": "https://developer.bango.com/error-codes/too-many-requests"
    }
  ]
}

{
  "errors": [
    {
      "code": "internal-server-error",
      "meta": {
        "canRetry": true
      },
      "message": "The server encountered an unexpected condition which prevented it from fulfilling the request",
      "url": "https://developer.bango.com/error-codes/internal-server-error"
    }
  ]
}

{
  "errors": [
    {
      "code": "service-unavailable",
      "meta": {},
      "message": "The service is undergoing maintenance and is not available. Please try again later",
      "url": "https://developer.bango.com/error-codes/service-unavailable"
    }
  ]
}

Retrieve an identity verification session

Use this endpoint to retrieve an identity verification session. The flow property of the session describes the selected identity verification flow, if any. The state property describes the current state of the session, and this may change over time. Partners can poll a session regularly to track asynchronous processes managed by the Bango Platform, such as sending messages to an end user’s device through a payment provider’s SMS service.

To poll, partners can:

Use the rid of the session: this is a unique identifier (UUID v4) created by the Bango Platform
Use an alias for the rid, for example partnerSessionId:fhie857jfskgiei. (The Bango Platform creates this alias automatically if the partner specifies a partnerSessionId when creating the session)

GET

https://some-prod-tbd.bango.com

{nsid}

identity

verifications

{ridOrAlias}

Retrieve an identity verification session

curl --request GET \
  --url https://some-prod-tbd.bango.com/ns/{nsid}/identity/verifications/{ridOrAlias} \
  --header 'Authorization: Basic <encoded-value>'

const options = {method: 'GET', headers: {Authorization: 'Basic <encoded-value>'}};

fetch('https://some-prod-tbd.bango.com/ns/{nsid}/identity/verifications/{ridOrAlias}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://some-prod-tbd.bango.com/ns/{nsid}/identity/verifications/{ridOrAlias}"

headers = {"Authorization": "Basic <encoded-value>"}

response = requests.get(url, headers=headers)

print(response.text)

{
  "rid": "581b2e40-741c-4683-ae66-46c9fe6f4d5e",
  "lastUpdate": "2022-12-21T08:59:32Z",
  "flow": "none",
  "state": "authorizing",
  "partnerSessionId": "e9342a9f-ff3f-44ad-8e30-8a6f9a820060",
  "private": {
    "partnerCustomerId": "6789812A",
    "OTHER": "<unknown>"
  },
  "shared": {
    "nextAction": "none",
    "merchantToPaymentProvider": {
      "authSuccessRedirectUrl": "https://example.com/merchant/user-login-ok",
      "authFailureRedirectUrl": "https://example.com/merchant/user-login-failed"
    },
    "paymentProviderToMerchant": {
      "authRedirectUrl": "https://example.com/payment-provider/login"
    }
  },
  "result": {
    "code": "token-created",
    "reasons": [
      {
        "code": "missing-parameter",
        "meta": {
          "param": "<string>"
        },
        "message": "A required parameter was missing from the request",
        "url": "https://developer.bango.com/error-codes/missing-parameter"
      }
    ]
  }
}

{
  "errors": [
    {
      "code": "invalid-credentials",
      "meta": {},
      "message": "The supplied credentials are not valid",
      "url": "https://developer.bango.com/error-codes/invalid-credentials"
    }
  ]
}

{
  "errors": [
    {
      "code": "permission-denied",
      "meta": {},
      "message": "The client is not permitted to perform this operation",
      "url": "https://developer.bango.com/error-codes/permission-denied"
    }
  ]
}

{
  "errors": [
    {
      "code": "not-found",
      "meta": {},
      "message": "The requested resource was not found",
      "url": "https://developer.bango.com/error-codes/not-found"
    }
  ]
}

{
  "errors": [
    {
      "code": "too-many-requests",
      "meta": {},
      "message": "Request limit reached. Please try again later",
      "url": "https://developer.bango.com/error-codes/too-many-requests"
    }
  ]
}

{
  "errors": [
    {
      "code": "internal-server-error",
      "meta": {
        "canRetry": true
      },
      "message": "The server encountered an unexpected condition which prevented it from fulfilling the request",
      "url": "https://developer.bango.com/error-codes/internal-server-error"
    }
  ]
}

{
  "errors": [
    {
      "code": "service-unavailable",
      "meta": {},
      "message": "The service is undergoing maintenance and is not available. Please try again later",
      "url": "https://developer.bango.com/error-codes/service-unavailable"
    }
  ]
}

Authorizations

Authorization

string

header

required

Basic authentication header of the form Basic <encoded-value>, where <encoded-value> is the base64-encoded string username:password.

Path Parameters

nsid

string<uuid>

required

Globally unique namespace ID. These IDs are opaque, not guessable, and not sequential.

Bango provides each Bango partner with a unique set of resource URIs. All resource URI paths start with /ns/{nsid}, where {nsid} is the namespace ID. No other Bango partner shares this namespace. Partner credentials permit access only to URIs with this namespace.

Example:

"673c74de-ce5b-4f79-9851-2544d1d836cb"

ridOrAlias

required

Globally unique resource ID. These IDs are opaque, not guessable, and not sequential.

Each individual resource in a partner's namespace has a unique identifier: this is the identifier immediately after the resource type in the URI path.

For example, in the URI /ns/673c74de-ce5b-4f79-9851-2544d1d836cb/elephants/581b2e40-741c-4683-ae66-46c9fe6f4d5e:

The namespace id is 673c74de-ce5b-4f79-9851-2544d1d836cbde
elephants indicates the resource type is elephant
The resource id is 581b2e40-741c-4683-ae66-46c9fe6f4d5e

Every resource has a read-only property rid that contains the resource ID, for convenience.

Example:

"581b2e40-741c-4683-ae66-46c9fe6f4d5e"

Response

Resource found

Identity verification session - no flow selected
Identity verification session - Trusted flow selected
Identity verification session - Negotiated flow selected
Identity verification session - MO flow selected
Identity verification session - MT flow selected

An identity verification session when no flow has been selected.

rid

string<uuid>

required

Globally unique resource ID. These IDs are opaque, not guessable, and not sequential.

Each individual resource in a partner's namespace has a unique identifier: this is the identifier immediately after the resource type in the URI path.

For example, in the URI /ns/673c74de-ce5b-4f79-9851-2544d1d836cb/elephants/581b2e40-741c-4683-ae66-46c9fe6f4d5e:

The namespace id is 673c74de-ce5b-4f79-9851-2544d1d836cbde
elephants indicates the resource type is elephant
The resource id is 581b2e40-741c-4683-ae66-46c9fe6f4d5e

Every resource has a read-only property rid that contains the resource ID, for convenience.

Example:

"581b2e40-741c-4683-ae66-46c9fe6f4d5e"

lastUpdate

string<date-time>

required

RFC 3339 datetime of the last update to this resource

Example:

"2022-12-21T08:59:32Z"

flow

any

required

No flow has been selected

state

enum<string>

required

Describes the state of the resource when no flow has been selected.

state is one of:

authorizing - the Bango Platform is checking for permission to create the session
new - the session is created and the Bango Platform is ready for the partner to select a flow
failed - the Bango Platform has denied the request to create the session
closed - the partner has decided to cancel the session without selecting a flow

Typically partners see only new. authorizing is very short-lived, failed is possible but unlikely, and closed is only entered at the partner's request.

Available options:

authorizing,

new,

failed,

closed

partnerSessionId

string

A session ID supplied by the partner. This is assumed to be unique across all the partner's identity verification sessions.

Minimum string length: 1

Example:

"e9342a9f-ff3f-44ad-8e30-8a6f9a820060"

private

object

A place for the merchant partner to store private data related to the identity verification session. Once the payment instrument token is generated, this data is associated with the token.

Merchant partners can initialize the data when creating a session, and can patch this data later when starting a flow or using an UPDATE_SESSION_DATA action.

Supports any data (constraints TBD). This schema defines some commonly used properties.

Show child attributes

shared

Shared identity verification session properties · object

Data shared between the merchant partner and the payment provider as part of an identity verification session.

Show child attributes

result

Action result, if any · object

The result of the most recent action. There are three outcomes for an action:

The action was performed and completed with a positive outcome
The action was performed and completed with a negative outcome
The action was not performed because a required constraint was not met

The result code indicates which outcome applied and is always a string in lower-kebab-case.

The result reasons indicates any additional explanations available for the outcome (outcomes 2 and 3 above). For outcome 1 above, reasons is an empty array.

Show child attributes

Bango Payments

For payment providers

For merchants

Retrieve an identity verification session

Authorizations

Path Parameters

Response