Perform a business operation related to an identity token

curl --request POST \
  --url https://some-prod-tbd.bango.com/ns/{nsid}/identity/tokens/{rid}/actions \
  --header 'Authorization: Basic <encoded-value>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "type": "CANCEL",
  "payload": {}
}
'

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

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

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

response = requests.post(url, json=payload, headers=headers)

print(response.text)

{
  "rid": "9dd4ac2d-83f3-4cba-a534-14c37f07da34",
  "lastUpdate": "2023-03-14T15:54:00Z",
  "type": "payment-instrument-token",
  "state": "active",
  "merchantId": "AUSSIE_APPS",
  "paymentProviderId": "OGNABTEL",
  "paymentEligibilityStatus": "enabled",
  "accountType": "postpaid",
  "locale": "en-US",
  "customerProfile": "spending_limit_profile",
  "userProperties": {
    "token": "myUserToken",
    "accountNickname": 457,
    "specialProperty": {
      "key1": "value1"
    }
  }
}

Perform a business operation related to an identity token

Use this endpoint to ask the Bango Platform to perform a business operation related to an identity token. A business operation might be an update to the token, or a task associated with the token.

API consumers request business operations by sending actions to this endpoint. An action specifies the business operation. The Bango Platform decides whether the business operation is permitted, and if so it performs the business operation. This might result in a change to the resource’s properties, and might cause a side effect.

400 response error codes:

invalid-json if the request body isn’t valid JSON format
missing-parameter if type is not present in the request body
invalid-parameter if type is not a valid action type
missing-parameter if payload is required and not present
invalid-parameter if payload is not the expected shape for the type of action (which may mean that payload is missing required parameters or some parameters are invalid: check the documentation to find out the expected payload shape for each action type)

POST

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

{nsid}

identity

tokens

{rid}

actions

Perform a business operation related to an identity token

curl --request POST \
  --url https://some-prod-tbd.bango.com/ns/{nsid}/identity/tokens/{rid}/actions \
  --header 'Authorization: Basic <encoded-value>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "type": "CANCEL",
  "payload": {}
}
'

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

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

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

response = requests.post(url, json=payload, headers=headers)

print(response.text)

{
  "rid": "9dd4ac2d-83f3-4cba-a534-14c37f07da34",
  "lastUpdate": "2023-03-14T15:54:00Z",
  "type": "payment-instrument-token",
  "state": "active",
  "merchantId": "AUSSIE_APPS",
  "paymentProviderId": "OGNABTEL",
  "paymentEligibilityStatus": "enabled",
  "accountType": "postpaid",
  "locale": "en-US",
  "customerProfile": "spending_limit_profile",
  "userProperties": {
    "token": "myUserToken",
    "accountNickname": 457,
    "specialProperty": {
      "key1": "value1"
    }
  }
}

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"

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"

Body

application/json

A request to perform a business operation related to an identity token. A request specifies an action type and any action-specific data (the payload). The response is always the latest version of the identity token held in the Bango Platform.

The following action types are available. See each action type schema for detailed information.

CANCEL: A request to permanently disable a payment instrument token, with no possibility of undo
FETCH_ELIGIBILITY: A request to fetch eligibility information for the token from the downstream payment provider
VALIDATE_PASSPHRASE: A request to validate passphrase for the token from the downstream payment provider
GET_ACCOUNT: A request to retrieve the account information associated with a PIT

CANCEL action
FETCH_ELIGIBILITY action
VALIDATE_PASSPHRASE action
GET_ACCOUNT action

A request to permanently disable a payment instrument token, with no possibility of undo.

If the payment instrument token is already canceled, returns HTTP 409 with error code pit-already-canceled.

type

any

required

payload

object

required

Empty object

Response

The updated resource.

Identity token resource - CANCEL selected
Identity token resource - FETCH_ELIGIBILITY selected
Identity token resource- VALIDATE_PASSPHRASE selected
Identity token resource- GET_ACCOUNT selected

An identity token resource when CANCEL 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"

type

any

required

The type of token. Code can use type to infer the schema for the rest of the resource.

For now, only payment-instrument-token is supported. Other values may be supported in future.

state

enum<string>

required

The token state. Tokens of type payment-instrument-token are always one of:

active: may be used for payments, if eligible
canceled: may not be used for payments

The only permitted state transition is from active to canceled. To make this transition, send a CANCEL action. It is not possible to transition from canceled back to active.

Available options:

active,

canceled

merchantId

string

required

Friendly unique identifier for the merchant partner.

Internally, corresponds to the accountKey property in the route-config-server's partner_namespaces table.

Required string length: 2 - 50

Example:

"AUSSIE_APPS"

paymentProviderId

string

required

Friendly unique identifier for the payment provider.

Internally, corresponds to the accountKey property in the route-config-server's partner_namespaces table.

Required string length: 2 - 50

Example:

"OGNABTEL"

paymentEligibilityStatus

enum<string>

default:unknown

Information about the token related to payment processing.

discovering: The Bango Platform is currently waiting for a response from the payment provider about the token
enabled: Authorized partners can use the token to process payments
not-enabled: The payment provider has not enabled the token to process payments
closed: The payment provider has decided the token can no longer process payments (this is permanent)
barred: The payment provider has suspended or barred the user associated with the token (this may be temporary)
unknown: The payment provider has not provided information about this token
unsupported: The payment provider does not support requests for information about this token

Available options:

discovering,

enabled,

not-enabled,

closed,

barred,

unknown,

unsupported

accountType

enum<string>

The account type allocated by the payment provider for an end user's account.

Available options:

prepaid,

postpaid,

unknown

locale

string

A BCP 47 language tag representing the locale of the merchant end user, if known.

Required string length: 1 - 50

Examples:

"en-US"

"ar-SA"

customerProfile

string

Customer’s latest spending limit profile

userProperties

User specific properties · object

Properties that are specific to a user

Example:

{
  "userProperties": {
    "token": "myUserToken",
    "accountNickname": 457,
    "specialProperty": { "key1": "value1" }
  }
}

Bango Payments

For payment providers

For merchants

Perform a business operation related to an identity token

Authorizations

Path Parameters

Body

Response