openapi: 3.1.0
info:
  title: Charge requests
  version: 1.1.0
  description: |
    # Overview
    This API is for resellers using the optional Billing & Charging module. It provides information on the outbound charge request which is sent to the reseller when a payment is due.

    # Change log
    **2025-06-18** | v.1.1.0
    - COMING SOON - metadata added for DVM-specific fields (in merchantToPaymentProvider)
    **2025-06-13** | v.1.0.0
    - Initial release of DVM Billing & Charging outbound charge requests
    - This is a cut down view of the Payments charge API focusing on just the use cases needed for DVM

servers:
  - url: https://reseller.url
    description: Server belonging to the reseller 

security:
  - basic: []

paths:
  '/actions':
    post:
      summary: Bango sends a charge request to the reseller
      parameters:
        - in: header
          name: Bango-Request-Action
          schema:
            type: string
            enum: 
              - CHARGE
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CHARGE'
            examples:
              DVM charge request:
                value:
                  id: 2adf1639-bb50-4df7-b8a0-79a0cd4f2277
                  type: CHARGE
                  payload:
                    routeConfiguration:
                      merchantId: BANGO_TEL
                      paymentProviderId: BANGO_TEL
                    paymentAction:
                      bangoPaymentId: d8f8da00-fcfe-427a-b79c-3faa807f49bf
                      actionAmount:
                        amount: 10
                        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 - 6 months free
                        category: SUBSCRIPTION
                        price:
                          amount: 10
                          currency: USD
                      shared:
                        merchantToPaymentProvider:
                          offerId: 0ac240d1-b5b9-46ab-b6be-580df8282fdd
                          consumerOfferId: ee8bc745-646e-4c2b-8d85-148a8a608b64
                          billingPlanId: 05605fa1-c2ed-4aea-82b9-9344ccf36f21
                          invoiceId: 3dd8c615-89b4-474c-86e3-f4a61d4f4129
                          chargeEffectiveTs: 2025-08-18T03:12:23.122Z
                    paymentInstrumentProperties:
                      account:
                        accountId: Billing-identifier
      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/CHARGE_APPROVED_RESPONSE'
                  - $ref: '#/components/schemas/CHARGE_DENIED_RESPONSE'
        '204':
          description: |
            The action in the request was acknowledged by the recipient and no response action was required
        '400':
          $ref: '#/components/responses/BadRequestErrorResponse'
        '500':
          description: |
            An internal server error occurred
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/payment-provider-internal-server-error'

                required:
                  - errors
        '503':
          $ref: '#/components/responses/PaymentProviderServiceUnavailableErrorResponse'
components:
  securitySchemes:
    basic:
      type: http
      description: Basic authentication
      scheme: basic
  schemas:
    CHARGE:
      type: object
      required:
        - id
        - type
        - payload
      properties:
        id:
          type: string
          format: uuid
          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:
          const: CHARGE
        payload:
          type: object
          required:
            - routeConfiguration
            - paymentAction
            - paymentInstrumentProperties
          properties:
            routeConfiguration:
              $ref: '#/components/schemas/payment-route-configuration-properties'
            paymentAction:
              $ref: '#/components/schemas/payment-charge-request-properties'
            paymentInstrumentProperties:
              $ref: '#/components/schemas/payment-instrument-properties'
          
    payment-route-configuration-properties:
      description: Properties of a billing route
      type: object
      required:
        - paymentProviderId
        - merchantId
      properties:
        merchantId:
          type: string 
          minLength: 2
          maxLength: 50
          description: Friendly unique identifier for the partner. For DVM billing & charging this is the same as the payment provider id
        paymentProviderId:
          type: string 
          minLength: 2
          maxLength: 50
          description: Friendly unique identifier for the partner. For DVM billing & charging, this is the unique id of the reseller. 

    payment-charge-request-properties:
      description: Charge payment request properties
      type: object
      required:
        - bangoPaymentId
        - actionAmount
        - balance
        - saleItem
        - shared
      properties:
        bangoPaymentId:
          type: string 
          format: uuid
          description: Bango's unique identifier for the payment
        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'

    payment-instrument-properties:
      description: Payment instrument properties
      type: object
      properties:
        account:
          $ref: '#/components/schemas/payment-instrument-account-properties'

    payment-instrument-account-properties:
      title: Payment instrument account properties
      description: |
        Properties of a payment instrument that identify the account with the Customer. 
      type: object
      properties:
        accountId:
          type: string
          description: For DVM Billing & Charging where the reseller is using the CX, this is the billable identity provided during SSO.
    
    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
 
    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

    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
        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 charging, 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:
      description: An item (product or service) purchased in whole or part by a payment.
      type: object
      required:
        - description
        - price
      properties:
        description:
          description: A description for the item
          type: string
          minLength: 1
          maxLength: 255
        category:
          description: An optional category for the item
          type: string
          minLength: 1
          maxLength: 255
        price:
          allOf:
            - $ref: '#/components/schemas/monetary-value-required'
            - title: The full payment expected for this item
      
    payment-shared:
      title: Data shared between Content Provider and Customer
      description: |
        Additional metadata from DVM shared with the payment provider to enable the partner to associate the charge request with other DVM ids, such as offerId and consumerOfferId.
      type: object
      properties:
        merchantToPaymentProvider:
          $ref: '#/components/schemas/merchant-To-Payment-Provider'

    merchant-To-Payment-Provider: 
      description: Data Bango owns (read/write access) and the Reseller may consume (read access only)
      type: object
      properties:
        offerId:
          type: string
          format: uuid
          description: The unique id of the offer the consumer has taken 
        consumerOfferId:
          type: string
          format: uuid
          description: The unique id of the consumer's bundle
        billingPlanId:
          type: string
          format: uuid
          description: The unique id of the billing plan used to manage the lifecycle of the consumer's bundle (e.g. subscription)
        invoiceId:
          type: string
          format: uuid
          description: The unique id of the invoice associated to this charge. Useful for support and correlation with reports
        chargeEffectiveTs:
          type: string
          format: date-time 
          description: ISO-8601 format to milliseconds. The original due date of the charge request


    payment-provider-payment-id:
      description: |
        The Customer's own unique identifier for the payment. Not necessarily a UUID. Bango assumes it is unique.

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

        The current value is given to the Content Provider in the payment resource.
      type: string
      minLength: 1
      maxLength: 255

    
    CHARGE_APPROVED_RESPONSE:
      title: CHARGE_APPROVED_RESPONSE response action [plan-p1]
      description: |
        Confirmation that a request to the Customer to charge a payment (one-step charging) has succeeded. (Denials use the `CHARGE_DENIED_RESPONSE` response action.)

        A Customer may include a `paymentProviderPaymentId` property to supply the Bango Platform with its own unique identifier for the payment. The Content Provider partner DOES NOT see this ID.
      type: object
      properties:
        id:
          type: string
          description: The unique identifier for the request action to which this is a response
        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 Customer to charge a payment (one-step charging) has been denied.

        A Customer includes a `code` and optionally a `message` property with more details.
      type: object
      properties:
        id:
          type: string
          description: The unique identifier for the request action to which this is a response
        type:
          const: CHARGE_DENIED_RESPONSE
        payload:
          type: object
          properties:
            code:
              description: |
                A machine-readable code that indicates why the Customer 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 Customer denied the charge.
              type: string
              minLength: 1
              maxLength: 255
            paymentProviderPaymentId:
              $ref: '#/components/schemas/payment-provider-payment-id'
          required:
            - code
      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
        url:
          description: URL to more information about the error type
          type: string
          format: url
      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
        url:
          description: URL to more information about the error type
          type: string
          format: url
      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
          required:
            - param
        message:
          description: Human-readable message describing the error
          type: string
        url:
          description: URL to more information about the error type
          type: string
          format: url
      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
        url:
          description: URL to more information about the error type
          type: string
          format: url
      required:
        - code
        - meta
        - message
    InvalidCredentials:
      allOf:
        - $ref: '#/components/schemas/CommonErrorResponse'
        - properties:
            errors:
              type: array
              items:
                $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
        url:
          description: URL to more information about the error type
          type: string
          format: url
      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
        url:
          description: URL to more information about the error type
          type: string
          format: url
      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 Customer believes the request can be retried
              type: boolean
              default: false
        message:
          description: Human-readable message describing the error
          type: string
        url:
          description: URL to more information about the error type
          type: string
          format: url
      required:
        - code
        - meta
        - message
    
    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 Customer believes the request can be retried
              type: boolean
              default: false
        message:
          description: Human-readable message describing the error
          type: string
        url:
          description: URL to more information about the error type
          type: string
          format: url
      required:
        - code
        - meta
        - message
    PaymentProviderServiceUnavailable:
      allOf:
        - $ref: '#/components/schemas/CommonErrorResponse'
        - properties:
            errors:
              type: array
              items:
                oneOf:
                  - $ref: '#/components/schemas/payment-provider-service-unavailable'
  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'
    
    PaymentProviderServiceUnavailableErrorResponse:
      description: Service unavailable
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/PaymentProviderServiceUnavailable'