openapi: 3.1.0
info:
  title: Temenos Transact Core Banking Accounts Beneficiaries API
  description: RESTful APIs for Temenos Transact (formerly T24) core banking operations. Provides comprehensive banking functionality organized into domain-driven API categories including Holdings (accounts, deposits, loans, cards), Order (payments, transfers, standing orders), Party (customers, beneficiaries, KYC), Reference (currencies, countries, rates), Product (catalog, conditions), and Enterprise (pricing, bundles). Built on the Arrangement Architecture, a modular business component-based framework enabling reusable product components across retail, corporate, treasury, wealth, and Islamic banking domains. APIs exchange data over HTTP using JSON format with a versioned URL structure following the pattern api/v1.0.0/{domain}/{resource}.
  version: 1.0.0
  contact:
    name: Temenos Developer Support
    url: https://developer.temenos.com/
    email: api.support@temenos.com
  license:
    name: Temenos Terms of Service
    url: https://www.temenos.com/terms-of-service/
  termsOfService: https://www.temenos.com/terms-of-service/
servers:
- url: https://api.temenos.com/api/v1.0.0
  description: Temenos Transact API - Production
- url: https://sandbox.temenos.com/api/v1.0.0
  description: Temenos Transact API - Sandbox
security:
- bearerAuth: []
tags:
- name: Beneficiaries
  description: Manage payment beneficiaries including domestic and international beneficiary registration, validation, and maintenance.
paths:
  /party/beneficiaries:
    get:
      operationId: getBeneficiaries
      summary: Temenos Transact List Beneficiaries
      description: Retrieve registered payment beneficiaries for a customer. Includes domestic and international beneficiaries with their bank details and validation status.
      tags:
      - Beneficiaries
      parameters:
      - $ref: '#/components/parameters/pageSize'
      - $ref: '#/components/parameters/pageStart'
      - $ref: '#/components/parameters/customerId'
      responses:
        '200':
          description: Successful retrieval of beneficiaries
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BeneficiariesResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalServerError'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    post:
      operationId: createBeneficiary
      summary: Temenos Transact Create Beneficiary
      description: Register a new payment beneficiary for a customer. Validates the beneficiary bank details including IBAN, BIC/SWIFT code, and account number format.
      tags:
      - Beneficiaries
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BeneficiaryCreateRequest'
      responses:
        '201':
          description: Beneficiary created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BeneficiaryResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          description: Beneficiary validation failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          $ref: '#/components/responses/InternalServerError'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  schemas:
    PaginationInfo:
      type: object
      description: Pagination metadata for list responses
      properties:
        pageSize:
          type: integer
          description: Number of records per page
          example: 10
        pageStart:
          type: integer
          description: Current page offset
          example: 10
        totalRecords:
          type: integer
          description: Total number of records available
          example: 10
    BeneficiaryCreateRequest:
      type: object
      required:
      - body
      properties:
        header:
          type: object
          properties:
            override:
              type: boolean
          example: example_value
        body:
          type: object
          required:
          - customerId
          - beneficiaryName
          properties:
            customerId:
              type: string
            beneficiaryName:
              type: string
            accountNumber:
              type: string
            iban:
              type: string
            bic:
              type: string
            bankName:
              type: string
            bankCountry:
              type: string
            currency:
              type: string
            beneficiaryType:
              type: string
              enum:
              - DOMESTIC
              - INTERNATIONAL
              - SEPA
            nickname:
              type: string
          example: example_value
    BeneficiariesResponse:
      type: object
      properties:
        header:
          $ref: '#/components/schemas/ResponseHeader'
        body:
          type: array
          items:
            $ref: '#/components/schemas/Beneficiary'
          example: []
        page:
          $ref: '#/components/schemas/PaginationInfo'
    Beneficiary:
      type: object
      description: A registered payment beneficiary
      properties:
        beneficiaryId:
          type: string
          description: Unique beneficiary identifier
          example: '500123'
        customerId:
          type: string
          description: Owning customer identifier
          example: '500123'
        beneficiaryName:
          type: string
          description: Name of the beneficiary
          example: example_value
        accountNumber:
          type: string
          description: Beneficiary account number
          example: example_value
        iban:
          type: string
          description: Beneficiary IBAN
          example: example_value
        bic:
          type: string
          description: Beneficiary bank BIC/SWIFT code
          example: example_value
        bankName:
          type: string
          description: Name of the beneficiary bank
          example: example_value
        bankCountry:
          type: string
          description: Country of the beneficiary bank
          example: example_value
        currency:
          type: string
          description: Default payment currency
          example: example_value
        beneficiaryType:
          type: string
          description: Type of beneficiary
          enum:
          - DOMESTIC
          - INTERNATIONAL
          - SEPA
          example: DOMESTIC
        status:
          type: string
          description: Beneficiary status
          enum:
          - ACTIVE
          - INACTIVE
          - PENDING_VERIFICATION
          example: ACTIVE
        nickname:
          type: string
          description: User-defined nickname for the beneficiary
          example: example_value
    BeneficiaryResponse:
      type: object
      properties:
        header:
          $ref: '#/components/schemas/ResponseHeader'
        body:
          $ref: '#/components/schemas/Beneficiary'
    ErrorResponse:
      type: object
      description: Standard error response structure
      required:
      - header
      properties:
        header:
          type: object
          properties:
            id:
              type: string
              description: Request identifier
            status:
              type: string
              description: Error status
              enum:
              - error
            transactionStatus:
              type: string
              description: Transaction status
          example: example_value
        error:
          type: object
          properties:
            type:
              type: string
              description: Error type classification
            message:
              type: string
              description: Human-readable error message
            code:
              type: string
              description: Machine-readable error code
            details:
              type: array
              description: Detailed error information
              items:
                type: object
                properties:
                  field:
                    type: string
                    description: Field that caused the error
                  message:
                    type: string
                    description: Field-level error message
                  code:
                    type: string
                    description: Field-level error code
          example: example_value
    ResponseHeader:
      type: object
      description: Standard response header returned by all Transact API operations
      properties:
        id:
          type: string
          description: Unique identifier for the resource
          example: abc123
        status:
          type: string
          description: Status of the operation (success, error)
          enum:
          - success
          - error
          example: success
        transactionStatus:
          type: string
          description: Transaction lifecycle status
          enum:
          - Live
          - Unauth
          - Hold
          - Reversed
          example: Live
        audit:
          type: object
          properties:
            parseTime:
              type: integer
              description: Time taken to parse the request in milliseconds
            responseParse:
              type: integer
              description: Time taken to generate the response in milliseconds
          example: example_value
  responses:
    Unauthorized:
      description: Authentication required or token expired
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    BadRequest:
      description: Bad request - invalid parameters or malformed request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    InternalServerError:
      description: Internal server error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  parameters:
    pageStart:
      name: page_start
      in: query
      description: Page token or offset for pagination
      schema:
        type: integer
        default: 0
        minimum: 0
    pageSize:
      name: page_size
      in: query
      description: Number of records to return per page (default 25, max 100)
      schema:
        type: integer
        default: 25
        minimum: 1
        maximum: 100
    customerId:
      name: customerId
      in: query
      description: Filter by customer identifier
      schema:
        type: string
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: OAuth 2.0 Bearer token authentication. Obtain a token from the Temenos authentication endpoint using client credentials or authorization code flow.