> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bango.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Retrieve information about an identity token

> Use this endpoint to retrieve information about an identity token.

This contains cached eligibility information that might be out of date. To fetch the latest information, send the `FETCH_ELIGIBILITY` action to the resource (response time will increase, as the Bango Platform fetches the latest information from the downstream payment provider).




## OpenAPI

````yaml /openapi/current/dcb-payments/merchant-to-bango/identity-token/openapi.yaml get /ns/{nsid}/identity/tokens/{rid}
openapi: 3.1.0
info:
  title: Bango Identity Token API
  version: 1.0.{build_number}
  contact:
    name: Bango Support
    url: https://developer.bango.com
    email: support@bango.com
servers:
  - url: https://some-prod-tbd.bango.com
    description: Production server
security:
  - BasicAuth: []
tags:
  - name: env-production
    description: Currently deployed to prod env
  - name: plan-later
    description: Not yet planned
paths:
  /ns/{nsid}/identity/tokens/{rid}:
    get:
      tags:
        - env-production
      summary: Retrieve information about an identity token
      description: >
        Use this endpoint to retrieve information about an identity token.


        This contains cached eligibility information that might be out of date.
        To fetch the latest information, send the `FETCH_ELIGIBILITY` action to
        the resource (response time will increase, as the Bango Platform fetches
        the latest information from the downstream payment provider).
      operationId: identity-token-get
      parameters:
        - $ref: '#/components/parameters/NamespaceId'
        - $ref: '#/components/parameters/ResourceId'
      responses:
        '200':
          description: Resource found
          content:
            application/vnd.bango.identity.token.v1+json:
              schema:
                $ref: '#/components/schemas/BasicProperties'
              example:
                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: prepaid
                locale: en-US
                userProperties:
                  token: myUserToken
                  accountNickname: 457
                  specialProperty:
                    key1: value1
                customerProfile: spending_limit_profile
        '401':
          $ref: '#/components/responses/InvalidCredentialsErrorResponse'
        '403':
          $ref: '#/components/responses/PermissionDeniedErrorResponse'
        '404':
          $ref: '#/components/responses/NotFoundErrorResponse'
        '429':
          $ref: '#/components/responses/TooManyRequestsErrorResponse'
        '500':
          $ref: '#/components/responses/InternalServerErrorResponse'
        '503':
          $ref: '#/components/responses/ServiceUnavailableErrorResponse'
components:
  parameters:
    NamespaceId:
      in: path
      name: nsid
      required: true
      schema:
        $ref: '#/components/schemas/namespace-id'
    ResourceId:
      in: path
      name: rid
      required: true
      schema:
        $ref: '#/components/schemas/resource-id'
  schemas:
    BasicProperties:
      properties:
        rid:
          $ref: '#/components/schemas/resource-id'
        lastUpdate:
          type: string
          format: date-time
          description: |
            RFC 3339 datetime of the last update to this resource
          example: '2022-12-21T08:59:32Z'
        type:
          const: payment-instrument-token
          description: >
            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:
          type: string
          enum:
            - active
            - canceled
          description: >
            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`.
        merchantId:
          $ref: '#/components/schemas/merchant-id'
        paymentProviderId:
          $ref: '#/components/schemas/payment-provider-id'
        paymentEligibilityStatus:
          type: string
          enum:
            - discovering
            - enabled
            - not-enabled
            - closed
            - barred
            - unknown
            - unsupported
          description: >
            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
          default: unknown
        accountType:
          $ref: '#/components/schemas/payment-provider-account-type'
        locale:
          $ref: '#/components/schemas/locale-bcp-47'
          description: >
            A [BCP 47](https://en.wikipedia.org/wiki/IETF_language_tag) language
            tag representing the locale of the merchant end user, if known.
        customerProfile:
          type: string
          description: |
            Customer’s latest spending limit profile
        userProperties:
          $ref: '#/components/schemas/userProperties'
      required:
        - rid
        - lastUpdate
        - type
        - state
        - merchantId
        - paymentProviderId
    namespace-id:
      title: Namespace ID
      description: >
        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.
      type: string
      format: uuid
      example: 673c74de-ce5b-4f79-9851-2544d1d836cb
    resource-id:
      title: Resource ID
      description: >
        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.
      type: string
      format: uuid
      example: 581b2e40-741c-4683-ae66-46c9fe6f4d5e
    merchant-id:
      title: Merchant ID
      description: >
        Friendly unique identifier for the merchant partner.


        Internally, corresponds to the `accountKey` property in the
        route-config-server's partner_namespaces table.
      x-bango-public-description: |
        Friendly unique identifier for the merchant partner.
      type: string
      example: AUSSIE_APPS
      minLength: 2
      maxLength: 50
    payment-provider-id:
      title: Payment provider ID
      description: >
        Friendly unique identifier for the payment provider.


        Internally, corresponds to the `accountKey` property in the
        route-config-server's partner_namespaces table.
      x-bango-public-description: |
        Friendly unique identifier for the payment provider.
      type: string
      example: OGNABTEL
      minLength: 2
      maxLength: 50
    payment-provider-account-type:
      title: Payment provider account type
      description: >
        The account type allocated by the payment provider for an end user's
        account.
      type: string
      enum:
        - prepaid
        - postpaid
        - unknown
    locale-bcp-47:
      title: BCP 47 language tag
      description: >
        A [BCP 47](https://en.wikipedia.org/wiki/IETF_language_tag) language
        tag.
      type: string
      minLength: 1
      maxLength: 50
      examples:
        - en-US
        - ar-SA
    userProperties:
      title: User specific properties
      description: |
        Properties that are specific to a user
      type: object
      example:
        userProperties:
          token: myUserToken
          accountNickname: 457
          specialProperty:
            key1: value1
    InvalidCredentials:
      allOf:
        - $ref: '#/components/schemas/CommonErrorResponse'
        - properties:
            errors:
              type: array
              items:
                oneOf:
                  - $ref: '#/components/schemas/invalid-credentials'
    PermissionDenied:
      allOf:
        - $ref: '#/components/schemas/CommonErrorResponse'
        - properties:
            errors:
              type: array
              items:
                oneOf:
                  - $ref: '#/components/schemas/permission-denied'
    NotFound:
      allOf:
        - $ref: '#/components/schemas/CommonErrorResponse'
        - properties:
            errors:
              type: array
              items:
                oneOf:
                  - $ref: '#/components/schemas/not-found'
    TooManyRequests:
      allOf:
        - $ref: '#/components/schemas/CommonErrorResponse'
        - properties:
            errors:
              type: array
              items:
                oneOf:
                  - $ref: '#/components/schemas/too-many-requests'
    InternalServerError:
      allOf:
        - $ref: '#/components/schemas/CommonErrorResponse'
        - properties:
            errors:
              type: array
              items:
                oneOf:
                  - $ref: '#/components/schemas/internal-server-error'
    ServiceUnavailable:
      allOf:
        - $ref: '#/components/schemas/CommonErrorResponse'
        - properties:
            errors:
              type: array
              items:
                oneOf:
                  - $ref: '#/components/schemas/service-unavailable'
    CommonErrorResponse:
      type: object
      required:
        - errors
    invalid-credentials:
      title: invalid-credentials
      description: Authentication error - invalid credentials
      type: object
      properties:
        code:
          const: invalid-credentials
        meta:
          description: >-
            Additional information to help identify the specific error case
            (empty in this case)
          type: object
        message:
          description: Human-readable message describing the error
          type: string
          example: The supplied credentials are not valid
        url:
          description: URL to more information about the error type
          type: string
          format: url
          example: https://developer.bango.com/error-codes/invalid-credentials
      required:
        - code
        - meta
        - message
    permission-denied:
      title: permission-denied
      description: Authorization error - permission denied
      type: object
      properties:
        code:
          const: permission-denied
        meta:
          description: >-
            Additional information to help identify the specific error case
            (empty in this case)
          type: object
        message:
          description: Human-readable message describing the error
          type: string
          example: The client is not permitted to perform this operation
        url:
          description: URL to more information about the error type
          type: string
          format: url
          example: https://developer.bango.com/error-codes/permission-denied
      required:
        - code
        - meta
        - message
    not-found:
      title: not-found
      description: Not found or access denied
      type: object
      properties:
        code:
          const: not-found
        meta:
          description: >-
            Additional information to help identify the specific error case
            (empty in this case)
          type: object
        message:
          description: Human-readable message describing the error
          type: string
          example: The requested resource was not found
        url:
          description: URL to more information about the error type
          type: string
          format: url
          example: https://developer.bango.com/error-codes/not-found
      required:
        - code
        - meta
        - message
    too-many-requests:
      title: too-many-requests
      description: Too many requests
      type: object
      properties:
        code:
          const: too-many-requests
        meta:
          description: >-
            Additional information to help identify the specific error case
            (empty in this case)
          type: object
        message:
          description: Human-readable message describing the error
          type: string
          example: Request limit reached. Please try again later
        url:
          description: URL to more information about the error type
          type: string
          format: url
          example: https://developer.bango.com/error-codes/too-many-requests
      required:
        - code
        - meta
        - message
    internal-server-error:
      title: internal-server-error
      description: Internal server error
      type: object
      properties:
        code:
          const: internal-server-error
        meta:
          description: Additional information to help identify the specific error case
          type: object
          properties:
            canRetry:
              description: Whether the request can be retried
              type: boolean
              default: true
        message:
          description: Human-readable message describing the error
          type: string
          example: >-
            The server encountered an unexpected condition which prevented it
            from fulfilling the request
        url:
          description: URL to more information about the error type
          type: string
          format: url
          example: https://developer.bango.com/error-codes/internal-server-error
      required:
        - code
        - meta
        - message
    service-unavailable:
      title: service-unavailable
      description: Service is unavailable
      type: object
      properties:
        code:
          const: service-unavailable
        meta:
          description: >-
            Additional information to help identify the specific error case
            (empty in this case)
          type: object
        message:
          description: Human-readable message describing the error
          type: string
          example: >-
            The service is undergoing maintenance and is not available. Please
            try again later
        url:
          description: URL to more information about the error type
          type: string
          format: url
          example: https://developer.bango.com/error-codes/service-unavailable
      required:
        - code
        - meta
        - message
  responses:
    InvalidCredentialsErrorResponse:
      description: |
        Authentication error - invalid credentials
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/InvalidCredentials'
    PermissionDeniedErrorResponse:
      description: >
        User is not authorized for this operation.


        This error occurs when you try to perform an operation on a resource,
        and you have permission to access the resource - but you don't have
        permission to perform the operation. For example, you may be authorized
        to `GET` the resource but not update it.


        (If you try to perform any operation on a resource you're not authorized
        to access, the API returns a 404 error.)
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/PermissionDenied'
    NotFoundErrorResponse:
      description: >
        The requested resource was not found or access was denied.


        The API returns an identical error in both scenarios for data privacy
        reasons: API consumers can't find out anything about resources they
        aren't authorized to access.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/NotFound'
    TooManyRequestsErrorResponse:
      description: >
        Request limit reached. The request was not processed.


        This error occurs when you send too many requests in a short period of
        time. You should pause before sending further requests.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/TooManyRequests'
    InternalServerErrorResponse:
      description: Unexpected internal server error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/InternalServerError'
    ServiceUnavailableErrorResponse:
      description: Service unavailable
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ServiceUnavailable'
  securitySchemes:
    BasicAuth:
      type: http
      scheme: basic

````