Create an identity verification session

curl --request POST \
  --url https://some-prod-tbd.bango.com/ns/{nsid}/identity/verifications \
  --header 'Authorization: Basic <encoded-value>' \
  --header 'Content-Type: application/json' \
  --data '{}'

const options = {
  method: 'POST',
  headers: {Authorization: 'Basic <encoded-value>', 'Content-Type': 'application/json'},
  body: JSON.stringify({})
};

fetch('https://some-prod-tbd.bango.com/ns/{nsid}/identity/verifications', 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"

payload = {}
headers = {
    "Authorization": "Basic <encoded-value>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, 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-json",
      "meta": {},
      "message": "The request body is not valid JSON",
      "url": "https://developer.bango.com/error-codes/invalid-json"
    }
  ]
}

{
  "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"
    }
  ]
}

Create an identity verification session

Use this endpoint to create an identity verification session. API consumers use this session to authenticate/verify the end user and obtain a Payment Instrument Token for them.

Include the action property to send an action immediately after the session is created.

400 response error codes:

invalid-json if the request body isn’t valid JSON format
missing-parameter for any mandatory parameter missing from the request body
invalid-parameter for any parameter that’s syntactically or semantically incorrect. For example:
- If this specification defines a parameter as a string, and an array of strings is supplied
- If this specification defines a parameter as a datetime, and an invalid datetime is supplied
- If parameters should be in a particular order (eg chronological datetimes) and they aren’t

POST

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

{nsid}

identity

verifications

Create an identity verification session

curl --request POST \
  --url https://some-prod-tbd.bango.com/ns/{nsid}/identity/verifications \
  --header 'Authorization: Basic <encoded-value>' \
  --header 'Content-Type: application/json' \
  --data '{}'

const options = {
  method: 'POST',
  headers: {Authorization: 'Basic <encoded-value>', 'Content-Type': 'application/json'},
  body: JSON.stringify({})
};

fetch('https://some-prod-tbd.bango.com/ns/{nsid}/identity/verifications', 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"

payload = {}
headers = {
    "Authorization": "Basic <encoded-value>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, 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-json",
      "meta": {},
      "message": "The request body is not valid JSON",
      "url": "https://developer.bango.com/error-codes/invalid-json"
    }
  ]
}

{
  "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"

Body

application/json

Data needed to create an identity verification session.

Partners can optionally include an action property. If present, the Bango Platform processes the action immediately after a successful session creation.

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

Data shared betweeen merchant and payment provider · object

Initial details of the negotiation between the merchant partner and the payment provider, from the merchant partner's perspective

Show child attributes

action

START_TRUSTED_FLOW action · object

Optional action to send immediately after a successful resource creation.

START_TRUSTED_FLOW action
START_NEGOTIATED_FLOW action
START_MO_FLOW action
START_MT_FLOW action
CANCEL_SESSION action [plan-later]

Show child attributes

Response

Resource created.

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

Create an identity verification session

Authorizations

Path Parameters

Body

Response