openapi: 3.1.0
info:
  title: Outbound 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 Outbound Payment Provider API (OPPA) is an interface definition for a service that payment providers implement on their own servers. It defines how the Bango Platform sends _actions_ to payment providers. An action represents a request for the payment provider to perform an operation, or a request for the payment provider to provide some data, or a notification to the payment provider.

    ### Glossary

    - **payment provider [adapter]**: 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://payment-provider.example.com/any-prefix
    description: Server belonging to the payment provider [adapter]
paths:
  /actions:
    post:
      operationId: send-action-outbound
      summary: Send an action to the payment provider [adapter]
      description: |
        The Bango Platform uses this endpoint to send an action to a payment provider, or an adapter for a payment provider.

        The available actions constitute a small fixed vocabulary for communications initiated by the Bango Platform. An action can:
        - Ask the payment provider [adapter] to perform an operation
        - Request data from the payment provider [adapter]
        - Notify the payment provider [adapter] of an event of interest

        Every action sent (a _request action_) may result in a range of possible responses (_response actions_) from the payment provider [adapter]. Each request action defines the expected response actions.

        Every request action will include a unique `id` property (UUID v4). This identifies the request action and is not used for any other purpose (it's **not** a payment resource ID, for example). The response action corresponding to the request action must include the request action's `id`.

        ### HTTP responses

        The Bango Platform always sends a request to the payment provider [adapter] over HTTP, and the payment provider [adapter] must return an HTTP response. HTTP requests contain request actions as defined in this specification.

        The HTTP response MUST be one of the following:
        - HTTP 204 NO CONTENT - permitted only if the request needs a simple acknowledgement without specific response data
        - HTTP 200 OK - containing a response action in the response body. Each request action defines the expected response actions
        - HTTP 4xx - indicating a problem with the request action
        - HTTP 5xx - indicating a problem with the payment provider [adapter] system

        This specification defines the shape of HTTP 4xx and 5xx responses. These all have a response body containing an `errors` array, each member of which is an object containing an error `code` and other data.

        If a request to a payment provider [adapter] times out, this is treated the same as an HTTP 503 error from the payment provider [adapter] with `canRetry: true`.

        #### HTTP 400 BAD REQUEST responses

        For HTTP 400 BAD REQUEST responses specifically, the payment provider [adapter] MUST use these values for `code` for the error conditions listed:

        - `invalid-json`
          - If the request body isn't valid JSON format
        - `missing-parameter`
          - If any required parameter is not present in the request body. For example, `id`, `type`, `payload`, or any required value inside `payload`.
        - `invalid-parameter`
          - If any parameter in the request is syntactically invalid. For example, if `type` is an integer, or if `id` is not a UUID v4
          - If any parameter in the request is semantically invalid. For example, if a `payload` field specifies a user identifier and that user isn't recognized by the payment provider [adapter]

        The payment provider [adapter] MAY use other values of `code` for an HTTP 400 BAD REQUEST response with other error conditions. The specification for each request action defines the additional permitted values of `code`.

        #### HTTP 5xx responses

        HTTP 5xx responses indicate a problem with the payment provider [adapter]. This might be a temporary problem caused by a network issue between the Bango Platform and the payment provider [adapter], or it may indicate a more serious, persistent issue.

        Any 5xx response from the payment provider [adapter] propagates through the platform as a service error with code `payment-provider-failure`. The 5xx response from the payment provider [adapter] may specify that the request can be retried, using the `meta.canRetry` boolean in the 5xx response.

        A timeout in the connection from the Bango Platform to the payment provider [adapter] is always reported as a `payment-provider-failure` that may be retried.
      parameters:
        - in: header
          name: Bango-Request-Action
          schema:
            description: |
              The value of `type` from the request body, indicating the type of request action. Allows payment providers [adapters] to route request actions without inspecting the request body.
            type: string
            enum:
              - NOTIFY_SESSION_FLOW
              - AUTHORIZE
              - CAPTURE
              - REFUND
              - CANCEL_AUTH
              - CHARGE
              - GET_ELIGIBILITY
              - SEND_MT_MESSAGE
              - VALIDATE_PASSPHRASE
              - SEND_OTP
              - VERIFY_OTP
      requestBody:
        description: |
          An action initiated by the Bango Platform, to be processed by the payment provider [adapter].

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

          - `NOTIFY_SESSION_FLOW`: Tell the payment provider [adapter] that a merchant partner is starting an identity verification flow
          - `AUTHORIZE`: Ask the payment provider [adapter] for payment authorization: the first step in a two-step (Authorize/Capture) payments model.
          - `CAPTURE`: Ask the payment provider [adapter] for payment capture: the second step in a two-step (Authorize/Capture) payments model
          - `REFUND`: Ask the payment provider [adapter] to charge a payment request: one-step payments model
          - `CANCEL_AUTH`: Ask the payment provider [adapter] to cancel an authorization on a payment request.
          - `GET_ELIGIBILITY`: Ask the payment provider [adapter] for up-to-date eligibility data for an end user
          - `SEND_MT_MESSAGE`: Ask the payment provider [adapter] to send a message to a particular end user device
          - `VALIDATE_PASSPHRASE`: Ask the payment provider [adapter] to validate a passphrase to a particular end user device
          - `SEND_OTP`: Ask the payment provider [adapter] to send an OTP to a particular end user device
          - `VERIFY_OTP`: Ask the payment provider [adapter] to verify an OTP provided by the merchant end user
          - `CHARGE`: Ask the payment provider [adapter] to charge a payment request: one-step payments model
        required: true
        content:
          application/json:
            schema:
              oneOf:
                - $ref: '#/components/schemas/AUTHORIZE'
                - $ref: '#/components/schemas/CANCEL_AUTH'
                - $ref: '#/components/schemas/CAPTURE'
                - $ref: '#/components/schemas/CHARGE'
                - $ref: '#/components/schemas/REFUND'
                - $ref: '#/components/schemas/GET_ELIGIBILITY'
                - $ref: '#/components/schemas/NOTIFY_SESSION_FLOW'
                - $ref: '#/components/schemas/SEND_MT_MESSAGE'
                - $ref: '#/components/schemas/VALIDATE_PASSPHRASE'
                - $ref: '#/components/schemas/SEND_OTP'
                - $ref: '#/components/schemas/VERIFY_OTP'
      responses:
        '200':
          description: |
            The response action, which depends on the request action.
          content:
            application/vnd.bango.pp-response-action.v1+json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/GET_ELIGIBILITY_RESPONSE'
                  - $ref: '#/components/schemas/AUTHORIZE_APPROVED_RESPONSE'
                  - $ref: '#/components/schemas/AUTHORIZE_DENIED_RESPONSE'
                  - $ref: '#/components/schemas/CANCEL_AUTH_APPROVED_RESPONSE'
                  - $ref: '#/components/schemas/CANCEL_AUTH_DENIED_RESPONSE'
                  - $ref: '#/components/schemas/CAPTURE_APPROVED_RESPONSE'
                  - $ref: '#/components/schemas/CAPTURE_DENIED_RESPONSE'
                  - $ref: '#/components/schemas/CHARGE_APPROVED_RESPONSE'
                  - $ref: '#/components/schemas/CHARGE_DENIED_RESPONSE'
                  - $ref: '#/components/schemas/REFUND_APPROVED_RESPONSE'
                  - $ref: '#/components/schemas/REFUND_DENIED_RESPONSE'
                  - $ref: '#/components/schemas/NOTIFY_SESSION_FLOW_APPROVED_RESPONSE'
                  - $ref: '#/components/schemas/NOTIFY_SESSION_FLOW_DENIED_RESPONSE'
                  - $ref: '#/components/schemas/SEND_MT_MESSAGE_RESPONSE'
                  - $ref: '#/components/schemas/VALIDATE_PASSPHRASE_RESPONSE'
                  - $ref: '#/components/schemas/SEND_OTP_RESPONSE'
                  - $ref: '#/components/schemas/VERIFY_OTP_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'
        '429':
          $ref: '#/components/responses/TooManyRequestsErrorResponse'
        '500':
          description: |
            An internal server error occurred
          content:
            application/json:
              schema:
                type: object
                properties:
                  paymentProviderOperationId:
                    description: |
                      An optional identifier used by the payment provider to identify retries. Used where the payment provider is unable to accept Bango's operationId.
                    type: string
                    minLength: 1
                    maxLength: 255
                  errors:
                    type: array
                    items:
                      oneOf:
                        - $ref: '#/components/schemas/payment-provider-internal-server-error'
                        - $ref: '#/components/schemas/adapter-failure'
                required:
                  - errors
        '502':
          $ref: '#/components/responses/PaymentProviderBadGatewayErrorResponse'
        '503':
          $ref: '#/components/responses/PaymentProviderServiceUnavailableErrorResponse'
        '504':
          $ref: '#/components/responses/PaymentProviderGatewayTimeoutErrorResponse'
components:
  schemas:
    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
    adapter-authentication-properties:
      title: Adapter Authentication properties
      description: |
        Properties used by the payment provider adapters to handle the specific authentication
        requirements of a payment provider.
      type: object
      properties:
        type:
          description: |
            The authentication type used by the Payment Provider adapter
          type: string
          enum:
            - OAuth
        endpoint:
          description: |
            The endpoint used to provide any required authentication tokens.
          type: string
    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
    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
    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
    payment-route-configuration-properties:
      title: Billing route properties
      description: |
        Properties of a billing route
      type: object
      properties:
        authentication:
          $ref: '#/components/schemas/adapter-authentication-properties'
        paymentProviderId:
          $ref: '#/components/schemas/payment-provider-id'
        merchantId:
          $ref: '#/components/schemas/merchant-id'
        routingKey:
          x-bango-public-description: |
            Routing key
          description: |
            ????
          type: string
        countryCode:
          $ref: '#/components/schemas/country-code-iso-3166'
      required:
        - paymentProviderId
        - merchantId
      example:
        authentication:
          type: OAuth
          endpoint: https://oauth.customer.com
        paymentProviderId: OGNABTEL
        merchantId: OGNAB_PLUS
        routingKey: '12345'
        countryCode: MX
    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
    bango-payment-id:
      title: Bango payment ID
      allOf:
        - $ref: '#/components/schemas/resource-id'
        - description: |
            Bango's unique identifier for the payment. Copied from the payment resource `rid` property.
    merchant-payment-id:
      title: Merchant payment ID
      description: |
        The merchant partner's own unique identifier for the payment. Not necessarily a UUID. Uniquely identifies a payment resource (equivalent to the payment resource `rid`). Copied from the payment resource `partnerPaymentId` property.
      type: string
      minLength: 1
      maxLength: 255
      example: asdfg-asdfhj-fgrewa-bcczx
    merchant-request-id:
      title: Merchant request ID
      description: |
        Merchant-owned request identifier. Bango considers this identifier opaque, and passes it to the payment provider unchanged (in OPPA request actions, as `merchantPaymentId`).

        In a returned payment resource, the `partnerRequestId` reflects the value specified in the request from the merchant. If a request does not specify a `partnerRequestId` then the response does not include a `partnerRequestId`.
      type: string
      minLength: 1
      maxLength: 255
      example: zfknveriuouzxcqweff12tgdvxxzb0
    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
    monetary-value:
      title: Monetary value
      description: |
        A monetary value, including currency.

        The `amount` value is represented as an integer in the minor units of the `currency` value, if any. For example:

        - `amount`: `999` and `currency`: `USD` represents USD 9.99, because USD uses two decimal digits for minor units
        - `amount`: `123` and `currency`: `JPY` represents JPY 123, because JPY has no minor units

        The Bango Platform uses [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) as the source of truth for currency codes, including minor units.
      type: object
      properties:
        amount:
          description: |
            The numeric value, in minor units of the currency. Always an integer.
          type: integer
          example: 999
        currency:
          $ref: '#/components/schemas/currency-code-iso-4217'
    monetary-value-required:
      allOf:
        - $ref: '#/components/schemas/monetary-value'
        - required:
            - amount
            - currency
    payment-balance:
      title: Payment balance
      description: |
        The total amounts currently authorized, captured, refunded, and canceled for the payment, taking all successful actions into account.

        For one-step payments, the `authorized` and `captured` values are always identical.
      type: object
      properties:
        authorized:
          $ref: '#/components/schemas/monetary-value-required'
        captured:
          $ref: '#/components/schemas/monetary-value-required'
        refunded:
          $ref: '#/components/schemas/monetary-value-required'
        canceled:
          $ref: '#/components/schemas/monetary-value-required'
      required:
        - authorized
        - captured
        - refunded
        - canceled
    sale-item:
      title: Sale item
      description: |
        An item (product or service) purchased in whole or part by a payment.
      type: object
      properties:
        description:
          description: |
            A description for the item.
          type: string
          minLength: 1
          maxLength: 255
          example: Ognab Music - 6-month subscription
        category:
          description: |
            An optional category for the item.
          type: string
          minLength: 1
          maxLength: 255
        uniqueId:
          description: |
            The partner's own unique identifier for the item. Ideally globally unique (a UUID).
          type: string
          minLength: 1
          maxLength: 255
          example: 18c32e64-04dc-4886-83f1-1a7d7ac1a95b
        price:
          allOf:
            - $ref: '#/components/schemas/monetary-value-required'
            - title: |
                The full payment expected for this item.
      required:
        - description
        - price
    payment-shared:
      title: Data shared between merchant and payment provider
      description: |
        Data shared between the merchant partner and the payment provider as part of a payment resource. Supplied to the payment provider with every payment action, such as `AUTHORIZE` or `CHARGE`.
      type: object
      properties:
        merchantToPaymentProvider:
          description: |
            Data the merchant partner owns (read/write access) and the payment provider may consume (read access only).

            Constraints:
            - Between 0 and 255 properties
            - Each property value is either:
              - string (length 0 to 255 inclusive)
              - number (-1048575 to +1048575 inclusive)
              - boolean
              - array (between 0 and 255 items) containing a mixture of:
                - string (length 0 to 255 inclusive)
                - number (-1048575 to +1048575 inclusive)

            Note that nested objects ARE NOT permitted.
          type: object
          maxProperties: 255
          additionalProperties:
            oneOf:
              - type: string
                minLength: 0
                maxLength: 255
              - type: number
                minimum: -1048575
                maximum: 1048575
              - type: boolean
              - type: array
                maxItems: 255
                items:
                  oneOf:
                    - type: string
                      minLength: 0
                      maxLength: 255
                    - type: number
                      minimum: -1048575
                      maximum: 1048575
                    - type: boolean
    payment-authorize-request-properties:
      title: Authorize payment request properties
      description: |
        Authorize payment request properties
      type: object
      properties:
        bangoPaymentId:
          $ref: '#/components/schemas/bango-payment-id'
        merchantPaymentId:
          $ref: '#/components/schemas/merchant-payment-id'
        merchantRequestId:
          $ref: '#/components/schemas/merchant-request-id'
        actionAmount:
          allOf:
            - $ref: '#/components/schemas/monetary-value-required'
            - description: |
                The amount and currency of the Authorize request
        balance:
          $ref: '#/components/schemas/payment-balance'
        saleItem:
          $ref: '#/components/schemas/sale-item'
        shared:
          $ref: '#/components/schemas/payment-shared'
      required:
        - bangoPaymentId
        - actionAmount
        - balance
        - saleItem
        - shared
      example:
        bangoPaymentId: 926f51a4-d992-4bf2-ab57-577007098880
        merchantPaymentId: '12343567'
        merchantRequestId: asldjfaklsdhfalskjhfd
        actionAmount:
          amount: 999
          currency: USD
        balance:
          authorized:
            amount: 0
            currency: USD
          captured:
            amount: 0
            currency: USD
          refunded:
            amount: 0
            currency: USD
          canceled:
            amount: 0
            currency: USD
        saleItem:
          description: Bango Music - 1 Month Subscription
          category: DIGITAL_GOODS
          price:
            amount: 999
            currency: USD
        shared:
          merchantToPaymentProvider:
            recombobulationId: abcd
    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
    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
    customerProfile:
      title: spending limit profile
      description: |
        Customer’s latest spending limit profile
      type: string
      maxLength: 50
      example: saver
    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'
        customerProfile:
          $ref: '#/components/schemas/customerProfile'
      example:
        accountType: prepaid
        countryCode: US
        locale: en-US
        currency: USD
        customerProfile: saver profile
    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'
    idempotency:
      title: Idempotency properties
      description: |
        Properties related to idempotency, to help with reconciliation between the Bango Platform and the payment provider.

        Omitted if the merchant partner did not specify an `Idempotency-Key` with the request.
      type: object
      properties:
        operationId:
          description: |
            A unique, random identifier for the operation. The same `operationId` is reused if the operation is retried.
          type: string
          format: uuid
        paymentProviderOperationId:
          description: |
            An optional identifier used by the payment provider to identify retries. Used where the payment provider is unable to accept Bango's operationId.
          type: string
          minLength: 1
          maxLength: 255
        isRetry:
          description: |
            Whether this request is a retry of an earlier request with the same `operationId`.
          type: boolean
      required:
        - operationId
        - isRetry
      example:
        operationId: d69113a4-e631-43f5-b054-2567467bbbf7
        paymentProviderOperationId: Jv290FSkm34guhSODUFmvksdfh
        isRetry: false
    AUTHORIZE:
      title: AUTHORIZE request action (outbound)
      description: |
        Ask the payment provider [adapter] for payment authorization: the first step in a two-step (Authorize/Capture) payments model. This step reserves funds against the end user's payment instrument with the payment provider.

        How it works: merchant partners send an `AUTHORIZE` action for a payment resource. Route policy determines whether authorization is permitted. If so, OPPA will send an `AUTHORIZE` action to the payment provider [adapter].

        The payment provider [adapter] responds either to approve or deny authorization (or signal an error in the request).

        ### Supported HTTP responses

        - HTTP 200 OK:
          - [`AUTHORIZE_APPROVED_RESPONSE`](/schemas/AUTHORIZE_APPROVED_RESPONSE) response action
          - [`AUTHORIZE_DENIED_RESPONSE`](/schemas/AUTHORIZE_DENIED_RESPONSE) response action
        - HTTP 204 NO CONTENT:
          - Simple acknowledgement approving authorization, without additional data
        - 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
      type: object
      properties:
        id:
          $ref: '#/components/schemas/request-id'
        type:
          const: AUTHORIZE
        payload:
          type: object
          properties:
            routeConfiguration:
              $ref: '#/components/schemas/payment-route-configuration-properties'
            paymentAction:
              $ref: '#/components/schemas/payment-authorize-request-properties'
            paymentInstrumentProperties:
              $ref: '#/components/schemas/payment-instrument-properties'
            merchantUserLocale:
              $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:
            - routeConfiguration
            - paymentAction
            - paymentInstrumentProperties
        idempotency:
          $ref: '#/components/schemas/idempotency'
      required:
        - id
        - type
        - payload
    payment-provider-payment-id:
      title: Payment provider payment ID
      description: |
        The payment provider's own unique identifier for the payment. Not necessarily a UUID. Bango assumes it is unique.

        The payment provider may supply this value in response to a request from the Bango Platform. Subsequent requests to the payment provider include the value where relevant, and responses to the Bango Platform may replace the value.

        The current value is given to the merchant in the payment resource.
      type: string
      minLength: 1
      maxLength: 255
      example: 345hkjhsgdkfgh43k5hjkhk1
    payment-cancel-auth-request-properties:
      title: Cancel Authorize payment request properties
      description: |
        Cancel Authorize payment request properties
      type: object
      properties:
        bangoPaymentId:
          $ref: '#/components/schemas/bango-payment-id'
        merchantPaymentId:
          $ref: '#/components/schemas/merchant-payment-id'
        merchantRequestId:
          $ref: '#/components/schemas/merchant-request-id'
        actionAmount:
          allOf:
            - $ref: '#/components/schemas/monetary-value-required'
            - description: |
                The amount and currency of the cancel authorization request
        paymentProviderPaymentId:
          $ref: '#/components/schemas/payment-provider-payment-id'
        balance:
          $ref: '#/components/schemas/payment-balance'
        saleItem:
          $ref: '#/components/schemas/sale-item'
        shared:
          $ref: '#/components/schemas/payment-shared'
      required:
        - bangoPaymentId
        - actionAmount
        - balance
        - saleItem
        - shared
      example:
        bangoPaymentId: 926f51a4-d992-4bf2-ab57-577007098880
        merchantPaymentId: '12343567'
        merchantRequestId: asldjfaklsdhfalskjhfd
        actionAmount:
          amount: 450
          currency: USD
        paymentProviderPaymentId: '1231232'
        balance:
          authorized:
            amount: 999
            currency: USD
          captured:
            amount: 0
            currency: USD
          refunded:
            amount: 0
            currency: USD
          canceled:
            amount: 0
            currency: USD
        saleItem:
          description: Bango Music - 1 Month Subscription
          category: DIGITAL_GOODS
          price:
            amount: 999
            currency: USD
        shared:
          merchantToPaymentProvider:
            recombobulationId: abcd
    CANCEL_AUTH:
      title: CANCEL_AUTH request action (outbound)
      description: |
        Ask the payment provider [adapter] to cancel an authorization on a payment request.

        The payment provider [adapter] responds either to approve or deny the cancel (or signal an error in the request).

        ### Supported HTTP responses

        - HTTP 200 OK:
          - [`CANCEL_AUTH_APPROVED_RESPONSE`](/schemas/CANCEL_AUTH_APPROVED_RESPONSE) response action
          - [`CANCEL_AUTH_DENIED_RESPONSE`](/schemas/CANCEL_AUTH_DENIED_RESPONSE) response action
        - HTTP 204 NO CONTENT:
          - Simple acknowledgement approving canceled authorization, without additional data
        - 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
      type: object
      properties:
        id:
          $ref: '#/components/schemas/request-id'
        type:
          const: CANCEL_AUTH
        payload:
          type: object
          properties:
            routeConfiguration:
              $ref: '#/components/schemas/payment-route-configuration-properties'
            paymentAction:
              $ref: '#/components/schemas/payment-cancel-auth-request-properties'
            paymentInstrumentProperties:
              $ref: '#/components/schemas/payment-instrument-properties'
          required:
            - routeConfiguration
            - paymentAction
            - paymentInstrumentProperties
        idempotency:
          $ref: '#/components/schemas/idempotency'
      required:
        - id
        - type
        - payload
    payment-capture-request-properties:
      title: Capture payment request properties
      description: |
        Capture payment request properties
      type: object
      properties:
        bangoPaymentId:
          $ref: '#/components/schemas/bango-payment-id'
        merchantPaymentId:
          $ref: '#/components/schemas/merchant-payment-id'
        merchantRequestId:
          $ref: '#/components/schemas/merchant-request-id'
        paymentProviderPaymentId:
          $ref: '#/components/schemas/payment-provider-payment-id'
        actionAmount:
          allOf:
            - $ref: '#/components/schemas/monetary-value-required'
            - description: |
                The amount and currency of the Capture request
        balance:
          $ref: '#/components/schemas/payment-balance'
        saleItem:
          $ref: '#/components/schemas/sale-item'
        shared:
          $ref: '#/components/schemas/payment-shared'
      required:
        - bangoPaymentId
        - actionAmount
        - balance
        - saleItem
        - shared
      example:
        bangoPaymentId: 926f51a4-d992-4bf2-ab57-577007098880
        merchantPaymentId: '12343567'
        merchantRequestId: asldjfaklsdhfalskjhfd
        paymentProviderPaymentId: 3ee9a989-24c8-4d66-b470-87297711c148
        actionAmount:
          amount: 450
          currency: USD
        balance:
          authorized:
            amount: 450
            currency: USD
          captured:
            amount: 0
            currency: USD
          refunded:
            amount: 0
            currency: USD
          canceled:
            amount: 0
            currency: USD
        saleItem:
          description: Bango Music - 1 Month Subscription
          category: DIGITAL_GOODS
          price:
            amount: 450
            currency: USD
        shared:
          merchantToPaymentProvider:
            recombobulationId: abcd
    CAPTURE:
      title: CAPTURE request action (outbound)
      description: |
        Ask the payment provider [adapter] for payment capture: the second step in a two-step (Authorize/Capture) payments model. This step bills the end user's payment instrument with the payment provider so the merchant partner will receive the funds for the goods or services associated with the payment resource.

        The payment provider [adapter] responds either to approve or deny capture (or signal an error in the request).

        The payment resource accessible by the merchant tracks how much has been captured.

        Route/partner policy determines the allowed types of captures.

        ### Single partial capture

        With this policy, merchant partners may send a single `CAPTURE` action for a payment resource for which an `AUTHORIZE` action has previously succeeded. The capture may specify any amount not exceeding the full amount authorized. OPPA will send a `CAPTURE` action to the payment provider [adapter] with the requested amount, which will never exceed the amount authorized.

        ### Single full capture

        With this policy, merchant partners may send a single `CAPTURE` action for a payment resource for which an `AUTHORIZE` action has previously succeeded. The capture MUST specify the full amount authorized. OPPA will send a `CAPTURE` action to the payment provider [adapter] with the requested amount, which is always the same as the amount authorized.

        ### Multiple captures

        With this policy, merchant partners may send any number of `CAPTURE` actions for the payment resource. If the amount requested would not make the total amount captured greater than the total amount authorized, OPPA sends another `CAPTURE` action to the payment provider [adapter] with the requested amount.


        ### Supported HTTP responses

        - HTTP 200 OK:
          - [`CAPTURE_APPROVED_RESPONSE`](/schemas/CAPTURE_APPROVED_RESPONSE) response action
          - [`CAPTURE_DENIED_RESPONSE`](/schemas/CAPTURE_DENIED_RESPONSE) response action
        - HTTP 204 NO CONTENT:
          - Simple acknowledgement approving capture, without additional data
        - 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
      type: object
      properties:
        id:
          $ref: '#/components/schemas/request-id'
        type:
          const: CAPTURE
        payload:
          type: object
          properties:
            routeConfiguration:
              $ref: '#/components/schemas/payment-route-configuration-properties'
            paymentAction:
              $ref: '#/components/schemas/payment-capture-request-properties'
            paymentInstrumentProperties:
              $ref: '#/components/schemas/payment-instrument-properties'
          required:
            - routeConfiguration
            - paymentAction
            - paymentInstrumentProperties
        idempotency:
          $ref: '#/components/schemas/idempotency'
      required:
        - id
        - type
        - payload
    payment-charge-request-properties:
      title: Charge payment request properties
      description: |
        Charge payment request properties
      type: object
      properties:
        bangoPaymentId:
          $ref: '#/components/schemas/bango-payment-id'
        merchantPaymentId:
          $ref: '#/components/schemas/merchant-payment-id'
        merchantRequestId:
          $ref: '#/components/schemas/merchant-request-id'
        actionAmount:
          allOf:
            - $ref: '#/components/schemas/monetary-value-required'
            - description: |
                The amount and currency of the Charge request
        balance:
          $ref: '#/components/schemas/payment-balance'
        saleItem:
          $ref: '#/components/schemas/sale-item'
        shared:
          $ref: '#/components/schemas/payment-shared'
      required:
        - bangoPaymentId
        - actionAmount
        - balance
        - saleItem
        - shared
      example:
        bangoPaymentId: 926f51a4-d992-4bf2-ab57-577007098880
        merchantPaymentId: '12343567'
        merchantRequestId: asldjfaklsdhfalskjhfd
        actionAmount:
          amount: 999
          currency: USD
        balance:
          authorized:
            amount: 0
            currency: USD
          captured:
            amount: 0
            currency: USD
          refunded:
            amount: 0
            currency: USD
          canceled:
            amount: 0
            currency: USD
        saleItem:
          description: Bango Music - 1 Month Subscription
          category: DIGITAL_GOODS
          price:
            amount: 999
            currency: USD
        shared:
          merchantToPaymentProvider:
            recombobulationId: abcd
    CHARGE:
      title: CHARGE request action (outbound) [plan-p1]
      description: |
        Ask the payment provider [adapter] to charge a payment request. This is a one-step payments model: it immediately bills the end user's payment instrument with the payment provider so the merchant partner will receive the funds for the goods or services associated with the payment resource, without initially reserving any funds.

        The payment provider [adapter] responds either to approve or deny charge (or signal an error in the request).

        The payment resource accessible by the merchant tracks how much has been charged in the authorized and captured balances (both will have the same value).

        ### Supported HTTP responses

        - HTTP 200 OK:
          - [`CHARGE_APPROVED_RESPONSE`](/schemas/CHARGE_APPROVED_RESPONSE) response action
          - [`CHARGE_DENIED_RESPONSE`](/schemas/CHARGE_DENIED_RESPONSE) response action
        - HTTP 204 NO CONTENT:
          - Simple acknowledgement approving charge, without additional data
        - 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
      type: object
      properties:
        id:
          $ref: '#/components/schemas/request-id'
        type:
          const: CHARGE
        payload:
          type: object
          properties:
            routeConfiguration:
              $ref: '#/components/schemas/payment-route-configuration-properties'
            paymentAction:
              $ref: '#/components/schemas/payment-charge-request-properties'
            paymentInstrumentProperties:
              $ref: '#/components/schemas/payment-instrument-properties'
          required:
            - routeConfiguration
            - paymentAction
            - paymentInstrumentProperties
        idempotency:
          $ref: '#/components/schemas/idempotency'
      required:
        - id
        - type
        - payload
    payment-refund-request-properties:
      title: Refund payment request properties
      description: |
        Refund payment request properties
      type: object
      properties:
        bangoPaymentId:
          $ref: '#/components/schemas/bango-payment-id'
        merchantPaymentId:
          $ref: '#/components/schemas/merchant-payment-id'
        merchantRequestId:
          $ref: '#/components/schemas/merchant-request-id'
        paymentProviderPaymentId:
          $ref: '#/components/schemas/payment-provider-payment-id'
        actionAmount:
          allOf:
            - $ref: '#/components/schemas/monetary-value-required'
            - description: |
                The amount and currency of the Refund request
        balance:
          $ref: '#/components/schemas/payment-balance'
        saleItem:
          $ref: '#/components/schemas/sale-item'
        shared:
          $ref: '#/components/schemas/payment-shared'
      required:
        - bangoPaymentId
        - actionAmount
        - balance
        - saleItem
        - shared
      example:
        bangoPaymentId: 926f51a4-d992-4bf2-ab57-577007098880
        merchantPaymentId: '12343567'
        merchantRequestId: asldjfaklsdhfalskjhfd
        paymentProviderPaymentId: '1231232'
        actionAmount:
          amount: 450
          currency: USD
        balance:
          authorized:
            amount: 999
            currency: USD
          captured:
            amount: 999
            currency: USD
          refunded:
            amount: 0
            currency: USD
          canceled:
            amount: 0
            currency: USD
        saleItem:
          description: Bango Music - 1 Month Subscription
          category: DIGITAL_GOODS
          price:
            amount: 999
            currency: USD
        shared:
          merchantToPaymentProvider:
            recombobulationId: abcd
    REFUND:
      title: REFUND request action (outbound)
      description: |
        Ask the payment provider [adapter] to refund a payment.

        The payment provider [adapter] responds either to approve or deny refund (or signal an error in the request).

        The payment resource accessible by the merchant tracks how much has been refunded.

        Route/partner policy determines the allowed types of refunds.

        ### Single partial refund

        With this policy, merchants may send a single `REFUND` action that specifies any amount not exceeding the full amount captured. OPPA will send a `REFUND` request action to the payment provider [adapter] with the requested amount. The amount to refund never exceeds the amount captured.

        ### Single full refund

        With this policy, merchants may send a single `REFUND` action that specifies exactly the captured amount. OPPA will send a `REFUND` request action to the payment provider [adapter] with the requested amount.

        ### Multiple refund

        With this policy, merchant partners may send any number of `REFUND` actions for the payment resource. If the amount requested would not make the total amount refunded greater than the total amount captured, OPPA sends another `REFUND` action to the payment provider [adapter] with the requested amount.


        ### Supported HTTP responses

        - HTTP 200 OK:
          - [`REFUND_APPROVED_RESPONSE`](/schemas/REFUND_APPROVED_RESPONSE) response action
          - [`REFUND_DENIED_RESPONSE`](/schemas/REFUND_DENIED_RESPONSE) response action
        - HTTP 204 NO CONTENT:
          - Simple acknowledgement approving refund, without additional data
        - 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
      type: object
      properties:
        id:
          $ref: '#/components/schemas/request-id'
        type:
          const: REFUND
        payload:
          type: object
          properties:
            routeConfiguration:
              $ref: '#/components/schemas/payment-route-configuration-properties'
            paymentAction:
              $ref: '#/components/schemas/payment-refund-request-properties'
            paymentInstrumentProperties:
              $ref: '#/components/schemas/payment-instrument-properties'
          required:
            - routeConfiguration
            - paymentAction
            - paymentInstrumentProperties
        idempotency:
          $ref: '#/components/schemas/idempotency'
      required:
        - id
        - type
        - payload
    GET_ELIGIBILITY:
      title: GET_ELIGIBILITY request action (outbound)
      description: |
        Ask the payment provider [adapter] for up-to-date eligibility data for an end user.

        The end user is identified using account properties associated with a payment instrument in the Bango Platform.

        ### Supported HTTP responses

        - HTTP 200 OK:
          - [`GET_ELIGIBILITY_RESPONSE`](/schemas/GET_ELIGIBILITY_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
            - `payload.account` does not identify an end user account known to the payment provider
      type: object
      properties:
        id:
          $ref: '#/components/schemas/request-id'
        type:
          const: GET_ELIGIBILITY
        payload:
          type: object
          properties:
            routeConfiguration:
              $ref: '#/components/schemas/payment-route-configuration-properties'
            account:
              $ref: '#/components/schemas/payment-instrument-account-properties'
              description: |
                Account identification data for the end user.
              type: object
            merchantUserLocale:
              $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:
            - routeConfiguration
            - account
      required:
        - id
        - type
        - payload
    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
    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
    NOTIFY_SESSION_FLOW:
      title: NOTIFY_SESSION_FLOW request action (outbound)
      description: |
        Tell the payment provider [adapter] that a merchant partner wants to start an identity verification flow.

        This notification occurs when:
        - a billing route is configured for the merchant partner and payment provider, and
        - the billing route configuration enables this notification, and
        - the notification can simplify the identity verification flow (not all flow types use it)

        A payment provider [adapter] can use this action to identify and share data to the merchant partner immediately the flow starts. For example, it allows the payment provider to give the merchant a dynamically generated URL needed for the flow.

        How it works: merchant partners send a `START_NEGOTIATED_FLOW` action (for example) for an identity verification session resource. Route policy determines if this flow is permitted. If so, route configuration determines whether the `NOTIFY_SESSION_FLOW` OPPA action is needed. If so, OPPA sends the action to the payment provider [adapter].

        The action to the payment provider [adapter] includes shared data supplied by the merchant partner. The payment provider [adapter] can validate and process the data before responding. For example, a payment provider may require a specific identifier from the merchant so it can generate an appropriate return value, or to decide whether to allow or deny the verification session.

        The payment provider [adapter] responds with one of the following:
        - A simple acknowledgment approving the flow (if it has no data to share)
        - An approval including data to share to the merchant partner
        - A denial, meaning the merchant should not be permitted to start the flow
        - An error (for example, if the request is malformed in some way)

        ### Supported HTTP responses

        - HTTP 200 OK:
          - [`NOTIFY_SESSION_FLOW_APPROVED_RESPONSE`](/schemas/NOTIFY_SESSION_FLOW_APPROVED_RESPONSE) response action
          - [`NOTIFY_SESSION_FLOW_DENIED_RESPONSE`](/schemas/NOTIFY_SESSION_FLOW_DENIED_RESPONSE) response action
        - HTTP 204 NO CONTENT:
          - Simple acknowledgement confirming receipt of the notification and approval of the identity verification flow, without returning data for 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
      type: object
      properties:
        id:
          $ref: '#/components/schemas/request-id'
        type:
          const: NOTIFY_SESSION_FLOW
        payload:
          type: object
          properties:
            verificationSessionId:
              $ref: '#/components/schemas/resource-id'
              description: |
                The verification session identifier generated by Bango.
            routeConfiguration:
              $ref: '#/components/schemas/payment-route-configuration-properties'
            shared:
              description: |
                Current negotiation data shared between the payment provider and the merchant partner
              type: object
              properties:
                nextAction:
                  $ref: '#/components/schemas/nextAction'
                merchantToPaymentProvider:
                  $ref: '#/components/schemas/merchantToPaymentProvider'
              required:
                - merchantToPaymentProvider
          required:
            - verificationSessionId
            - routeConfiguration
            - shared
      required:
        - id
        - type
        - payload
    SEND_MT_MESSAGE:
      title: SEND_MT_MESSAGE request action (outbound)
      description: |
        Ask the payment provider [adapter] to send a message to an end user's device. Typically this is an SMS to a phone number, but this request action does not imply or require a specific transport mechanism. (See also [`SEND_OTP`](/schemas/SEND_OTP), where the Bango Platform asks the payment provider to generate and send a OTP to the end user.)

        If there's a problem with the request action, the payment provider [adapter] returns HTTP 400. For example, if the payment provider [adapter] doesn't recognize the account properties in the request, it returns HTTP 400.

        If there's a problem sending the message to the end user, the payment provider [adapter] returns a [`SEND_MT_MESSAGE_RESPONSE`](/schemas/SEND_MT_MESSAGE_RESPONSE) response action including a `status` code.

        ### Supported HTTP responses

        - HTTP 200 OK:
          - [`SEND_MT_MESSAGE_RESPONSE`](/schemas/SEND_MT_MESSAGE_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` does not identify an end user account known to the payment provider
      type: object
      properties:
        id:
          $ref: '#/components/schemas/request-id'
        type:
          const: SEND_MT_MESSAGE
        payload:
          type: object
          properties:
            routeConfiguration:
              $ref: '#/components/schemas/payment-route-configuration-properties'
            account:
              $ref: '#/components/schemas/payment-instrument-account-properties'
            message:
              description: |
                The message to send to the end user's device.
              type: string
              minLength: 1
              maxLength: 600
              example: 1234 is your PIN for Aussie Apps
          required:
            - routeConfiguration
            - account
            - message
      required:
        - id
        - type
        - payload
    VALIDATE_PASSPHRASE:
      title: VALIDATE_PASSPHRASE request action (outbound)
      description: |
        Ask the payment provider [adapter] to validate a passphrase for an end user.

        The end user is authenticated using the passphrase provided to the merchant through the payment provider in the Bango Platform.

        ### Supported HTTP responses

        - HTTP 200 OK:
          - [`VALIDATE_PASSPHRASE_RESPONSE`](/schemas/VALIDATE_PASSPHRASE_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
            - `payload.account` does not identify an end user account known to the payment provider
      type: object
      properties:
        id:
          $ref: '#/components/schemas/request-id'
        type:
          const: VALIDATE_PASSPHRASE
        payload:
          type: object
          properties:
            routeConfiguration:
              $ref: '#/components/schemas/payment-route-configuration-properties'
            account:
              $ref: '#/components/schemas/payment-instrument-account-properties'
              description: |
                Account identification data for the end user.
              type: object
            passphrase:
              description: |
                the end user's passphrase authentication to be validated by the payment provider.
              type: string
              minLength: 1
              maxLength: 50
              example: Worry3-Troops-Failed-Sang
          additionalProperties: false
          required:
            - routeConfiguration
            - account
            - passphrase
      required:
        - id
        - type
        - payload
    payment-provider-otpAction:
      title: Payment provider OTP Action
      description: |
        The OTP action for the SEND_OTP operation.
      type: string
      enum:
        - reset
        - resend
        - send
    SEND_OTP:
      title: SEND_OTP request action (outbound)
      description: |
        Ask the payment provider [adapter] to send an OTP to an end user's device. Typically this is an SMS to a phone number, but this request action does not imply or require a specific transport mechanism. The OTP and the message are controlled by the payment provider (contrast with [`SEND_MT_MESSAGE`](/schemas/SEND_MT_MESSAGE), where the Bango Platform owns the OTP and the message). Later, use [`VERIFY_OTP`](/schemas/VERIFY_OTP) to check the end user supplied the correct OTP.

        If there's a problem with the request action, the payment provider [adapter] returns HTTP 400. For example, if the payment provider [adapter] doesn't recognize the account properties in the request, it returns HTTP 400.

        If there's a problem sending the message to the end user, the payment provider [adapter] returns a [`SEND_OTP_RESPONSE`](/schemas/SEND_OTP_RESPONSE) response action including a `status` code.

        ### Supported HTTP responses

        - HTTP 200 OK:
          - [`SEND_OTP_RESPONSE`](/schemas/SEND_OTP_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` does not identify an end user account known to the payment provider
      type: object
      properties:
        id:
          $ref: '#/components/schemas/request-id'
        type:
          const: SEND_OTP
        payload:
          type: object
          properties:
            routeConfiguration:
              $ref: '#/components/schemas/payment-route-configuration-properties'
            account:
              $ref: '#/components/schemas/payment-instrument-account-properties'
            otpAction:
              $ref: '#/components/schemas/payment-provider-otpAction'
          required:
            - routeConfiguration
            - account
            - otpAction
      required:
        - id
        - type
        - payload
    VERIFY_OTP:
      title: VERIFY_OTP request action (outbound)
      description: |
        Ask the payment provider [adapter] to verify an OTP provided by the merchant end user. Used only when the payment provider manages OTPs, and after sending [`SEND_OTP`](/schemas/SEND_OTP).

        If there's a problem with the request action, the payment provider [adapter] returns HTTP 400. For example, if the payment provider [adapter] doesn't recognize the account properties in the request, it returns HTTP 400.

        If there's a problem verifying the OTP, the payment provider [adapter] returns a [`VERIFY_OTP_RESPONSE`](/schemas/VERIFY_OTP_RESPONSE) response action including a `status` code.

        ### Supported HTTP responses

        - HTTP 200 OK:
          - [`VERIFY_OTP_RESPONSE`](/schemas/VERIFY_OTP_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` does not identify an end user account known to the payment provider
      type: object
      properties:
        id:
          $ref: '#/components/schemas/request-id'
        type:
          const: VERIFY_OTP
        payload:
          type: object
          properties:
            routeConfiguration:
              $ref: '#/components/schemas/payment-route-configuration-properties'
            account:
              $ref: '#/components/schemas/payment-instrument-account-properties'
            candidate:
              description: |
                The end user's candidate OTP.
              type: string
              minLength: 1
              maxLength: 100
          required:
            - routeConfiguration
            - account
            - candidate
      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
    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
    payment-provider-account-type-oppa:
      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
    payment-instrument-global-properties-oppa:
      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-oppa'
        countryCode:
          $ref: '#/components/schemas/country-code-iso-3166'
        locale:
          $ref: '#/components/schemas/locale-bcp-47'
        currency:
          $ref: '#/components/schemas/currency-code-iso-4217'
        customerProfile:
          $ref: '#/components/schemas/customerProfile'
      example:
        accountType: prepaid
        locale: en-US
        currency: USD
        customerProfile: saver
    payment-instrument-properties-without-account:
      title: Payment instrument properties
      description: |
        Payment instrument properties, including:
        - Properties that apply universally across all merchants
        - Properties that apply for specific merchants
      type: object
      additionalProperties: false
      properties:
        global:
          $ref: '#/components/schemas/payment-instrument-global-properties-oppa'
        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'
    GET_ELIGIBILITY_RESPONSE:
      title: GET_ELIGIBILITY_RESPONSE response action
      description: |
        Response to a `GET_ELIGIBILITY` action. Contains information about the current eligibility of an end user.
      type: object
      properties:
        id:
          $ref: '#/components/schemas/response-id'
        type:
          const: GET_ELIGIBILITY_RESPONSE
        payload:
          type: object
          properties:
            paymentEligibilityStatus:
              $ref: '#/components/schemas/paymentEligibilityStatus'
            paymentInstrumentProperties:
              $ref: '#/components/schemas/payment-instrument-properties-without-account'
          required:
            - paymentEligibilityStatus
      required:
        - id
        - type
        - payload
    payment-provider-shared:
      title: Data shared between payment provider and merchant
      description: |
        Data shared between the payment provider and the merchant partner as part of a payment resource. Supplied to the merchant with a successful `AUTHORIZE` action response.
      type: object
      properties:
        paymentProviderToMerchant:
          description: |
            Data the payment provider owns (read/write access) and the merchant partner may consume (read access only).

            Constraints:
            - Between 0 and 255 properties
            - Each property value is either:
              - string (length 0 to 255 inclusive)
              - number (-1048575 to +1048575 inclusive)
              - boolean
              - array (between 0 and 255 items) containing a mixture of:
                - string (length 0 to 255 inclusive)
                - number (-1048575 to +1048575 inclusive)

            Note that nested objects ARE NOT permitted.
          type: object
          maxProperties: 255
          additionalProperties:
            oneOf:
              - type: string
                minLength: 0
                maxLength: 255
              - type: number
                minimum: -1048575
                maximum: 1048575
              - type: boolean
              - type: array
                maxItems: 255
                items:
                  oneOf:
                    - type: string
                      minLength: 0
                      maxLength: 255
                    - type: number
                      minimum: -1048575
                      maximum: 1048575
                    - type: boolean
    AUTHORIZE_APPROVED_RESPONSE:
      title: AUTHORIZE_APPROVED_RESPONSE response action
      description: |
        Notification that a request to the payment provider [adapter] to authorize a payment (step 1 of two-step payments) has succeeded. (Denials use the `AUTHORIZE_DENIED_RESPONSE` response action.)

        A payment provider [adapter] may include a `paymentProviderPaymentId` property to supply the Bango Platform with its own unique identifier for the payment. The merchant partner sees this ID in the payment resource.
      type: object
      properties:
        id:
          $ref: '#/components/schemas/response-id'
        type:
          const: AUTHORIZE_APPROVED_RESPONSE
        payload:
          type: object
          properties:
            paymentProviderPaymentId:
              $ref: '#/components/schemas/payment-provider-payment-id'
            shared:
              $ref: '#/components/schemas/payment-provider-shared'
      required:
        - id
        - type
        - payload
    AUTHORIZE_DENIED_RESPONSE:
      title: AUTHORIZE_DENIED_RESPONSE response action
      description: |
        Notification that a request to the payment provider [adapter] to authorize a payment (step 1 of two-step payments) has been denied.

        A payment provider [adapter] includes a `code` and optionally a `message` property with more details.
      type: object
      properties:
        id:
          $ref: '#/components/schemas/response-id'
        type:
          const: AUTHORIZE_DENIED_RESPONSE
        payload:
          type: object
          properties:
            code:
              description: |
                A machine-readable code that indicates why the payment provider denied authorization.

                **NOTE** This is a provisional list of values for `code`
              type: string
              enum:
                - operation-not-supported
                - denied
                - user-invalid
                - user-barred
                - user-suspended
                - user-not-enabled
                - user-insufficient-credit
                - user-spend-limit-exceeded
                - already-in-progress
                - payment-unknown
            message:
              description: |
                An optional human-readable message describing why the payment provider denied authorization.
              type: string
              minLength: 1
              maxLength: 255
            paymentProviderPaymentId:
              $ref: '#/components/schemas/payment-provider-payment-id'
          required:
            - code
      required:
        - id
        - type
        - payload
    CANCEL_AUTH_APPROVED_RESPONSE:
      title: CANCEL_AUTH_APPROVED_RESPONSE response action
      description: |
        Confirmation that a request to the payment provider [adapter] to cancel authorization for a payment has succeeded. (Denials use the `CANCEL_AUTH_DENIED_RESPONSE` response action.)

        A payment provider [adapter] may include a `paymentProviderPaymentId` property to supply the Bango Platform with its own unique identifier for the payment. The merchant partner sees this ID in the payment resource.
      type: object
      properties:
        id:
          $ref: '#/components/schemas/response-id'
        type:
          const: CANCEL_AUTH_APPROVED_RESPONSE
        payload:
          type: object
          properties:
            paymentProviderPaymentId:
              $ref: '#/components/schemas/payment-provider-payment-id'
      required:
        - id
        - type
        - payload
    CANCEL_AUTH_DENIED_RESPONSE:
      title: CANCEL_AUTH_DENIED_RESPONSE response action
      description: |
        Notification that a request to the payment provider [adapter] to cancel authorization for a payment has been denied.

        A payment provider [adapter] includes a `code` and optionally a `message` property with more details.
      type: object
      properties:
        id:
          $ref: '#/components/schemas/response-id'
        type:
          const: CANCEL_AUTH_DENIED_RESPONSE
        payload:
          type: object
          properties:
            code:
              description: |
                A machine-readable code that indicates why the payment provider denied the cancelation request.

                **NOTE** This is a provisional list of values for `code`
              type: string
              enum:
                - operation-not-supported
                - denied
                - expired
                - user-invalid
                - user-barred
                - user-suspended
                - user-not-enabled
                - already-in-progress
                - payment-unknown
            message:
              description: |
                An optional human-readable message describing why the payment provider denied the cancelation request.
              type: string
              minLength: 1
              maxLength: 255
            paymentProviderPaymentId:
              $ref: '#/components/schemas/payment-provider-payment-id'
          required:
            - code
      required:
        - id
        - type
        - payload
    CAPTURE_APPROVED_RESPONSE:
      title: CAPTURE_APPROVED_RESPONSE response action
      description: |
        Confirmation that a request to the payment provider [adapter] to capture a payment (step 2 of two-step payments) has succeeded. (Denials use the `CAPTURE_DENIED_RESPONSE` response action.)

        A payment provider [adapter] may include a `paymentProviderPaymentId` property to supply the Bango Platform with its own unique identifier for the payment. The merchant partner sees this ID in the payment resource.
      type: object
      properties:
        id:
          $ref: '#/components/schemas/response-id'
        type:
          const: CAPTURE_APPROVED_RESPONSE
        payload:
          type: object
          properties:
            paymentProviderPaymentId:
              $ref: '#/components/schemas/payment-provider-payment-id'
      required:
        - id
        - type
        - payload
    CAPTURE_DENIED_RESPONSE:
      title: CAPTURE_DENIED_RESPONSE response action
      description: |
        Notification that a request to the payment provider [adapter] to capture a payment (step 2 of two-step payments) has been denied.

        A payment provider [adapter] includes a `code` and optionally a `message` property with more details.
      type: object
      properties:
        id:
          $ref: '#/components/schemas/response-id'
        type:
          const: CAPTURE_DENIED_RESPONSE
        payload:
          type: object
          properties:
            code:
              description: |
                A machine-readable code that indicates why the payment provider denied capture.

                **NOTE** This is a provisional list of values for `code`
              type: string
              enum:
                - operation-not-supported
                - denied
                - expired
                - user-invalid
                - user-barred
                - user-suspended
                - user-not-enabled
                - user-insufficient-credit
                - user-spend-limit-exceeded
                - already-in-progress
                - payment-unknown
            message:
              description: |
                An optional human-readable message describing why the payment provider denied capture.
              type: string
              minLength: 1
              maxLength: 255
            paymentProviderPaymentId:
              $ref: '#/components/schemas/payment-provider-payment-id'
          required:
            - code
      required:
        - id
        - type
        - payload
    CHARGE_APPROVED_RESPONSE:
      title: CHARGE_APPROVED_RESPONSE response action [plan-p1]
      description: |
        Confirmation that a request to the payment provider [adapter] to charge a payment (one-step payments) has succeeded. (Denials use the `CHARGE_DENIED_RESPONSE` response action.)

        A payment provider [adapter] may include a `paymentProviderPaymentId` property to supply the Bango Platform with its own unique identifier for the payment. The merchant partner DOES NOT see this ID.
      type: object
      properties:
        id:
          $ref: '#/components/schemas/response-id'
        type:
          const: CHARGE_APPROVED_RESPONSE
        payload:
          type: object
          properties:
            paymentProviderPaymentId:
              $ref: '#/components/schemas/payment-provider-payment-id'
      required:
        - id
        - type
        - payload
    CHARGE_DENIED_RESPONSE:
      title: CHARGE_DENIED_RESPONSE response action [plan-p1]
      description: |
        Notification that a request to the payment provider [adapter] to charge a payment (one-step payments) has been denied.

        A payment provider [adapter] includes a `code` and optionally a `message` property with more details.
      type: object
      properties:
        id:
          $ref: '#/components/schemas/response-id'
        type:
          const: CHARGE_DENIED_RESPONSE
        payload:
          type: object
          properties:
            code:
              description: |
                A machine-readable code that indicates why the payment provider denied the charge.

                **NOTE** This is a provisional list of values for `code`
              type: string
              enum:
                - operation-not-supported
                - denied
                - user-invalid
                - user-barred
                - user-suspended
                - user-not-enabled
                - user-insufficient-credit
                - user-spend-limit-exceeded
                - already-in-progress
                - payment-unknown
            message:
              description: |
                An optional human-readable message describing why the payment provider denied the charge.
              type: string
              minLength: 1
              maxLength: 255
            paymentProviderPaymentId:
              $ref: '#/components/schemas/payment-provider-payment-id'
          required:
            - code
      required:
        - id
        - type
        - payload
    REFUND_APPROVED_RESPONSE:
      title: REFUND_APPROVED_RESPONSE response action
      description: |
        Confirmation that a request to the payment provider [adapter] to refund a payment has succeeded. (Denials use the `REFUND_DENIED_RESPONSE` response action.)

        A payment provider [adapter] may include a `paymentProviderPaymentId` property to supply the Bango Platform with its own unique identifier for the payment. The merchant partner sees this ID in the payment resource.
      type: object
      properties:
        id:
          $ref: '#/components/schemas/response-id'
        type:
          const: REFUND_APPROVED_RESPONSE
        payload:
          type: object
          properties:
            paymentProviderPaymentId:
              $ref: '#/components/schemas/payment-provider-payment-id'
      required:
        - id
        - type
        - payload
    REFUND_DENIED_RESPONSE:
      title: REFUND_DENIED_RESPONSE response action
      description: |
        Notification that a request to the payment provider [adapter] to refund a payment has been denied.

        A payment provider [adapter] includes a `code` and optionally a `message` property with more details.
      type: object
      properties:
        id:
          $ref: '#/components/schemas/response-id'
        type:
          const: REFUND_DENIED_RESPONSE
        payload:
          type: object
          properties:
            code:
              description: |
                A machine-readable code that indicates why the payment provider denied the refund.

                **NOTE** This is a provisional list of values for `code`
              type: string
              enum:
                - operation-not-supported
                - denied
                - expired
                - user-invalid
                - user-barred
                - user-suspended
                - user-not-enabled
                - already-in-progress
                - payment-unknown
            message:
              description: |
                An optional human-readable message describing why the payment provider denied the refund.
              type: string
              minLength: 1
              maxLength: 255
            paymentProviderPaymentId:
              $ref: '#/components/schemas/payment-provider-payment-id'
          required:
            - code
      required:
        - id
        - type
        - payload
    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-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'
        customerProfile:
          $ref: '#/components/schemas/customerProfile'
      example:
        accountType: prepaid
        countryCode: US
        locale: en-US
        currency: USD
        customerProfile: saver profile
    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
        userProperties:
          $ref: '#/components/schemas/userProperties'
      example:
        paymentEligibilityStatus: barred
        userProperties:
          token: myUserToken
          accountNickname: 457
    payment-instrument-properties-partial-patch:
      title: Payment instrument properties partial patch object
      description: |
        A **partial** patch object for payment instrument properties. A payment provider [adapter] 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
    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
    NOTIFY_SESSION_FLOW_APPROVED_RESPONSE:
      title: NOTIFY_SESSION_FLOW_APPROVED_RESPONSE response action
      description: |
        Response to a `NOTIFY_SESSION_FLOW` request action.

        Confirmation that the merchant may start the requested identity verification flow, optionally including data to return to the merchant, and optionally initializing payment instrument properties.
      type: object
      properties:
        id:
          $ref: '#/components/schemas/response-id'
        type:
          const: NOTIFY_SESSION_FLOW_APPROVED_RESPONSE
        payload:
          type: object
          properties:
            paymentInstrumentProperties:
              $ref: '#/components/schemas/payment-instrument-properties-partial-patch'
            shared:
              description: |
                The negotiation data shared from the payment provider to the merchant partner
              type: object
              properties:
                nextAction:
                  $ref: '#/components/schemas/nextAction'
                paymentProviderToMerchant:
                  $ref: '#/components/schemas/paymentProviderToMerchant'
      required:
        - id
        - type
        - payload
    NOTIFY_SESSION_FLOW_DENIED_RESPONSE:
      title: NOTIFY_SESSION_FLOW_DENIED_RESPONSE response action
      description: |
        Denial of a merchant partner request to start an identity verification flow.

        A payment provider [adapter] includes a `code` and optionally a `message` property with more details.
      type: object
      properties:
        id:
          $ref: '#/components/schemas/response-id'
        type:
          const: NOTIFY_SESSION_FLOW_DENIED_RESPONSE
        payload:
          type: object
          properties:
            code:
              description: |
                A machine-readable code that indicates why the payment provider denied the identity verification flow.

                **NOTE** This is a provisional list of values for `code`
              type: string
              enum:
                - operation-not-supported
                - denied
            message:
              description: |
                An optional human-readable message describing why the payment provider denied the identity verification flow.
              type: string
              minLength: 1
              maxLength: 255
          required:
            - code
      required:
        - id
        - type
        - payload
    SEND_MT_MESSAGE_RESPONSE:
      title: SEND_MT_MESSAGE_RESPONSE response action
      description: |
        Response to a `SEND_MT_MESSAGE` action. Identifies whether or not the payment provider [adapter] was able to send the message to the end user.

        Note that if the payment provider [adapter] did not recognize the account properties in the request, it returns HTTP 400 for the `SEND_MT_MESSAGE` request action, and not a `SEND_MT_MESSAGE_RESPONSE` response action.

        If the status is `send-request-failure` or `unknown`, this may be reported to the merchant as a `payment-provider-failure` error with `paymentProviderCode` set to `mt-message-send-request-failure`.

        If the status is `send-requested`, this DOES NOT guarantee the message was delivered.
      type: object
      properties:
        id:
          $ref: '#/components/schemas/response-id'
        type:
          const: SEND_MT_MESSAGE_RESPONSE
        payload:
          type: object
          properties:
            status:
              description: |
                The outcome of the payment provider [adapter] attempt to send the message to the end user.

                Possible values:
                - `send-requested`: Request to send the message was accepted. This DOES NOT guarantee the message was delivered
                - `send-request-failure`: Request to send the message was not accepted, and no detailed explanation is available
                - `unknown`: No information is available to indicate whether the message was sent

                Additional `status` values will be added as needed.
              type: string
              enum:
                - send-requested
                - send-request-failure
                - unknown
          required:
            - status
      required:
        - id
        - type
        - payload
    passphrase-status:
      title: passphrase-Status
      description: |
        The status of the passphrase validation as returned by the payment provider

        Possible values:
        - `accepted`: The passphrase provided by the user was accepted by the payment provider
        - `declined`: The passphrase provided by the user was declined by the payment provider
        - `closed`: The passphrase provided by the user was closed by the payment provider
        - `barred`: The passphrase provided by the user was barred by the payment provider
        - `not-enabled`: The passphrase provided by the user was not-enable by the payment provider
        - `unknown`: An error of some kind occurred requesting the validation of the user passphrase to the payment provider
      type: string
      enum:
        - accepted
        - declined
        - closed
        - barred
        - not-enabled
        - unknown
      examples:
        - accepted
    VALIDATE_PASSPHRASE_RESPONSE:
      title: VALIDATE_PASSPHRASE_RESPONSE response action
      description: |
        Response to a `VALIDATE_PASSPHRASE` action. Contains information about the validity of the passphrase provided by the end user.
      type: object
      properties:
        id:
          $ref: '#/components/schemas/response-id'
        type:
          const: VALIDATE_PASSPHRASE_RESPONSE
        payload:
          type: object
          properties:
            status:
              $ref: '#/components/schemas/passphrase-status'
          required:
            - status
      required:
        - id
        - type
        - payload
    SEND_OTP_RESPONSE:
      title: SEND_OTP_RESPONSE response action
      description: |
        Response to a `SEND_OTP` action. Identifies whether or not the payment provider [adapter] was able to (perhaps generate and) send the OTP to the end user.

        Note that if the payment provider [adapter] did not recognize the account properties in the request, it returns HTTP 400 for the `SEND_OTP` request action, and not a `SEND_OTP_RESPONSE` response action.

        If the status is `send-request-failure` or `unknown`, this may be reported to the merchant as a `payment-provider-failure` error with `paymentProviderCode` set to `otp-request-failure`.

        If the status is `send-requested`, this DOES NOT guarantee the message was delivered.
      type: object
      properties:
        id:
          $ref: '#/components/schemas/response-id'
        type:
          const: SEND_OTP_RESPONSE
        payload:
          type: object
          properties:
            status:
              description: |
                The outcome of the payment provider [adapter] attempt to send the OTP to the end user.

                Possible values:
                - `send-requested`: Request to send the OTP was accepted. This DOES NOT guarantee the message was delivered
                - `send-request-denied`: Request to send the OTP was denied for security reasons
                - `send-request-failure`: Request to send the OTP was not accepted, and no detailed explanation is available
                - `unknown`: No information is available to indicate whether the OTP was sent

                Additional `status` values will be added as needed.
              type: string
              enum:
                - send-requested
                - send-request-denied
                - send-request-failure
                - unknown
          required:
            - status
      required:
        - id
        - type
        - payload
    payment-instrument-properties-account-required:
      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'
      required:
        - account
    VERIFY_OTP_RESPONSE:
      title: VERIFY_OTP_RESPONSE response action
      description: |
        Response to a `VERIFY_OTP` action. Identifies whether or not the payment provider [adapter] was able to verify the OTP supplied by the end user, and whether the candidate OTP from the end user was the expected OTP.

        Note that if the payment provider [adapter] did not recognize the account properties in the request, it returns HTTP 400 for the `VERIFY_OTP` request action, and not a `VERIFY_OTP_RESPONSE` response action.

        If the status is `unknown`, this may be reported to the merchant as a `payment-provider-failure` error with `paymentProviderCode` set to `otp-request-failure`.
      type: object
      properties:
        id:
          $ref: '#/components/schemas/response-id'
        type:
          const: VERIFY_OTP_RESPONSE
        payload:
          type: object
          properties:
            status:
              description: |
                The outcome of the payment provider [adapter] attempt to verify the OTP.

                Possible values:
                - `otp-correct`: The candidate OTP from the end user was the expected OTP
                - `otp-incorrect`: The candidate OTP from the end user was not the expected OTP
                - `otp-expired`: The candidate OTP was not checked because the OTP has expired
                - `too-many-attempts`: The candidate OTP was not checked because the maximum number of attempts has been reached
                - `unknown`: No information is available to indicate whether the OTP was verified

                Additional `status` values will be added as needed.
              type: string
              enum:
                - otp-correct
                - otp-incorrect
                - otp-expired
                - too-many-attempts
                - unknown
            paymentInstrumentProperties:
              $ref: '#/components/schemas/payment-instrument-properties-account-required'
          required:
            - status
            - 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'
    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'
    payment-provider-internal-server-error:
      title: internal-server-error [PP]
      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 payment provider believes the request can be retried
              type: boolean
              default: false
        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
    adapter-failure:
      title: adapter-failure
      description: Bango adapter failed
      type: object
      properties:
        code:
          const: adapter-failure
        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 Bango adapter 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/adapter-failure
      required:
        - code
        - meta
        - message
    payment-provider-bad-gateway:
      title: bad-gateway [PP]
      description: Gateway or proxy is unable to complete your request
      type: object
      properties:
        code:
          const: bad-gateway
        meta:
          description: Additional information to help identify the specific error case
          type: object
          properties:
            canRetry:
              description: Whether the payment provider believes the request can be retried
              type: boolean
              default: true
        message:
          description: Human-readable message describing the error
          type: string
          example: The server was unable to complete your request. 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
    PaymentProviderBadGateway:
      allOf:
        - $ref: '#/components/schemas/CommonErrorResponse'
        - properties:
            errors:
              type: array
              items:
                oneOf:
                  - $ref: '#/components/schemas/payment-provider-bad-gateway'
    payment-provider-service-unavailable:
      title: service-unavailable [PP]
      description: Service is unavailable
      type: object
      properties:
        code:
          const: service-unavailable
        meta:
          description: Additional information to help identify the specific error case
          type: object
          properties:
            canRetry:
              description: Whether the payment provider believes the request can be retried
              type: boolean
              default: false
        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
    PaymentProviderServiceUnavailable:
      allOf:
        - $ref: '#/components/schemas/CommonErrorResponse'
        - properties:
            errors:
              type: array
              items:
                oneOf:
                  - $ref: '#/components/schemas/payment-provider-service-unavailable'
    payment-provider-gateway-timeout:
      title: gateway-timeout [PP]
      description: Service is not responding in time
      type: object
      properties:
        code:
          const: gateway-timeout
        meta:
          description: Additional information to help identify the specific error case
          type: object
          properties:
            canRetry:
              description: Whether the payment provider believes the request can be retried
              type: boolean
              default: true
        message:
          description: Human-readable message describing the error
          type: string
          example: The server was unable to complete your request. 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
    PaymentProviderGatewayTimeout:
      allOf:
        - $ref: '#/components/schemas/CommonErrorResponse'
        - properties:
            errors:
              type: array
              items:
                oneOf:
                  - $ref: '#/components/schemas/payment-provider-gateway-timeout'
  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'
    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'
    PaymentProviderBadGatewayErrorResponse:
      description: Bad Gateway
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/PaymentProviderBadGateway'
    PaymentProviderServiceUnavailableErrorResponse:
      description: Service unavailable
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/PaymentProviderServiceUnavailable'
    PaymentProviderGatewayTimeoutErrorResponse:
      description: Gateway Timeout
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/PaymentProviderGatewayTimeout'
