openapi: 3.1.0
info:
  title: Inbound Payment Provider API
  version: 1.0.{build_number}
  x-bango-public-version: 1.0.0
  contact:
    name: Bango Support
    url: https://developer.bango.com
    email: support@bango.com
  x-bango-public-description: |
    The Inbound Payment Provider API (IPPA) allows authenticated/authorized users to send _actions_ to the Bango Platform. An action represents a request for the Bango Platform to perform an operation, or a request for the Bango Platform to provide some data, or a notification to the Bango Platform.

    ### Glossary

    - **payment provider**: Some payment providers integrate directly with the Bango Platform, and some integrate indirectly with the help of a Bango-hosted adapter service. We use the phrase "payment provider [adapter]" to mean *either* the payment provider *or* a Bango-hosted adapter for that payment provider

    ## Change log

    - 1.0.0
      - First released version
servers:
  - url: https://api.bango.com
    description: Production server
paths:
  /ns/{nsid}/payment-provider/actions:
    post:
      operationId: send-action-inbound
      summary: Send an action to the Bango Platform
      parameters:
        - $ref: '#/components/parameters/NamespaceId'
      requestBody:
        description: |
          An action initiated by the payment provider, to be processed by the Bango Platform.

          The following action types are available. See each action type schema for detailed information on purpose and response action types.

          - `SEND_MERCHANT_MESSAGE`: Ask the Bango Platform to forward a message from the payment provider to a merchant partner
          - `GET_SESSION`: Ask the Bango Platform for the data stored for a verification session
          - `CONFIRM_SESSION_IDENTITY`: Notify the Bango Platform that an end user was successfully identified as part of an identity verification flow
          - `REJECT_SESSION_IDENTITY`: Notify the Bango Platform that an end user was NOT successfully identified as part of an identity verification flow
          - `CANCEL_PI`: Ask the Bango Platform to permanently cancel a payment instrument and any associated payment instrument tokens
          - `UPDATE_SESSION`: Ask the Bango Platform to store data with a verification session, including data shared with the merchant partner
          - `GET_PI`: Ask the Bango Platform for the data stored for a payment instrument
          - `UPDATE_PI`: Ask the Bango Platform to update the data stored for a payment instrument
          - `NOTIFY_MO`: Provide the Bango Platform with details of an MO message received by the payment provider
        required: true
        content:
          application/json:
            schema:
              oneOf:
                - $ref: '#/components/schemas/SEND_MERCHANT_MESSAGE'
                - $ref: '#/components/schemas/GET_SESSION'
                - $ref: '#/components/schemas/CONFIRM_SESSION_IDENTITY'
                - $ref: '#/components/schemas/REJECT_SESSION_IDENTITY'
                - $ref: '#/components/schemas/CANCEL_PI'
                - $ref: '#/components/schemas/UPDATE_SESSION'
                - $ref: '#/components/schemas/GET_PI'
                - $ref: '#/components/schemas/UPDATE_PI'
                - $ref: '#/components/schemas/NOTIFY_MO'
      responses:
        '200':
          description: |
            The response action, which depends on the request action.
          content:
            application/vnd.bango.platform-response-action.v1+json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/SESSION_RESPONSE'
                  - $ref: '#/components/schemas/PI_RESPONSE'
        '204':
          description: |
            The action in the request was acknowledged by the recipient and no response action was required
        '400':
          $ref: '#/components/responses/BadRequestErrorResponse'
        '401':
          $ref: '#/components/responses/InvalidCredentialsErrorResponse'
        '403':
          $ref: '#/components/responses/PermissionDeniedErrorResponse'
        '404':
          $ref: '#/components/responses/NotFoundErrorResponse'
        '409':
          description: |
            The resource 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/pi-already-canceled'
                        - $ref: '#/components/schemas/incompatible-state'
                required:
                  - errors
        '429':
          $ref: '#/components/responses/TooManyRequestsErrorResponse'
        '500':
          $ref: '#/components/responses/InternalServerErrorResponse'
        '503':
          $ref: '#/components/responses/ServiceUnavailableErrorResponse'
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
    request-id:
      title: Unique identifier for request action
      description: |
        A unique identifier for the request action (not used for any other purpose). If the recipient of the request action returns a response action, the response action must specify the same identifier as its own `id`.
      type: string
      format: uuid
      example: 2adf1639-bb50-4df7-b8a0-79a0cd4f2277
    SEND_MERCHANT_MESSAGE:
      title: SEND_MERCHANT_MESSAGE request action (inbound)
      description: |
        _This action might be replaced in a future phase of work_

        This action type lets a payment provider ask the Bango Platform to forward a message intact from the payment provider to a merchant partner.

        The action identifies the merchant partner using a string ID defined by Bango Support as part of the payment provider's configuration settings (different payment providers may use different strings for the same merchant partner).

        The action includes the message body and a message type. The Bango Platform uses the message type to select how to forward the message to the merchant partner. For example, some merchant partners may reserve different API endpoints for the delivery of different types of message. Not all merchant partners may support all message types.

        ### Possible HTTP responses

        - HTTP 204 NO CONTENT:
          - the message was successfully sent to the merchant partner
        - HTTP 400 BAD REQUEST with one or more errors:
          - `code` == `invalid-json`:
            - the request body is not valid JSON
          - `code` == `missing-parameter`:
            - a required parameter is omitted from the request action
          - `code` == `invalid-parameter`:
            - a parameter is not of the expected type, or
            - a parameter violates the documented constraints, or
            - `payload.recipientId` is not recognized as a merchant partner the payment provider may contact, or
            - `payload.recipientId` is recognized as a merchant partner but it doesn't support the message type, or
            - `payload.recipientId` is recognized as a merchant partner but it rejected the message (the error's `meta` object may give a reason)
      type: object
      properties:
        id:
          $ref: '#/components/schemas/request-id'
        type:
          const: SEND_MERCHANT_MESSAGE
        payload:
          type: object
          properties:
            recipientId:
              description: |
                The payment provider's configured string identifier for a merchant partner.
              type: string
              minLength: 1
              maxLength: 255
            messageType:
              description: |
                The type of message. The Bango Platform uses this to select how to forward the message to the merchant partner.
              type: string
              enum:
                - FRAUD_NOTIFICATION
                - REMITTANCE_ACCEPTANCE_NOTIFICATION
            body:
              description: |
                The content to forward to the merchant partner.
              type: string
              minLength: 1
              maxLength: 4095
          required:
            - recipientId
            - messageType
            - body
      required:
        - id
        - type
        - payload
    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
    GET_SESSION:
      title: GET_SESSION request action (inbound)
      description: |
        This action type lets a payment provider request the data stored for a verification session in the Bango Platform. The response includes data the payment provider has provided to the merchant, and data the merchant has provided to the payment provider.

        ### Possible HTTP responses

        - HTTP 200 OK:
          - [`SESSION_RESPONSE`](/schemas/SESSION_RESPONSE) response action
        - HTTP 400 BAD REQUEST with one or more errors:
          - `code` == `invalid-json`:
            - the request body is not valid JSON
          - `code` == `missing-parameter`:
            - a required parameter is omitted from the request action
          - `code` == `invalid-parameter`:
            - a parameter is not of the expected type, or
            - a parameter violates the documented constraints
        - HTTP 404 NOT FOUND with an error:
          - `code` == `not-found`:
            - `payload.verificationSessionId` does not identify a verification session that exists, or
            - `payload.verificationSessionId` does not identify a verification session the payment provider has access to
      type: object
      properties:
        id:
          $ref: '#/components/schemas/request-id'
        type:
          const: GET_SESSION
        payload:
          type: object
          properties:
            verificationSessionId:
              $ref: '#/components/schemas/resource-id'
              description: |
                The verification session identifier generated by Bango. Bango provided this to the merchant partner to include in the message from the end user's device.
          required:
            - verificationSessionId
      required:
        - id
        - type
        - payload
    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
    simple-object-patch:
      title: Simple object patch mechanism
      description: |
        Extend an existing object schema with this schema to enable a simple way to patch an object.

        The extended schema has two special properties:
        - $replace: boolean. If present, and if true, then this means "remove all existing properties from the object before applying updates"
        - $remove: an array of property names. If present, then this means "remove properties with these names from the object before applying updates"

        This extended schema now lets you define a patch object, which specifies operations to perform on an existing object to make a new object. In the patch object, `$replace` and `$remove` (applied first) remove existing properties from the original object, and other properties update the original object.

        Nested objects might themselves be extended this way: patches are applied recursively.

        Examples

        Imagine a schema ABC defining three optional properties `a`, `b`, and `c` whose values are all strings. Consider this object matching schema ABC:

        ```json
        {
          "a": "xyz",
          "b": "qwerty",
          "c": "plplpl"
        }
        ```

        Extend ABC with this schema (adding `$remove` and `$replace`) to get ABC_Patchable. Here's a patch object matching ABC_Patchable:

        ```json
        {
          "$remove": ["b"],
          "a": "aaaaaaa"
        }
        ```

        Applying the patch - combining the original object with the patch object - gives this object:

        ```json
        {
          "a": "aaaaaaa",
          "c": "plplpl"
        }
        ```

        - The property `b` was removed (because of `$remove` in the patch object)
        - The property `a` was updated (because it was specified in the patch object)
        - The property `c` was unchanged (because it wasn't mentioned in the patch object)

        Another example of a patch object:

        ```json
        {
          "$replace": true,
          "b": "bbbbbbb"
        }
        ```

        The result after patching the original object would be:

        ```json
        {
          "b": "bbbbbbb"
        }
        ```

        - All existing properties were removed (because `$replace` was set to true in the patch object)
        - The property `b` was updated (because it was specified in the patch object)

        Now imagine a schema GH defining two properties `g` and `h`, where the value of `g` is a string and the value of `h` is an object (matching schema XY) with optional properties `x` and `y`, both strings. Consider this object matching schema GH:

        ```json
        {
          "g": "ggg",
          "h": {
            "x": "xxx",
            "y": "yyy"
          }
        }
        ```

        Extend both GH and the nested XY schemas with this schema, making GH_Patchable. Here's a patch object matching GH_Patchable:

        ```json
        {
          "$remove": ['g'],
          "h": {
            "$replace": true,
            "x": "aaa"
          }
        }
        ```

        The result after patching the object above would be:

        ```json
        {
          "h": {
            "x": "aaa"
          }
        }
        ```

        - The property `g` was removed (because of `$remove` in the patch object)
        - The properties `x` and `y` were removed (because `$replace` was set to true in the inner patch object)
        - The property `x` was updated (because it was specifed in the inner patch object)
      type: object
      properties:
        $replace:
          description: |
            If true, removes all existing properties from the object before applying any property updates.
          type: boolean
          default: false
        $remove:
          description: |
            If present, removes the properties named in the array before applying any property updates.

            It is NOT an error if an array member references a property that does not exist in the object being patched.

            It is NOT an error if an array member references a property not defined in the schema of the object being patched.

            It is NOT an error to include a property in the array and also to update its value.
          type: array
          items:
            type: string
    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
    country-code-iso-3166:
      title: ISO 3166-1 alpha-2 country code
      description: |
        A two-character [ISO 3166-1 alpha-2](https://www.iso.org/iso-3166-country-codes.html) country code.
      type: string
      enum:
        - AF
        - AX
        - AL
        - DZ
        - AS
        - AD
        - AO
        - AI
        - AQ
        - AG
        - AR
        - AM
        - AW
        - AU
        - AT
        - AZ
        - BS
        - BH
        - BD
        - BB
        - BY
        - BE
        - BZ
        - BJ
        - BM
        - BT
        - BO
        - BQ
        - BA
        - BW
        - BV
        - BR
        - IO
        - BN
        - BG
        - BF
        - BI
        - KH
        - CM
        - CA
        - CV
        - KY
        - CF
        - TD
        - CL
        - CN
        - CX
        - CC
        - CO
        - KM
        - CG
        - CD
        - CK
        - CR
        - CI
        - HR
        - CU
        - CW
        - CY
        - CZ
        - DK
        - DJ
        - DM
        - DO
        - EC
        - EG
        - SV
        - GQ
        - ER
        - EE
        - ET
        - FK
        - FO
        - FJ
        - FI
        - FR
        - GF
        - PF
        - TF
        - GA
        - GM
        - GE
        - DE
        - GH
        - GI
        - GR
        - GL
        - GD
        - GP
        - GU
        - GT
        - GG
        - GN
        - GW
        - GY
        - HT
        - HM
        - VA
        - HN
        - HK
        - HU
        - IS
        - IN
        - ID
        - IR
        - IQ
        - IE
        - IM
        - IL
        - IT
        - JM
        - JP
        - JE
        - JO
        - KZ
        - KE
        - KI
        - KP
        - KR
        - KW
        - KG
        - LA
        - LV
        - LB
        - LS
        - LR
        - LY
        - LI
        - LT
        - LU
        - MO
        - MK
        - MG
        - MW
        - MY
        - MV
        - ML
        - MT
        - MH
        - MQ
        - MR
        - MU
        - YT
        - MX
        - FM
        - MD
        - MC
        - MN
        - ME
        - MS
        - MA
        - MZ
        - MM
        - NA
        - NR
        - NP
        - NL
        - NC
        - NZ
        - NI
        - NE
        - NG
        - NU
        - NF
        - MP
        - 'NO'
        - OM
        - PK
        - PW
        - PS
        - PA
        - PG
        - PY
        - PE
        - PH
        - PN
        - PL
        - PT
        - PR
        - QA
        - RE
        - RO
        - RU
        - RW
        - BL
        - SH
        - KN
        - LC
        - MF
        - PM
        - VC
        - WS
        - SM
        - ST
        - SA
        - SN
        - RS
        - SC
        - SL
        - SG
        - SX
        - SK
        - SI
        - SB
        - SO
        - ZA
        - GS
        - SS
        - ES
        - LK
        - SD
        - SR
        - SJ
        - SZ
        - SE
        - CH
        - SY
        - TW
        - TJ
        - TZ
        - TH
        - TL
        - TG
        - TK
        - TO
        - TT
        - TN
        - TR
        - TM
        - TC
        - TV
        - UG
        - UA
        - AE
        - GB
        - US
        - UM
        - UY
        - UZ
        - VU
        - VE
        - VN
        - VG
        - VI
        - WF
        - EH
        - YE
        - ZM
        - ZW
    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
    currency-code-iso-4217:
      title: ISO 4217 3-char currency code
      description: |
        A three-character [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.

        The allowed values are:
        - All current ISO 4217 codes except those for precious metals and bonds
        - ISO 4217 historical codes withdrawn since 2010

        ISO 4217 publication: January 1, 2023
      type: string
      enum:
        - AED
        - AFN
        - ALL
        - AMD
        - ANG
        - AOA
        - ARS
        - AUD
        - AWG
        - AZN
        - BAM
        - BBD
        - BDT
        - BGN
        - BHD
        - BIF
        - BMD
        - BND
        - BOB
        - BOV
        - BRL
        - BSD
        - BTN
        - BWP
        - BYN
        - BYR
        - BZD
        - CAD
        - CDF
        - CHE
        - CHF
        - CHW
        - CLF
        - CLP
        - CNY
        - COP
        - COU
        - CRC
        - CUC
        - CUP
        - CVE
        - CZK
        - DJF
        - DKK
        - DOP
        - DZD
        - EEK
        - EGP
        - ERN
        - ETB
        - EUR
        - FJD
        - FKP
        - GBP
        - GEL
        - GHS
        - GIP
        - GMD
        - GNF
        - GTQ
        - GYD
        - HKD
        - HNL
        - HRK
        - HTG
        - HUF
        - IDR
        - ILS
        - INR
        - IQD
        - IRR
        - ISK
        - JMD
        - JOD
        - JPY
        - KES
        - KGS
        - KHR
        - KMF
        - KPW
        - KRW
        - KWD
        - KYD
        - KZT
        - LAK
        - LBP
        - LKR
        - LRD
        - LSL
        - LTL
        - LVL
        - LYD
        - MAD
        - MDL
        - MGA
        - MKD
        - MMK
        - MNT
        - MOP
        - MRO
        - MRU
        - MUR
        - MVR
        - MWK
        - MXN
        - MXV
        - MYR
        - MZN
        - NAD
        - NGN
        - NIO
        - NOK
        - NPR
        - NZD
        - OMR
        - PAB
        - PEN
        - PGK
        - PHP
        - PKR
        - PLN
        - PYG
        - QAR
        - RON
        - RSD
        - RUB
        - RWF
        - SAR
        - SBD
        - SCR
        - SDG
        - SEK
        - SGD
        - SHP
        - SLE
        - SLL
        - SOS
        - SRD
        - SSP
        - STD
        - STN
        - SVC
        - SYP
        - SZL
        - THB
        - TJS
        - TMT
        - TND
        - TOP
        - TRY
        - TTD
        - TWD
        - TZS
        - UAH
        - UGX
        - USD
        - USN
        - USS
        - UYI
        - UYU
        - UYW
        - UZS
        - VED
        - VEF
        - VES
        - VND
        - VUV
        - WST
        - XAF
        - XCD
        - XDR
        - XFU
        - XOF
        - XPF
        - XSU
        - YER
        - ZAR
        - ZMK
        - ZMW
        - ZWL
      example: USD
    payment-instrument-global-properties-patch:
      title: Payment instrument global properties patch
      description: |
        Patch (add, update, or remove) properties that apply across all merchants universally.
      allOf:
        - $ref: '#/components/schemas/simple-object-patch'
      type: object
      minProperties: 0
      maxProperties: 50
      unevaluatedProperties:
        type: string
        minLength: 1
        maxLength: 512
      properties:
        accountType:
          $ref: '#/components/schemas/payment-provider-account-type'
        countryCode:
          $ref: '#/components/schemas/country-code-iso-3166'
        locale:
          $ref: '#/components/schemas/locale-bcp-47'
        currency:
          $ref: '#/components/schemas/currency-code-iso-4217'
      example:
        accountType: prepaid
        locale: en-US
        currency: USD
    payment-instrument-route-properties-patch:
      title: Payment instrument per-route properties
      description: |
        Properties of a payment instrument that apply to a specific route.
      allOf:
        - $ref: '#/components/schemas/simple-object-patch'
      type: object
      minProperties: 0
      maxProperties: 50
      unevaluatedProperties:
        type: string
        minLength: 1
        maxLength: 512
      properties:
        paymentEligibilityStatus:
          description: |
            Whether the account identification data in the request may be used to process payments.

            - `enabled`: Authorized partners can use the account data to process payments
            - `not-enabled`: Authorized partners cannot use the account data to process payments
            - `closed`: The payment provider has closed the account and it can no longer process payments
            - `barred`: The payment provider has suspended or barred the user associated with the account (this may be temporary)
            - `unknown`: The payment provider has not provided information about this account
            - `unsupported`: The payment provider does not support requests for information about this account
          type: string
          enum:
            - enabled
            - not-enabled
            - closed
            - barred
            - unknown
            - unsupported
      example:
        paymentEligibilityStatus: barred
    payment-instrument-properties-partial-patch:
      title: Payment instrument properties partial patch object
      description: |
        A **partial** patch object for payment instrument properties. A payment provider can specify:
        - Properties to merge (add, update) with the existing account properties
        - Properties to patch (add, update, or remove) the existing global properties that apply universally across all merchants
        - Properties to patch (add, update, or remove) the existing merchant-specific properties
      type: object
      properties:
        account:
          title: Account identification properties
          description: |
            Merge (add, update) properties that identify the account with the payment provider. Requests can specify any additional string properties needed by the payment provider to identify the account.
          allOf:
            - $ref: '#/components/schemas/payment-instrument-account-properties'
        global:
          $ref: '#/components/schemas/payment-instrument-global-properties-patch'
        route:
          title: Per-route properties, indexed by friendly merchant ID
          description: |
            Patch (add, update, or remove) properties that apply per-merchant.

            Property names are friendly string identifiers for merchant partners (for example, `OGNAB_PLUS`). Each string maps to a partner namespace ID in the shared route-config-service.
          allOf:
            - $ref: '#/components/schemas/simple-object-patch'
          type: object
          properties:
            SOME_MERCHANT_ID:
              title: Any valid merchant IDs (mapping to partner namespace IDs)
              description: Patch (add, update, or remove) one or more merchant-specific configuration properties.
              allOf:
                - $ref: '#/components/schemas/payment-instrument-route-properties-patch'
      example:
        account:
          phoneNumber: '+447700900123'
        route:
          OGNAB_PLUS:
            paymentEligibilityStatus: enabled
          $remove:
            - OGNAB_MINUS
    nextAction:
      description: |
        An optional next action for either the merchant partner or the payment provider. This string, read/write for both parties, allows either party to send an explicit signal to the other using a well-defined property. Either party may set the string as part of an "update shared data" operation.

        Typically the string is used by one party to inform the other party that there is session data for them to process to progress the negotation. That session data should provide additional context as needed.

        For flexibility, this schema specifies any string. Bango recommends using these strings:
        - `none`: No next action is currently defined
        - `merchant`: A signal for the merchant partner to take the next action
        - `payment-provider`: A signal for the payment provider to take the next action
      type: string
      minLength: 1
      default: none
    paymentProviderToMerchant:
      description: |
        Data the payment provider owns (read/write access) and the merchant partner may consue (read access only)
      type: object
      properties:
        authRedirectUrl:
          description: |
            The payment provider URL to which the merchant should redirect the end user to authenticate to the payment provider.
          type: string
          format: url
          example: https://example.com/payment-provider/login
    CONFIRM_SESSION_IDENTITY:
      title: CONFIRM_SESSION_IDENTITY request action (inbound)
      description: |
        This action type lets a payment provider notify the Bango Platform that an end user was successfully identified as part of an identity verification flow. The Bango Platform can then generate the payment instrument token for the merchant partner.

        The action includes optional account identity information, optional global properties for the end user, and optional route-specific properties for the end user.

        The action can also include data intended for the merchant.

        After this action, `UPDATE_SESSION` actions will not be processed and will result in an error.

        ### Possible HTTP responses

        - HTTP 200 OK:
          - [`SESSION_RESPONSE`](/schemas/SESSION_RESPONSE) response action
        - HTTP 400 BAD REQUEST with one or more errors:
          - `code` == `invalid-json`:
            - the request body is not valid JSON
          - `code` == `missing-parameter`:
            - a required parameter is omitted from the request action
          - `code` == `invalid-parameter`:
            - a parameter is not of the expected type, or
            - a parameter violates the documented constraints, or
            - a `payload.paymentInstrumentProperties.route` property is not a merchant partner enabled for the payment provider
          - `code` == `incompatible-state`:
            - the current verification session state does not permit identity confirmation from the payment provider
        - HTTP 404 NOT FOUND with an error:
          - `code` == `not-found`:
            - `payload.verificationSessionId` does not identify a verification session that exists, or
            - `payload.verificationSessionId` does not identify a verification session the payment provider has access to
      type: object
      properties:
        id:
          $ref: '#/components/schemas/request-id'
        type:
          const: CONFIRM_SESSION_IDENTITY
        payload:
          type: object
          properties:
            verificationSessionId:
              $ref: '#/components/schemas/resource-id'
              description: |
                The verification session identifier generated by Bango. Bango provided this to the merchant partner to include in the message from the end user's device.
            paymentInstrumentProperties:
              $ref: '#/components/schemas/payment-instrument-properties-partial-patch'
            shared:
              description: |
                Update to the negotiation data shared from the payment provider to the merchant partner. Data in `paymentProviderToMerchant` is merged into the existing data.
              type: object
              properties:
                nextAction:
                  $ref: '#/components/schemas/nextAction'
                paymentProviderToMerchant:
                  $ref: '#/components/schemas/paymentProviderToMerchant'
          required:
            - verificationSessionId
      required:
        - id
        - type
        - payload
    REJECT_SESSION_IDENTITY:
      title: REJECT_SESSION_IDENTITY request action (inbound)
      description: |
        This action type lets a payment provider notify the Bango Platform that an end user was not successfully identified as part of an identity verification flow. The Bango Platform can then report this conclusion back to the merchant partner.

        The action includes an error code that lets the payment provider provide more detailed information.

        After this action, `UPDATE_SESSION` actions will not be processed and will result in an error.

        ### Possible HTTP responses

        - HTTP 200 OK:
          - [`SESSION_RESPONSE`](/schemas/SESSION_RESPONSE) response action
        - HTTP 400 BAD REQUEST with one or more errors:
          - `code` == `invalid-json`:
            - the request body is not valid JSON
          - `code` == `missing-parameter`:
            - a required parameter is omitted from the request action
          - `code` == `invalid-parameter`:
            - a parameter is not of the expected type, or
            - a parameter violates the documented constraints
          - `code` == `incompatible-state`:
            - the current verification session state does not permit identity rejection from the payment provider
        - HTTP 404 NOT FOUND with an error:
          - `code` == `not-found`:
            - `payload.verificationSessionId` does not identify a verification session that exists, or
            - `payload.verificationSessionId` does not identify a verification session the payment provider has access to
      type: object
      properties:
        id:
          $ref: '#/components/schemas/request-id'
        type:
          const: REJECT_SESSION_IDENTITY
        payload:
          type: object
          properties:
            verificationSessionId:
              $ref: '#/components/schemas/resource-id'
              description: |
                The verification session identifier generated by Bango. Bango provided this to the merchant partner to include in the message from the end user's device.
            code:
              description: |
                A machine-readable code that indicates why the payment provider rejected the identity verification session.

                The payment provider can use the generic code `rejected` if a more specific code is not available. In this case, it's a good idea to include more details in the `message` field.

                In most cases, the code is reported to the merchant partner in the session resource, in the `result.reasons` array. But note:
                - `payment-provider-internal-server-error` and `payment-provider-service-unavailable` are both transformed to `payment-provider-failure`, with the value of `meta.paymentProviderCode` set appropriately and `meta.canRetry` always set to `false` (because the merchant can't retry anything)

                **NOTE** List subject to change.
              type: string
              enum:
                - user-canceled
                - user-invalid
                - user-barred
                - user-suspended
                - user-not-enabled
                - expired
                - payment-provider-internal-server-error
                - payment-provider-service-unavailable
                - adapter-failure
                - rejected
            message:
              description: |
                An optional human-readable message describing why the payment provider rejected the identity verification session.
              type: string
              minLength: 1
              maxLength: 255
          required:
            - verificationSessionId
            - code
      required:
        - id
        - type
        - payload
    CANCEL_PI:
      title: CANCEL_PI request action (inbound)
      description: |
        This action type lets a payment provider request to cancel a payment instrument in the Bango Platform. Canceling a payment instrument indirectly cancels all payment instrument tokens associated with that payment instrument. It is not possible to undo cancelation.

        The action includes account identity information, and an optional reason for the cancelation. This specification defines a set of reason codes: more can be added as needed.

        ### Possible HTTP responses

        - HTTP 200 OK:
          - [`PI_RESPONSE`](/schemas/PI_RESPONSE) response action
        - HTTP 400 BAD REQUEST with one or more errors:
          - `code` == `invalid-json`:
            - the request body is not valid JSON
          - `code` == `missing-parameter`:
            - a required parameter is omitted from the request action
          - `code` == `invalid-parameter`:
            - a parameter is not of the expected type, or
            - a parameter violates the documented constraints
        - HTTP 404 NOT FOUND with an error:
          - `code` == `not-found`:
            - `payload.account` does not identify a payment instrument that exists, or
            - `payload.account` does not identify a payment instrument the payment provider has access to
        - HTTP 409 CONFLICT with error:
          - `code` == `pi-already-canceled`:
            - the payment instrument is already canceled
      type: object
      properties:
        id:
          $ref: '#/components/schemas/request-id'
        type:
          const: CANCEL_PI
        payload:
          type: object
          properties:
            account:
              $ref: '#/components/schemas/payment-instrument-account-properties'
              description: |
                Account identifiers for the payment instrument to cancel.
            code:
              description: |
                An optional reason code, allowing the payment provider to explain why the payment instrument is being canceled.

                These reason codes have been defined:
                - `account-closed`: the payment provider account has closed
                - `other-payment-provider`: the account identifier is not recognized by the payment provider, and may belong to another
                - `user-not-eligible`: the payment provider account holder is no longer eligible for payment processing
                - `other`: another reason

                Other reason codes will be added as required.
              type: string
              enum:
                - account-closed
                - other-payment-provider
                - user-not-eligible
                - other
            message:
              description: |
                An optional human-readable message to further explain why the payment instrument is being canceled.
              type: string
              example: Account migrated to another payment provider
          required:
            - account
      required:
        - id
        - type
        - payload
    UPDATE_SESSION:
      title: UPDATE_SESSION request action (inbound)
      description: |
        This action type lets a payment provider store short-lived or long-lived data about the verification session in the Bango Platform. The Bango Platform can use some or all of this data later (after receiving a `CONFIRM_SESSION_IDENTITY` action) to generate the payment instrument token for the merchant partner.

        The action includes account identity information, optional global properties for the end user, and optional route-specific properties for the end user.

        The update can also include data intended for the merchant.

        ### Possible HTTP responses

        - HTTP 200 OK:
          - [`SESSION_RESPONSE`](/schemas/SESSION_RESPONSE) response action
        - HTTP 400 BAD REQUEST with one or more errors:
          - `code` == `invalid-json`:
            - the request body is not valid JSON
          - `code` == `missing-parameter`:
            - a required parameter is omitted from the request action
          - `code` == `invalid-parameter`:
            - a parameter is not of the expected type, or
            - a parameter violates the documented constraints, or
            - a `payload.paymentInstrumentProperties.route` property is not a merchant partner enabled for the payment provider
          - `code` == `incompatible-state`:
            - the current verification session state does not permit session updates from the payment provider
        - HTTP 404 NOT FOUND with an error:
          - `code` == `not-found`:
            - `payload.verificationSessionId` does not identify a verification session that exists, or
            - `payload.verificationSessionId` does not identify a verification session the payment provider has access to
      type: object
      properties:
        id:
          $ref: '#/components/schemas/request-id'
        type:
          const: UPDATE_SESSION
        payload:
          type: object
          properties:
            verificationSessionId:
              $ref: '#/components/schemas/resource-id'
              description: |
                The verification session identifier generated by Bango. Bango provided this to the merchant partner to include in the message from the end user's device.
            paymentInstrumentProperties:
              $ref: '#/components/schemas/payment-instrument-properties-partial-patch'
            shared:
              description: |
                Update to the negotiation data shared from the payment provider to the merchant partner. Data in `paymentProviderToMerchant` is merged into the existing data.
              type: object
              properties:
                nextAction:
                  $ref: '#/components/schemas/nextAction'
                paymentProviderToMerchant:
                  $ref: '#/components/schemas/paymentProviderToMerchant'
          required:
            - verificationSessionId
      required:
        - id
        - type
        - payload
    GET_PI:
      title: GET_PI request action (inbound)
      description: |
        This action type lets a payment provider request the data stored for a payment instrument in the Bango Platform, specified using account identifiers. Merchant partners DO NOT see this data.

        ### Possible HTTP responses

        - HTTP 200 OK:
          - [`PI_RESPONSE`](/schemas/PI_RESPONSE) response action
        - HTTP 400 BAD REQUEST with one or more errors:
          - `code` == `invalid-json`:
            - the request body is not valid JSON
          - `code` == `missing-parameter`:
            - a required parameter is omitted from the request action
          - `code` == `invalid-parameter`:
            - a parameter is not of the expected type, or
            - a parameter violates the documented constraints
        - HTTP 404 NOT FOUND with an error:
          - `code` == `not-found`:
            - `payload.account` does not identify a payment instrument that exists, or
            - `payload.account` does not identify a payment instrument the payment provider has access to
      type: object
      properties:
        id:
          $ref: '#/components/schemas/request-id'
        type:
          const: GET_PI
        payload:
          type: object
          properties:
            account:
              $ref: '#/components/schemas/payment-instrument-account-properties'
          required:
            - account
      required:
        - id
        - type
        - payload
    route:
      title: Per-route properties, indexed by friendly merchant ID
      description: |
        Patch (add, update, or remove) properties that apply per-merchant.

        Property names are friendly string identifiers for merchant partners (for example, `OGNAB_PLUS`). Each string maps to a partner namespace ID in the shared route-config-service.
      allOf:
        - $ref: '#/components/schemas/simple-object-patch'
      type: object
      properties:
        SOME_MERCHANT_ID:
          title: Any valid merchant IDs (mapping to partner namespace IDs)
          description: Patch (add, update, or remove) one or more merchant-specific configuration properties.
          allOf:
            - $ref: '#/components/schemas/payment-instrument-route-properties-patch'
    UPDATE_PI:
      title: UPDATE_PI request action (inbound)
      description: |
        This action type lets a payment provider update some data stored for a payment instrument in the Bango Platform, specified using account identifiers. Merchant partners DO NOT see this data.

        The action permits changes to active payment instruments only, and to global and route properties only. It is not possible to update canceled payment instruments, or payment instrument account properties.

        ### Possible HTTP responses

        - HTTP 200 OK:
          - [`PI_RESPONSE`](/schemas/PI_RESPONSE) response action
        - HTTP 400 BAD REQUEST with one or more errors:
          - `code` == `invalid-json`:
            - the request body is not valid JSON
          - `code` == `missing-parameter`:
            - a required parameter is omitted from the request action
          - `code` == `invalid-parameter`:
            - a parameter is not of the expected type, or
            - a parameter violates the documented constraints, or
            - `payload.account` specifies a canceled payment instrument, or
            - a `payload.paymentInstrumentProperties.route` property is not a merchant partner enabled for the payment provider
        - HTTP 404 NOT FOUND with an error:
          - `code` == `not-found`:
            - `payload.account` does not identify a payment instrument that exists, or
            - `payload.account` does not identify a payment instrument the payment provider has access to
      type: object
      properties:
        id:
          $ref: '#/components/schemas/request-id'
        type:
          const: UPDATE_PI
        payload:
          type: object
          properties:
            account:
              $ref: '#/components/schemas/payment-instrument-account-properties'
              description: |
                Account identifiers for the payment instrument to change.
            paymentInstrumentProperties:
              description: |
                A patch object for payment instrument properties, allowing a payment provider to patch (add, update, or remove):
                - Properties that apply universally across all merchants
                - Properties that apply for specific merchants
              type: object
              properties:
                global:
                  $ref: '#/components/schemas/payment-instrument-global-properties-patch'
                route:
                  $ref: '#/components/schemas/route'
          required:
            - account
            - paymentInstrumentProperties
      required:
        - id
        - type
        - payload
    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
    mo-transport:
      title: MO transport mechanism
      description: |
        How the MO message was delivered to the payment provider.

        Permitted values:
        - `sms`: MO message was delivered over SMS
        - `http-header-enrichment`: MO message was delivered over HTTP with user account details provided using Header Enrichment
      type: string
      enum:
        - sms
        - http-header-enrichment
    NOTIFY_MO:
      title: NOTIFY_MO request action (inbound)
      description: |
        This action type lets a payment provider notify the Bango Platform of an MO message received by the payment provider.

        ### Possible HTTP responses

        - HTTP 204 NO CONTENT:
          - Simple acknowledgement
        - HTTP 400 BAD REQUEST with one or more errors:
          - `code` == `invalid-json`:
            - the request body is not valid JSON
          - `code` == `missing-parameter`:
            - a required parameter is omitted from the request action
          - `code` == `invalid-parameter`:
            - a parameter is not of the expected type, or
            - a parameter violates the documented constraints
        - HTTP 404 NOT FOUND:
          - `code` == `not-found`:
            - `merchantId` is not recognized
            - merchant/payment provider route does not exist, or is not enabled, or does not support the MO flow
            - `sessionToken` is not recognized (when `sessionTokenType` is `bango` and there's no matching verification session ID)
        - HTTP 409 CONFLICT
          - `code` == `incompatible-state`:
            - the session `flow/state` was not `mo/awaiting-message` (`meta.reason` should explain that session is now in state `failed`)
      type: object
      properties:
        id:
          $ref: '#/components/schemas/request-id'
        type:
          const: NOTIFY_MO
        payload:
          type: object
          properties:
            account:
              $ref: '#/components/schemas/payment-instrument-account-properties'
            merchantId:
              $ref: '#/components/schemas/merchant-id'
            transport:
              $ref: '#/components/schemas/mo-transport'
            sessionToken:
              description: |
                Bango session token or merchant session token.

                Bango session tokens are always in UUID v4 format. Merchant session tokens may be any string.

                The session token DOES NOT include the `bango-session-rid:` prefix (for Bango session tokens) or any merchant-specific prefix like `DCB:`.
              type: string
              minLength: 1
              maxLength: 256
              example: b638c171-8e47-402d-a6d2-6cf29faf5711
            sessionTokenType:
              description: |
                Whether sessionToken is a Bango session token or a merchant session token.

                In the MO message received by the payment provider, Bango session tokens have the prefix `bango-session-rid:` If this prefix is not present, a session token is treated as a merchant session token.
              type: string
              enum:
                - bango
                - merchant
          required:
            - account
            - merchantId
            - transport
            - sessionToken
            - sessionTokenType
      required:
        - id
        - type
        - payload
    response-id:
      title: Unique request identifier
      description: |
        The unique identifier for the request action to which this is a response.
      type: string
      format: uuid
      example: 2adf1639-bb50-4df7-b8a0-79a0cd4f2277
    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
    merchantToPaymentProvider:
      description: |
        Data the merchant partner owns (read/write access) and the payment provider may consume (read access only).

        This specification defines some properties that merchant partners and payment providers MAY use for certain purposes. These properties are optional, but if specified MUST match the schemas defined here.

        Merchant partners and payment providers MAY use other properties not defined here.
      type: object
      properties:
        authSuccessRedirectUrl:
          description: |
            The merchant URL to which the payment provider should redirect the end user after a successful authentication.
          type: string
          format: url
          example: https://example.com/merchant/user-login-ok
        authFailureRedirectUrl:
          description: |
            The merchant URL to which the payment provider should redirect the end user after a failed authentication.
          type: string
          format: url
          example: https://example.com/merchant/user-login-failed
    SESSION_RESPONSE:
      title: SESSION_RESPONSE response action
      description: |
        The data stored for a verification session in the Bango Platform. Includes private data, data the payment provider has provided to the merchant, and data the merchant has provided to the payment provider.
      type: object
      properties:
        id:
          $ref: '#/components/schemas/response-id'
        type:
          const: SESSION_RESPONSE
        payload:
          type: object
          properties:
            verificationSessionId:
              $ref: '#/components/schemas/resource-id'
              description: |
                The verification session identifier generated by Bango. Bango provided this to the merchant partner to include in the message from the end user's device.
            paymentProviderId:
              $ref: '#/components/schemas/payment-provider-id'
            merchantId:
              $ref: '#/components/schemas/merchant-id'
            paymentInstrumentProperties:
              $ref: '#/components/schemas/payment-instrument-properties-partial-patch'
            shared:
              description: |
                Current negotiation data shared between the payment provider and the merchant partner
              type: object
              properties:
                nextAction:
                  $ref: '#/components/schemas/nextAction'
                paymentProviderToMerchant:
                  $ref: '#/components/schemas/paymentProviderToMerchant'
                merchantToPaymentProvider:
                  $ref: '#/components/schemas/merchantToPaymentProvider'
          required:
            - verificationSessionId
            - paymentProviderId
            - merchantId
            - paymentInstrumentProperties
      required:
        - id
        - type
        - payload
    payment-instrument-global-properties:
      title: Payment instrument global properties
      description: |
        Properties of a payment instrument that apply universally across all merchants.
      type: object
      minProperties: 0
      maxProperties: 50
      unevaluatedProperties:
        type: string
        minLength: 1
        maxLength: 512
      properties:
        accountType:
          $ref: '#/components/schemas/payment-provider-account-type'
        countryCode:
          $ref: '#/components/schemas/country-code-iso-3166'
        locale:
          $ref: '#/components/schemas/locale-bcp-47'
        currency:
          $ref: '#/components/schemas/currency-code-iso-4217'
      example:
        accountType: prepaid
        locale: en-US
        currency: USD
    userProperties:
      title: User specific properties
      description: |
        Properties that are specific to a user
      type: object
      example:
        userProperties:
          token: myUserToken
          accountNickname: 457
          specialProperty:
            key1: value1
    payment-instrument-route-properties:
      title: Payment instrument per-route properties
      description: |
        Properties of a payment instrument that apply to a specific route.
      type: object
      minProperties: 0
      maxProperties: 50
      unevaluatedProperties:
        type: string
        minLength: 1
        maxLength: 512
      properties:
        paymentEligibilityStatus:
          description: |
            Whether the account identification data in the request may be used to process payments.

            - `enabled`: Authorized partners can use the account data to process payments
            - `not-enabled`: Authorized partners cannot use the account data to process payments
            - `closed`: The payment provider has closed the account and it can no longer process payments
            - `barred`: The payment provider has suspended or barred the user associated with the account (this may be temporary)
            - `unknown`: The payment provider has not provided information about this account
            - `unsupported`: The payment provider does not support requests for information about this account
          type: string
          enum:
            - enabled
            - not-enabled
            - closed
            - barred
            - unknown
            - unsupported
          example: enabled
        userProperties:
          $ref: '#/components/schemas/userProperties'
        OTHERS:
          description: Other allowed properties TBD
      example:
        paymentEligibilityStatus: barred
        userProperties:
          token: myUserToken
          accountNickname: 457
    payment-instrument-properties:
      title: Payment instrument properties
      description: |
        Payment instrument properties, including:
        - Account identifiers
        - Properties that apply universally across all merchants
        - Properties that apply for specific merchants
      type: object
      additionalProperties: false
      properties:
        account:
          $ref: '#/components/schemas/payment-instrument-account-properties'
        global:
          $ref: '#/components/schemas/payment-instrument-global-properties'
        route:
          title: Per-route properties, indexed by friendly merchant ID
          description: |
            Property names are friendly string identifiers for merchant partners (for example, `OGNAB_PLUS`). Each string maps to a partner namespace ID in the shared route-config-service.
          type: object
          properties:
            SOME_MERCHANT_ID:
              $ref: '#/components/schemas/payment-instrument-route-properties'
    PI_RESPONSE:
      title: PI_RESPONSE response action
      description: |
        The data stored for a payment instrument in the Bango Platform.
      type: object
      properties:
        id:
          $ref: '#/components/schemas/response-id'
        type:
          const: PI_RESPONSE
        payload:
          type: object
          properties:
            paymentInstrumentProperties:
              $ref: '#/components/schemas/payment-instrument-properties'
          required:
            - paymentInstrumentProperties
      required:
        - id
        - type
        - payload
    CommonErrorResponse:
      type: object
      required:
        - errors
    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'
    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'
    pi-already-canceled:
      title: pi-already-canceled [plan-p1]
      description: |
        The payment provider tried to cancel a payment instrument that is already canceled.
      type: object
      properties:
        code:
          const: pi-already-canceled
        meta:
          description: Empty in this case
          type: object
        message:
          description: Human-readable message describing the error
          const: Payment instrument already canceled
        url:
          description: URL to more information about the error type
          type: string
          format: url
          example: https://developer.bango.com/error-codes/pi-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
    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'
  parameters:
    NamespaceId:
      in: path
      name: nsid
      required: true
      schema:
        $ref: '#/components/schemas/namespace-id'
  responses:
    BadRequestErrorResponse:
      description: Bad request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/BadRequest'
    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'
