openapi: 3.0.3
info:
  title: Open Banking API
  description: >
    A comprehensive Open Banking API specification encompassing Information APIs, 
    Single Payment APIs, Recurring Payments, and Request/Offer to Pay functionalities.
  version: 1.0.0
  contact:
    name: API Support
    email: support@openbanking.example.com

servers:
  - url: https://api.bopenbanking.com/open-banking/v1
    description: Production API
  - url: https://dev.api.bopenbanking.com/open-banking/v1
    description: Development API
  - url: https://test.api.bopenbanking.com/open-banking/v1
    description: Test API
  - url: https://{apiId}.execute-api.{region}.amazonaws.com/v1/open-banking/v1
    description: AWS API Gateway invoke URL (fallback)
    variables:
      apiId:
        default: your-api-id
      region:
        default: eu-west-2

tags:
  - name: Information
    description: APIs for accessing account details, balances, and transaction histories.
  - name: Payments
    description: APIs for initiating single, immediate payments.
  - name: Recurring Payments
    description: APIs for establishing standing orders and subscription payments.
  - name: Request to Pay
    description: Endpoints for a payee to request funds from a payer.
  - name: Offer to Pay
    description: Endpoints for a payer to offer funds to a payee.

paths:
  # ==========================================
  # 1. Information APIs
  # ==========================================
  /accounts:
    get:
      tags:
        - Information
      summary: Get Accounts
      description: Retrieve a list of authorized accounts for the authenticated user.
      responses:
        '200':
          description: Successful retrieval of accounts
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccountListResponse'
  
  /accounts/{AccountId}/balances:
    get:
      tags:
        - Information
      summary: Get Account Balances
      description: Retrieve the balance(s) for a specific account.
      parameters:
        - name: AccountId
          in: path
          required: true
          description: Unique identifier for the account
          schema:
            type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BalanceResponse'

  /accounts/{AccountId}/transactions:
    get:
      tags:
        - Information
      summary: Get Account Transactions
      description: Retrieve a list of transactions for a specific account.
      parameters:
        - name: AccountId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransactionListResponse'

  # ==========================================
  # 2. Payment APIs
  # ==========================================
  /payments:
    post:
      tags:
        - Payments
      summary: Initiate Single Payment
      description: Create a single immediate payment instruction.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PaymentInitiation'
      responses:
        '201':
          description: Payment successfully initiated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentResponse'

  # ==========================================
  # 3. Recurring Payments
  # ==========================================
  /recurring-payments:
    post:
      tags:
        - Recurring Payments
      summary: Initiate Recurring Payment
      description: Create a recurring payment instruction (e.g., Standing Order).
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RecurringPaymentInitiation'
      responses:
        '201':
          description: Recurring payment successfully established
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RecurringPaymentResponse'

  # ==========================================
  # 4. Request to Pay / Offer to Pay
  # ==========================================
  /request-to-pay:
    post:
      tags:
        - Request to Pay
      summary: Initiate a Request to Pay (RtP)
      description: Securely request money from a payer (e.g., biller requesting payment).
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RequestToPay'
      responses:
        '201':
          description: Request to pay created and sent to payer
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RequestToPayResponse'

  /offer-to-pay:
    post:
      tags:
        - Offer to Pay
      summary: Initiate an Offer to Pay
      description: Proactively offer a payment to a payee (e.g., refund offer).
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OfferToPay'
      responses:
        '201':
          description: Offer to pay created and sent to payee
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OfferToPayResponse'

components:
  schemas:
    # -------------------------
    # Shared Schemas
    # -------------------------
    CurrencyAmount:
      type: object
      required:
        - Amount
        - Currency
      properties:
        Amount:
          type: string
          pattern: '^\d{1,13}\.\d{1,5}$'
          example: "150.00"
        Currency:
          type: string
          pattern: '^[A-Z]{3,3}$'
          example: "GBP"
          
    AccountIdentification:
      type: object
      required:
        - SchemeName
        - Identification
      properties:
        SchemeName:
          type: string
          example: "UK.OBIE.SortCodeAccountNumber"
        Identification:
          type: string
          example: "80200112345678"
        Name:
          type: string
          example: "John Doe"

    # -------------------------
    # Information Schemas
    # -------------------------
    AccountListResponse:
      type: object
      properties:
        Data:
          type: array
          items:
            type: object
            properties:
              AccountId:
                type: string
                example: "acc-12345"
              Currency:
                type: string
                example: "GBP"
              AccountType:
                type: string
                example: "Retail"
              AccountSubType:
                type: string
                example: "CurrentAccount"
    BalanceResponse:
      type: object
      properties:
        Data:
          type: object
          properties:
            AccountId:
              type: string
              example: "acc-12345"
            BalanceAmount:
              $ref: '#/components/schemas/CurrencyAmount'
            CreditDebitIndicator:
              type: string
              enum: [Credit, Debit]
              example: "Credit"
    TransactionListResponse:
      type: object
      properties:
        Data:
          type: array
          items:
            type: object
            properties:
              TransactionId:
                type: string
                example: "txn-98765"
              Amount:
                $ref: '#/components/schemas/CurrencyAmount'
              CreditDebitIndicator:
                type: string
                enum: [Credit, Debit]
              Status:
                type: string
                example: "Booked"
              BookingDateTime:
                type: string
                format: date-time

    # -------------------------
    # Payment Schemas
    # -------------------------
    PaymentInitiation:
      type: object
      required:
        - InstructionIdentification
        - EndToEndIdentification
        - InstructedAmount
        - CreditorAccount
      properties:
        InstructionIdentification:
          type: string
          example: "INSTR-001"
        EndToEndIdentification:
          type: string
          example: "E2E-001"
        InstructedAmount:
          $ref: '#/components/schemas/CurrencyAmount'
        CreditorAccount:
          $ref: '#/components/schemas/AccountIdentification'
        RemittanceInformation:
          type: object
          properties:
            Reference:
              type: string
              example: "Invoice 1234"
              
    PaymentResponse:
      type: object
      properties:
        PaymentId:
          type: string
          example: "pmt-887766"
        Status:
          type: string
          example: "Pending"
        CreationDateTime:
          type: string
          format: date-time

    # -------------------------
    # Recurring Payment Schemas
    # -------------------------
    RecurringPaymentInitiation:
      type: object
      required:
        - Frequency
        - FirstPaymentDateTime
        - InstructedAmount
        - CreditorAccount
      properties:
        Frequency:
          type: string
          description: "e.g., EvryDay, EvryWorkgDay, IntrvlWkDay:01:02 (every other week on a Tuesday)"
          example: "IntrvlMnthDay:01:01"
        FirstPaymentDateTime:
          type: string
          format: date-time
        NextPaymentDateTime:
          type: string
          format: date-time
        FinalPaymentDateTime:
          type: string
          format: date-time
        InstructedAmount:
          $ref: '#/components/schemas/CurrencyAmount'
        CreditorAccount:
          $ref: '#/components/schemas/AccountIdentification'
          
    RecurringPaymentResponse:
      type: object
      properties:
        RecurringPaymentId:
          type: string
          example: "rp-112233"
        Status:
          type: string
          example: "Active"

    # -------------------------
    # Request/Offer to Pay Schemas
    # -------------------------
    RequestToPay:
      type: object
      required:
        - PayeeName
        - PayerIdentifier
        - AmountRequested
        - DueDate
      properties:
        PayeeName:
          type: string
          example: "Utility Company Ltd"
        PayerIdentifier:
          type: string
          description: "Proxy ID, Email, or Mobile Number of the person being asked to pay."
          example: "+447123456789"
        AmountRequested:
          $ref: '#/components/schemas/CurrencyAmount'
        DueDate:
          type: string
          format: date
          example: "2026-08-01"
        Reference:
          type: string
          example: "Electric Bill July"
          
    RequestToPayResponse:
      type: object
      properties:
        RequestToPayId:
          type: string
          example: "rtp-554433"
        Status:
          type: string
          enum: [Sent, Accepted, Rejected, Paid]
          example: "Sent"

    OfferToPay:
      type: object
      required:
        - PayerName
        - PayeeIdentifier
        - AmountOffered
      properties:
        PayerName:
          type: string
          example: "John Doe"
        PayeeIdentifier:
          type: string
          description: "Proxy ID, Email, or Mobile Number of the person being offered payment."
          example: "jane.doe@example.com"
        AmountOffered:
          $ref: '#/components/schemas/CurrencyAmount'
        Reference:
          type: string
          example: "Dinner split"
          
    OfferToPayResponse:
      type: object
      properties:
        OfferToPayId:
          type: string
          example: "otp-998877"
        Status:
          type: string
          enum: [Sent, Accepted, Rejected, Paid]
          example: "Sent"