Temenos Bulk Payments API

openapi: 3.2.0
info:
  title: Temenos Payments Bulk Payments API
  description: Payment processing and management API supporting multiple payment types including SEPA credit transfers, instant SEPA payments, SWIFT cross-border payments, PSD2 compliant open banking payments, request-to-pay, bulk payment initiation, direct debit management, and payment stop requests. Built on Berlin Group PSD2 API standards with full ISO 20022 messaging support and integrated clearing through the Temenos Payments Hub.
  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/legal-information/website-terms-and-conditions/
  termsOfService: https://www.temenos.com/legal-information/website-terms-and-conditions/
servers:
- url: https://api.temenos.com/payments/v1
  description: Temenos Payments API - Production
- url: https://sandbox.temenos.com/payments/v1
  description: Temenos Payments API - Sandbox
security:
- bearerAuth: []
tags:
- name: Bulk Payments
  description: Handle bulk payment file uploads and manual entry for batch payment processing with approval workflows and status tracking.
paths:
  /bulkPayments:
    get:
      operationId: listBulkPayments
      summary: List Bulk Payment Batches
      description: Retrieve a list of bulk payment batches with their processing status and summary information including total amounts and payment counts.
      tags:
      - Bulk Payments
      parameters:
      - $ref: '#/components/parameters/pageSize'
      - $ref: '#/components/parameters/pageStart'
      - name: status
        in: query
        description: Filter by batch processing status
        schema:
          type: string
          enum:
          - PENDING_APPROVAL
          - APPROVED
          - PROCESSING
          - COMPLETED
          - REJECTED
      responses:
        '200':
          description: Successful retrieval of bulk payment batches
          content:
            application/json:
              schema:
                type: object
                properties:
                  header:
                    $ref: '#/components/schemas/PaginationHeader'
                  body:
                    type: array
                    items:
                      $ref: '#/components/schemas/BulkPayment'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: createBulkPayment
      summary: Create Bulk Payment Batch
      description: Initiate a bulk payment batch by uploading payment instructions for batch processing. Supports file upload and manual entry with configurable approval workflows.
      tags:
      - Bulk Payments
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BulkPaymentCreate'
      responses:
        '201':
          description: Bulk payment batch created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BulkPayment'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /bulkPayments/{batchId}/approve:
    post:
      operationId: approveBulkPayment
      summary: Approve Bulk Payment Batch
      description: Approve a bulk payment batch for processing after review. Applies the configured approval workflow rules.
      tags:
      - Bulk Payments
      parameters:
      - $ref: '#/components/parameters/batchId'
      responses:
        '200':
          description: Bulk payment batch approved
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BulkPayment'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  responses:
    BadRequest:
      description: Invalid request parameters
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: Requested resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: Authentication required or invalid credentials
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  schemas:
    Error:
      type: object
      description: Error response
      properties:
        errorCode:
          type: string
          description: Machine-readable error code
        errorMessage:
          type: string
          description: Human-readable error description
    BulkPaymentCreate:
      type: object
      description: Request body for creating a bulk payment batch
      required:
      - debitAccountId
      - currency
      - payments
      properties:
        debitAccountId:
          type: string
          description: Common debit account
        currency:
          type: string
          description: Batch currency in ISO 4217 format
          pattern: ^[A-Z]{3}$
        valueDate:
          type: string
          format: date
          description: Common value date for all payments
        payments:
          type: array
          description: Individual payment instructions
          minItems: 1
          items:
            type: object
            required:
            - beneficiaryName
            - amount
            properties:
              beneficiaryName:
                type: string
                description: Beneficiary name
              beneficiaryIban:
                type: string
                description: Beneficiary IBAN
              amount:
                type: number
                format: double
                description: Payment amount
              reference:
                type: string
                description: Payment reference
    BulkPayment:
      type: object
      description: Bulk payment batch
      properties:
        batchId:
          type: string
          description: Unique batch identifier
        debitAccountId:
          type: string
          description: Common debit account for the batch
        totalAmount:
          type: number
          format: double
          description: Total batch amount
        currency:
          type: string
          description: Batch currency
        paymentCount:
          type: integer
          description: Number of payments in the batch
        status:
          type: string
          description: Batch processing status
          enum:
          - PENDING_APPROVAL
          - APPROVED
          - PROCESSING
          - COMPLETED
          - REJECTED
        createdDate:
          type: string
          format: date-time
          description: Batch creation timestamp
    PaginationHeader:
      type: object
      description: Pagination metadata for list responses
      properties:
        page_size:
          type: integer
          description: Number of records per page
        page_start:
          type: integer
          description: Starting record number
        total_size:
          type: integer
          description: Total number of records available
  parameters:
    pageStart:
      name: page_start
      in: query
      description: Starting record number for pagination
      schema:
        type: integer
        minimum: 0
        default: 0
    pageSize:
      name: page_size
      in: query
      description: Number of records to return per page
      schema:
        type: integer
        minimum: 1
        maximum: 100
        default: 25
    batchId:
      name: batchId
      in: path
      required: true
      description: Unique bulk payment batch identifier
      schema:
        type: string
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: JWT-based authentication token obtained through the Temenos authentication endpoint.
externalDocs:
  description: Temenos Open Banking and Payments Documentation
  url: https://developer.temenos.com/open-banking&payments