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
tags:
  - name: env-production
    description: Currently deployed to prod env
  - name: plan-later
    description: Not yet planned
paths:
  /ns/{nsid}/identity/tokens/{rid}:
    get:
      operationId: identity-token-get
      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).
      tags:
        - env-production
      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'
  /ns/{nsid}/identity/tokens/{rid}/actions:
    post:
      operationId: identity-token-send-action
      summary: Perform a business operation related to an identity token
      description: |
        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)
      tags:
        - env-production
      parameters:
        - $ref: '#/components/parameters/NamespaceId'
        - $ref: '#/components/parameters/ResourceId'
      requestBody:
        description: |
          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`](/schemas/CANCEL): A request to permanently disable a payment instrument token, with no possibility of undo
          - [`FETCH_ELIGIBILITY`](/schemas/FETCH_ELIGIBILITY): A request to fetch eligibility information for the token from the downstream payment provider
          - [`VALIDATE_PASSPHRASE`](/schemas/VALIDATE_PASSPHRASE): A request to validate passphrase for the token from the downstream payment provider
          - [`GET_ACCOUNT`](/schemas/GET_ACCOUNT): A request to retrieve the account information associated with a PIT
        required: true
        content:
          application/json:
            schema:
              oneOf:
                - $ref: '#/components/schemas/CANCEL'
                - $ref: '#/components/schemas/FETCH_ELIGIBILITY'
                - $ref: '#/components/schemas/VALIDATE_PASSPHRASE'
                - $ref: '#/components/schemas/GET_ACCOUNT'
      responses:
        '200':
          description: |
            The updated resource.
          content:
            application/vnd.bango.identity.token.v1+json:
              schema:
                $ref: '#/components/schemas/token-options'
              examples:
                CANCEL response:
                  value:
                    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
                FETCH_ELIGIBILITY response:
                  value:
                    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
                GET_ACCOUNT response:
                  value:
                    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
                    account:
                      phoneNumber: '+4402079304832'
                    userProperties:
                      token: myUserToken
                      accountNickname: 457
                      specialProperty:
                        key1: value1
                VALIDATE_PASSPHRASE response:
                  value:
                    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
                    passphraseValidationStatus: accepted
                    userProperties:
                      token: myUserToken
                      accountNickname: 457
                      specialProperty:
                        key1: value1
        '400':
          $ref: '#/components/responses/BadRequestErrorResponse'
        '401':
          $ref: '#/components/responses/InvalidCredentialsErrorResponse'
        '403':
          $ref: '#/components/responses/PermissionDeniedErrorResponse'
        '404':
          $ref: '#/components/responses/NotFoundErrorResponse'
        '409':
          description: |
            The token is not in the correct state for the requested operation.
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      oneOf:
                        - $ref: '#/components/schemas/pit-already-canceled'
                        - $ref: '#/components/schemas/incompatible-state'
                required:
                  - errors
        '429':
          $ref: '#/components/responses/TooManyRequestsErrorResponse'
        '500':
          description: Unexpected internal server error or payment provider error
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      oneOf:
                        - $ref: '#/components/schemas/internal-server-error'
                        - $ref: '#/components/schemas/payment-provider-failure'
                required:
                  - errors
        '503':
          $ref: '#/components/responses/ServiceUnavailableErrorResponse'
        '504':
          $ref: '#/components/responses/GatewayTimeoutErrorResponse'
components:
  schemas:
    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
    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
    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
    InvalidCredentials:
      allOf:
        - $ref: '#/components/schemas/CommonErrorResponse'
        - properties:
            errors:
              type: array
              items:
                oneOf:
                  - $ref: '#/components/schemas/invalid-credentials'
    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
    PermissionDenied:
      allOf:
        - $ref: '#/components/schemas/CommonErrorResponse'
        - properties:
            errors:
              type: array
              items:
                oneOf:
                  - $ref: '#/components/schemas/permission-denied'
    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
    NotFound:
      allOf:
        - $ref: '#/components/schemas/CommonErrorResponse'
        - properties:
            errors:
              type: array
              items:
                oneOf:
                  - $ref: '#/components/schemas/not-found'
    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
    TooManyRequests:
      allOf:
        - $ref: '#/components/schemas/CommonErrorResponse'
        - properties:
            errors:
              type: array
              items:
                oneOf:
                  - $ref: '#/components/schemas/too-many-requests'
    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
    InternalServerError:
      allOf:
        - $ref: '#/components/schemas/CommonErrorResponse'
        - properties:
            errors:
              type: array
              items:
                oneOf:
                  - $ref: '#/components/schemas/internal-server-error'
    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
    ServiceUnavailable:
      allOf:
        - $ref: '#/components/schemas/CommonErrorResponse'
        - properties:
            errors:
              type: array
              items:
                oneOf:
                  - $ref: '#/components/schemas/service-unavailable'
    CANCEL:
      title: CANCEL action
      description: |
        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: object
      properties:
        type:
          const: CANCEL
        payload:
          description: Empty object
          type: object
          additionalProperties: false
      required:
        - type
        - payload
    FETCH_ELIGIBILITY:
      title: FETCH_ELIGIBILITY action
      description: |
        A request to fetch eligibility information for the token from the downstream payment provider.
      type: object
      properties:
        type:
          const: FETCH_ELIGIBILITY
        payload:
          description: |
            Data needed for the FETCH_ELIGIBILITY action.
          type: object
          properties:
            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.
          additionalProperties: false
      required:
        - type
        - payload
    VALIDATE_PASSPHRASE:
      title: VALIDATE_PASSPHRASE action
      description: |
        A request to validate passphrase secret for the token from the downstream payment provider.
      type: object
      properties:
        type:
          const: VALIDATE_PASSPHRASE
        payload:
          description: |
            Data needed for the VALIDATE_PASSPHRASE action.
          type: object
          properties:
            passphrase:
              type: string
              minLength: 1
              maxLength: 50
              description: |
                A plain text referring to a user passphrase that will be authenticated for the token from the downstream payment provider.
          required:
            - passphrase
      required:
        - type
        - payload
    GET_ACCOUNT:
      title: GET_ACCOUNT action
      description: |
        A request to retrieve the account information associated with a PIT
      type: object
      properties:
        type:
          const: GET_ACCOUNT
        payload:
          description: Empty object
          type: object
          additionalProperties: false
      required:
        - type
        - payload
    token-cancel:
      title: Identity token resource - CANCEL selected
      description: |
        An identity token resource when CANCEL has been selected.
      allOf:
        - $ref: '#/components/schemas/BasicProperties'
    token-fetch-eligibility:
      title: Identity token resource - FETCH_ELIGIBILITY selected
      description: |
        An identity token resource FETCH_ELIGIBILITY has been selected.
      allOf:
        - $ref: '#/components/schemas/BasicProperties'
    payment-provider-passphrase-validation-status:
      title: Payment provider passphrase validation status
      description: |
        The status returned by the payment provider resulting from passphrase validation.
      type: string
      enum:
        - accepted
        - declined
        - closed
        - barred
        - not-enabled
        - unknown
    ExtendedPassphraseProperties:
      properties:
        passphraseValidationStatus:
          $ref: '#/components/schemas/payment-provider-passphrase-validation-status'
      required:
        - passphraseValidationStatus
    token-validate-passphrase:
      title: Identity token resource- VALIDATE_PASSPHRASE selected
      description: |
        An identity token resource when VALIDATE_PASSPHRASE has been selected.
      allOf:
        - $ref: '#/components/schemas/BasicProperties'
        - $ref: '#/components/schemas/ExtendedPassphraseProperties'
    phone-number:
      title: Phone number (E.164)
      description: |
        A phone number in E.164 format, with a leading `+` sign. No spaces or symbols are permitted.
      type: string
      pattern: ^\+[1-9]?[0-9]{7,14}$
      example: '+447700900123'
    payment-instrument-account-properties:
      title: Payment instrument account properties
      description: |
        Properties of a payment instrument that identify the account with the payment provider. In many cases, this is a phone number.

        MUST contain at least one property. MAY contain more than one property. All property values MUST be strings.

        The `phoneNumber` property defined here MUST be used IF the payment provider identifies the account using a phone number that can be expressed in E.164 format with a leading `+`. Otherwise, the property MUST NOT be used (use a property with a different name instead).
      type: object
      minProperties: 1
      maxProperties: 50
      unevaluatedProperties:
        type: string
        minLength: 1
        maxLength: 512
      properties:
        phoneNumber:
          $ref: '#/components/schemas/phone-number'
      example:
        phoneNumber: '+447700900123'
        anyPropertyNeededByThePaymentProvider: some-string
    ExtendedAccountProperties:
      properties:
        account:
          $ref: '#/components/schemas/payment-instrument-account-properties'
      required:
        - account
    token-get-account:
      title: Identity token resource- GET_ACCOUNT selected
      description: |
        An identity token resource. when GET_ACCOUNT has been selected.
      allOf:
        - $ref: '#/components/schemas/BasicProperties'
        - $ref: '#/components/schemas/ExtendedAccountProperties'
    token-options:
      title: Identity Token resource
      description: |
        An identity Token resource response.
      oneOf:
        - $ref: '#/components/schemas/token-cancel'
        - $ref: '#/components/schemas/token-fetch-eligibility'
        - $ref: '#/components/schemas/token-validate-passphrase'
        - $ref: '#/components/schemas/token-get-account'
    invalid-json:
      title: invalid-json
      description: The request body is not valid JSON
      type: object
      properties:
        code:
          const: invalid-json
        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 request body is not valid JSON
        url:
          description: URL to more information about the error type
          type: string
          format: url
          example: https://developer.bango.com/error-codes/invalid-json
      required:
        - code
        - meta
        - message
    missing-parameter:
      title: missing-parameter
      description: A required parameter is missing from the request
      type: object
      properties:
        code:
          const: missing-parameter
        meta:
          description: Additional information to help identify the specific error case
          type: object
          properties:
            param:
              description: The name of the missing parameter
              type: string
          required:
            - param
        message:
          description: Human-readable message describing the error
          type: string
          example: A required parameter was missing from the request
        url:
          description: URL to more information about the error type
          type: string
          format: url
          example: https://developer.bango.com/error-codes/missing-parameter
      required:
        - code
        - meta
        - message
    invalid-parameter:
      title: invalid-parameter
      description: A request parameter is invalid
      type: object
      properties:
        code:
          const: invalid-parameter
        meta:
          description: Additional information to help identify the specific error case
          type: object
          properties:
            param:
              description: The name of the invalid parameter
              type: string
            reason:
              description: Optional human-readable information to explain why the parameter is invalid. Code must not rely on the content of this string.
              type: string
              example: 'Expected format: YYYY-MM-DD'
          required:
            - param
        message:
          description: Human-readable message describing the error
          type: string
          example: A parameter in the request was not valid
        url:
          description: URL to more information about the error type
          type: string
          format: url
          example: https://developer.bango.com/error-codes/invalid-parameter
      required:
        - code
        - meta
        - message
    BadRequest:
      allOf:
        - $ref: '#/components/schemas/CommonErrorResponse'
        - properties:
            errors:
              type: array
              items:
                oneOf:
                  - $ref: '#/components/schemas/invalid-json'
                  - $ref: '#/components/schemas/missing-parameter'
                  - $ref: '#/components/schemas/invalid-parameter'
    pit-already-canceled:
      title: pit-already-canceled
      description: |
        An attempt was made to cancel a payment instrument token that is already canceled.
      type: object
      properties:
        code:
          const: pit-already-canceled
        meta:
          description: Empty in this case
          type: object
        message:
          description: Human-readable message describing the error
          const: Payment instrument token already canceled
        url:
          description: URL to more information about the error type
          type: string
          format: url
          example: https://developer.bango.com/error-codes/pit-already-canceled
      required:
        - code
        - meta
        - message
    incompatible-state:
      title: incompatible-state
      description: |
        Incompatible state.

        This is a generic error used when a more specific error is not available. The `meta.reason` may give a human-readable description of the error.
      type: object
      properties:
        code:
          const: incompatible-state
        meta:
          description: Additional information to help identify the specific error case
          type: object
          properties:
            reason:
              description: Human-readable information to explain in detail why the operation cannot be permitted in the current state. Code must not rely on the content of this string.
              type: string
              example: Operation is permitted in state "active" only
        message:
          description: Human-readable message describing the error
          const: The resource is not in the correct state for the requested operation
        url:
          description: URL to more information about the error type
          type: string
          format: url
          example: https://developer.bango.com/error-codes/incompatible-state
      required:
        - code
        - meta
        - message
    payment-provider-failure:
      title: payment-provider-failure
      description: |
        An error occurred with the downstream payment provider, and the Bango Platform was unable to fulfil the request.

        This might be a transient error or a persistent error. The `meta.paymentProviderCode` value indicates the type of response received by the Bango Platform from the payment provider.

        The `meta.canRetry` boolean indicates whether the payment provider believes the merchant can retry the request.
      type: object
      properties:
        code:
          const: payment-provider-failure
        meta:
          description: Additional information to help identify the specific error case
          type: object
          properties:
            paymentProviderCode:
              description: |
                Code indicating the type of response the Bango Platform received from the payment provider. Not all codes apply to all requests from the Bango Platform.

                Possible values:
                - `service-unavailable`: the payment provider returned an HTTP 503 response to a request from the Bango Platform
                - `internal-server-error`: the payment provider returned another HTTP 5xx response to a request from the Bango Platform
                - `mt-message-send-request-failure`: the payment provider was unable to send an MT flow message to an end user's device
                - `otp-request-failure`: the payment provider was unable to send an OTP to an end user's device, or verify an OTP provided by an end user
              type: string
              enum:
                - internal-server-error
                - service-unavailable
                - mt-message-send-request-failure
                - otp-request-failure
            canRetry:
              description: Whether the payment provider believes the request can be retried
              type: boolean
          required:
            - paymentProviderCode
            - canRetry
        message:
          description: Human-readable message describing the error
          const: An error occurred at the payment provider
        url:
          description: URL to more information about the error type
          type: string
          format: url
          example: https://developer.bango.com/error-codes/payment-provider-failure
      required:
        - code
        - meta
        - message
    gateway-timeout:
      title: gateway-timeout
      description: Gateway timeout
      type: object
      properties:
        code:
          const: gateway-timeout
        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 server timed out while waiting for a response from an upstream server, causing the request to fail
      required:
        - code
        - meta
        - message
    GatewayTimeout:
      allOf:
        - $ref: '#/components/schemas/CommonErrorResponse'
        - properties:
            errors:
              type: array
              items:
                oneOf:
                  - $ref: '#/components/schemas/gateway-timeout'
  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'
  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'
    BadRequestErrorResponse:
      description: Bad request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/BadRequest'
    GatewayTimeoutErrorResponse:
      description: Gateway timeout.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/GatewayTimeout'
