BackBase Approve API

openapi: 3.2.0
info:
  title: Payment Orders Client Approve API
  description: Provides access to querying, initiating, approving and managing (recurring) payment orders, payment order drafts and batch payments.
  version: 2.0.0
servers:
- url: http://localhost:4010
  description: mock-api-server
- url: http://localhost:8080
  description: Springboot default port
- url: https://localhost:8081
  description: 'Best practice: use https'
tags:
- name: approve
  description: Payment approval API.
paths:
  /client-api/v2/payment-orders/{paymentOrderId}/approvals:
    summary: Approvals
    description: Performs an approval operation on the given payment order
    put:
      tags:
      - approve
      description: Approves or rejects a given payment order
      operationId: putApprovalsByPaymentOrderId
      parameters:
      - name: paymentOrderId
        in: path
        description: Payment Order ID
        required: true
        style: simple
        explode: false
        schema:
          maxLength: 36
          type: string
      requestBody:
        description: Approves or rejects a given payment order
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PaymentOrderApprovalPutRequest'
            example:
              $ref: '#/components/examples/payment-orders-approval-payment-order-approval-put-request'
        required: true
      responses:
        '202':
          description: PaymentOrderAccepted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentOrdersPostResponse'
              examples:
                simple:
                  $ref: '#/components/examples/simple-1'
                approved:
                  $ref: '#/components/examples/approved-1'
        '403':
          description: BreachReportError
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BreachReportError'
              example:
                $ref: '#/components/examples/error-breach-report-error'
        '500':
          description: InternalServer
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/internal-server-error'
              example:
                $ref: '#/components/examples/lib-internal-server-error'
        '400':
          description: BadRequest
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/bad-request-error'
              example:
                $ref: '#/components/examples/lib-bad-request-validation-error'
      x-BbAccessControl-resource: Payments
      x-BbAccessControl-function: Different functions per payment type, eg 'SEPA CT', 'US Domestic Wire', etc
      x-BbAccessControl-privilege: view,approve
      summary: Put approvals by payment order id
      x-summary-source: derived
components:
  examples:
    simple-1:
      summary: simple-1
      value:
        id: af2599ef-759a-4b78-8e67-4949055a532b
        status: ENTERED
    payment-orders-approval-payment-order-approval-put-request:
      summary: payment-orders-approval-payment-order-approval-put-request
      value:
        approvalStatus: APPROVED
    lib-bad-request-validation-error:
      summary: lib-bad-request-validation-error
      value:
        message: Bad Request
        errors:
        - message: Value Exceeded. Must be between {min} and {max}.
          key: common.api.shoesize
          context:
            max: '50'
            min: '1'
    error-breach-report-error:
      summary: error-breach-report-error
      value:
        message: Limits has been breached, check the report for more details
        payment:
          id: 7d341c28-6714-11e7-907b-a6006ad3dba0
          status: ENTERED
          originatorAccount:
            arrangementId: 729190df-a421-4937-94fd-5e1a3da132cc
            identification:
              identification: NL53RABO0309349755
              schemeName: IBAN
          instructionPriority: NORM
          requestedExecutionDate: 2017-07-16
          transferTransactionInformation:
            name: Jack Jackson
            instructedAmount:
              amount: '5000.55'
              currencyCode: EUR
            counterpartyAccount:
              identification:
                identification: FR708933019952AUNHQNQ0KZ
                schemeName: IBAN
              arrangementId: fe9d66ae-b927-4ac7-8799-c5a38a596ff2
            counterparty:
              name: Backbase
              postalAddress:
                addressLine1: Jacob Bontiusplaats 9
                zipcode: 1018LL
                city: Amsterdam
                country: NL
            remittanceInformation:
              type: UNSTRUCTURED
              content: Return a debt
          version: 0
        checkTime: 2017-01-31 12:12:12+00:00
        breachReport:
        - limitedEntity:
          - ref: 1234567-12312-123123
            type: Service Agreement
            description: Kuhic, Gislason and Kemmer. SERVICE AGREEMENT
          shadow: false
          currency: EUR
          user-BBID: oleksii
          breachInfo:
          - breachType: THRESHOLD
            breachedLimitType: PERIODIC
            timeframe:
              period: daily
              startTime: 2017-01-31 00:00:00+00:00
              endTime: 2017-01-31 23:59:59+00:00
            currentConsumption: '250.0'
            currentThreshold: '499.9'
          - breachType: CONSUMPTION
            timeframe:
              period: monthly
              startTime: 2017-01-01 00:00:00+00:00
              endTime: 2017-01-31 23:59:59+00:00
            currentConsumption: '9950.0'
            currentThreshold: '10000.0'
        - user-BBID: oleksii
          shadow: false
          currency: EUR
          breachInfo:
          - breachType: CONSUMPTION
            timeframe:
              period: daily
              startTime: 2017-01-31 00:00:00+00:00
              endTime: 2017-01-31 23:59:59+00:00
            currentConsumption: '500.0'
            currentThreshold: '1000.0'
        - limitedEntity:
          - ref: 1234567-12312-123123
            type: Function Access Group
            description: Payments approvers
          - ref: 1234567-12312-123123
            type: Function
            description: Domestic payments
          - ref: Approve
            type: Privilege
            description: Approve
          shadow: false
          currency: EUR
          breachInfo:
          - breachType: THRESHOLD
            timeframe:
              period: daily
              startTime: 2017-01-31 00:00:00+00:00
              endTime: 2017-01-31 23:59:59+00:00
            currentConsumption: '250.0'
            currentThreshold: '499.9'
        - limitedEntity:
          - ref: 1234567-12312-123123
            type: Legal Entity
            description: Kuhic, Gislason and Kemmer
          shadow: false
          currency: EUR
          breachInfo:
          - breachType: CONSUMPTION
            timeframe:
              period: quarterly
              startTime: 2017-01-01 00:00:00+00:00
              endTime: 2017-03-31 23:59:59+00:00
            currentConsumption: '99950.0'
            currentThreshold: '100000.0'
    approved-1:
      summary: approved-1
      value:
        id: af2599ef-759a-4b78-8e67-4949055a532b
        status: ENTERED
        approvalStatus: APPROVED
    lib-internal-server-error:
      summary: lib-internal-server-error
      value:
        message: Description of error
  schemas:
    error-item:
      title: ErrorItem
      type: object
      properties:
        message:
          type: string
          description: Any further information.
        key:
          type: string
          description: '{capability-name}.api.{api-key-name}. For generated validation errors this is the path in the document the error resolves to. e.g. object name + ''.'' + field'
        context:
          type: object
          additionalProperties:
            type: string
          description: Context can be anything used to construct localised messages.
    Bank:
      type: object
      properties:
        bankBranchCode:
          maxLength: 11
          type: string
          description: Some code to identify a bank office, p.e. ABA routing transit number (9) or Swift BIC code (11)
        name:
          maxLength: 140
          type: string
          description: The name of a bank
        postalAddress:
          $ref: '#/components/schemas/PostalAddress'
        bic:
          pattern: ^([A-Z0-9]){4}([A-Z]){2}([A-Z0-9]){2}([A-Z0-9]{3})?$
          type: string
          description: Business identifier code as specified by ISO 9362:2014
      description: This object is used to identify the counterparty or correspondent bank.
    BreachReportItem:
      required:
      - breachInfo
      type: object
      properties:
        limitedEntity:
          type: array
          description: When not set, user-BBID must be set
          items:
            $ref: '#/components/schemas/EntityDescription'
        shadow:
          type: boolean
          description: Shadow limit flag. Applicable for certain entity-types
        currency:
          type: string
          description: Currency code
        user-BBID:
          type: string
          description: BBID of the user for whom the personal limit is assigned
        breachInfo:
          type: array
          description: List of breached periodic limits related to a particular limitable entity
          items:
            $ref: '#/components/schemas/BreachInfo'
    ContextualInformation:
      required:
      - externalUserId
      - origin
      - serviceAgreementId
      type: object
      properties:
        externalUserId:
          maxLength: 64
          type: string
          description: The (unique and human readable) external user id of the user.
        internalUserId:
          maxLength: 36
          minLength: 1
          type: string
          description: General purpose identifier. Can be UUID but does not have to.
        serviceAgreementId:
          maxLength: 36
          minLength: 1
          type: string
          description: General purpose identifier. Can be UUID but does not have to.
        legalEntityId:
          maxLength: 36
          minLength: 1
          type: string
          description: General purpose identifier. Can be UUID but does not have to.
        origin:
          maxLength: 200
          minLength: 1
          type: string
          description: Name the system where endpoint is calling from
    PaymentOrdersPostResponse:
      title: PaymentOrdersPostResponse
      required:
      - id
      - status
      type: object
      properties:
        id:
          type: string
        status:
          type: string
          description: The internal DBS status of the payment order..
          enum:
          - DRAFT
          - ENTERED
          - READY
          - ACCEPTED
          - PROCESSED
          - REJECTED
          - CANCELLED
          - CANCELLATION_PENDING
          - CONFIRMATION_PENDING
          - CONFIRMATION_DECLINED
        bankStatus:
          maxLength: 35
          type: string
          description: Internal status of the payment or batch order in the core banking system.
        reasonCode:
          maxLength: 4
          type: string
          description: Reason code the core banking system accepted/rejected the payment or batch.
        reasonText:
          maxLength: 35
          type: string
          description: Human readable reason the core banking system accepted/rejected the payment or batch.
        errorDescription:
          maxLength: 105
          type: string
          description: Additional information from the core banking system on why the payment was refused.
        nextExecutionDate:
          type: string
          description: The execution date of the payment that the core system calculated.
          format: date
        paymentSetupId:
          maxLength: 128
          type: string
          description: Generated when the PISP sets up the payments before the Backbase authorization flow.
        paymentSubmissionId:
          maxLength: 128
          type: string
          description: Generated when the PISP submits the payment which is after the Backbase authorization flow.
        approvalStatus:
          maxLength: 70
          type: string
          description: The status as returned by the approval service.
        transferFee:
          $ref: '#/components/schemas/Currency'
        exchangeRateInformation:
          $ref: '#/components/schemas/ExchangeRateInformation'
        additions:
          type: object
          additionalProperties:
            type: string
    TimeFrame:
      required:
      - endTime
      - period
      - startTime
      type: object
      properties:
        period:
          type: string
        startTime:
          type: string
          format: date-time
        endTime:
          type: string
          format: date-time
    bad-request-error:
      title: BadRequestError
      required:
      - message
      type: object
      properties:
        message:
          type: string
          description: Any further information
        errors:
          type: array
          description: Detailed error information
          items:
            $ref: '#/components/schemas/error-item'
    Actions:
      type: array
      description: An array of actions that could be performed on a payment order. Actions that can be done are dependant on the payment itself.
      items:
        type: string
        description: The actions that can be performed by the user (with the current context). This field is not evaluated when payment is requested by support employee on behalf of another user.
        enum:
        - APPROVE
        - FINAL_APPROVE
        - REJECT
        - CANCEL
        - DELETE
    CounterpartyAccount:
      required:
      - identification
      properties:
        accountType:
          maxLength: 10
          type: string
          description: The type of the account, e.g. for ACH we have CHECKING/SAVINGS
        arrangementId:
          maxLength: 36
          minLength: 1
          type: string
          description: The unique arrangement id.
        externalArrangementId:
          maxLength: 70
          minLength: 1
          type: string
          description: The external unique arrangement id.
        identification:
          $ref: '#/components/schemas/Identification'
        name:
          maxLength: 140
          type: string
          description: Default name field used in DBS
      description: The counterparty Account is the original account identification plus the arrangement if applicable.
    EntityDescription:
      required:
      - description
      - ref
      - type
      type: object
      properties:
        ref:
          type: string
        type:
          type: string
        description:
          type: string
    IdentifiedTransaction:
      required:
      - counterparty
      - counterpartyAccount
      - instructedAmount
      type: object
      properties:
        counterparty:
          $ref: '#/components/schemas/InvolvedParty'
        counterpartyAccount:
          $ref: '#/components/schemas/CounterpartyAccount'
        counterpartyBank:
          $ref: '#/components/schemas/Bank'
        instructedAmount:
          $ref: '#/components/schemas/Currency'
        correspondentBank:
          $ref: '#/components/schemas/Bank'
        intermediaryBank:
          $ref: '#/components/schemas/Bank'
        messageToBank:
          maxLength: 140
          type: string
          description: The message to the bank used for US domestic wire payments
        targetCurrency:
          pattern: ^[A-Z]{3}$
          type: string
          description: The alpha-3 code (complying with ISO 4217) of the currency
        remittanceInformation:
          $ref: '#/components/schemas/RemittanceInformation'
        endToEndIdentification:
          maxLength: 35
          type: string
        mandateIdentifier:
          maxLength: 15
          type: string
          description: The mandate identifier, of the counter party, giving permission for the debit order.
        chargeBearer:
          type: string
          description: 'Indicated who pays the fees for an international transfer. Possible values: OUR(originator), BEN(beneficiary or SHA(shared).'
          enum:
          - OUR
          - BEN
          - SHA
        transferFee:
          $ref: '#/components/schemas/Currency'
        exchangeRateInformation:
          $ref: '#/components/schemas/ExchangeRateInformation'
      description: The object defining the identified transaction, which means the counterparty will have a arrangementId where applicable.
    ExchangeRateInformation:
      type: object
      properties:
        currencyCode:
          pattern: ^[A-Z]{3}$
          type: string
          description: Currency in which the rate of exchange is expressed in a currency exchange.
        rate:
          maximum: 1.0e+18
          minimum: -1.0e+18
          type: string
          description: The factor used for conversion of an amount from one currency to another.
        rateType:
          type: string
          description: Specifies the type used to complete the currency exchange.
          enum:
          - ACTUAL
          - INDICATIVE
          - AGREED
        contractIdentification:
          maxLength: 256
          type: string
          description: Unique and unambiguous reference to the foreign exchange contract agreed between the initiating party/creditor and the debtor agent.
      description: The detailed information on the exchange rate that has been used in the payment transaction.
    BreachReportError:
      required:
      - message
      type: object
      properties:
        message:
          type: string
        payment:
          $ref: '#/components/schemas/IdentifiedPaymentOrder'
        checkTime:
          type: string
          format: date-time
        breachReport:
          type: array
          items:
            $ref: '#/components/schemas/BreachReportItem'
    InvolvedParty:
      required:
      - name
      type: object
      properties:
        name:
          maxLength: 140
          type: string
        role:
          type: string
          description: These are the possible values the role of an involved party can  have.
          enum:
          - CREDITOR
          - DEBTOR
        postalAddress:
          $ref: '#/components/schemas/PostalAddress'
        recipientId:
          maxLength: 15
          type: string
          description: Used for ACH Credit to indicate the id of the recipient
      description: This object is a common denominator for the debtor or creditor party.
    PostalAddress:
      type: object
      properties:
        addressLine1:
          maxLength: 70
          type: string
        addressLine2:
          maxLength: 70
          type: string
        streetName:
          maxLength: 70
          type: string
        postCode:
          maxLength: 16
          type: string
        town:
          maxLength: 35
          type: string
        countrySubDivision:
          maxLength: 35
          type: string
        country:
          maxLength: 2
          type: string
      description: Postal address object with fields
    Currency:
      $ref: '#/components/schemas/currency'
    Schedule:
      required:
      - every
      - 'on'
      - startDate
      - transferFrequency
      type: object
      properties:
        nonWorkingDayExecutionStrategy:
          type: string
          description: Strategy for executing payments on non-working days
          enum:
          - BEFORE
          - AFTER
          - NONE
        transferFrequency:
          type: string
          description: Denotes how frequently the transfer should be made
          enum:
          - ONCE
          - DAILY
          - WEEKLY
          - BIWEEKLY
          - MONTHLY
          - QUARTERLY
          - YEARLY
        'on':
          type: integer
          description: Denotes day on which transfer should be executed. For WEEKLY transferFrequency it will be 1..7 indicating weekday. For BIWEEKLY it will be 1..14 indicating the day of the two week period. For MONTHLY it will be 1..31 indicating day of month. For YEARLY it will be 1..12 indicating month of the year.
          format: int32
        startDate:
          type: string
          description: When to start executing the schedule. First transfer will be executed on first calculated date by schedule after this date.
          format: date
        endDate:
          type: string
          description: When to stop transfers. Transfers will not be executed after this date. Only one of endDate and repeat is possible. If neither repeat nor endDate is provided transfer will be executed until canceled
          format: date
        repeat:
          type: integer
          description: Number of transfer to be executed. Only one of endDate and repeat is possible. If neither repeat nor endDate is provided transfer will be executed until canceled
          format: int32
        every:
          type: integer
          description: Indicates skip interval of transfer. 1 would mean execute every time, 2 - every other time
          format: int32
          enum:
          - 1
          - 2
        nextExecutionDate:
          type: string
          description: Date when the next payment will be executed, taking in consideration bank holidays and cut-off times. It will be only retrieved when getting payments, it will be dismissed when creating or updating.
          format: date
      description: Schedule for recurring transfer. Mandatory if paymentMode is RECURRING
    PaymentOrderApprovalPutRequest:
      title: ApprovalStatusPutRequest
      required:
      - approvalStatus
      type: object
      properties:
        approvalStatus:
          type: string
          description: The options for approval.
          enum:
          - APPROVED
          - REJECTED
        comment:
          maxLength: 140
          type: string
          description: When approving or rejecting, the user can add comments which would explain the reason for the action.
    currency:
      title: Currency
      required:
      - amount
      - currencyCode
      type: object
      properties:
        amount:
          maximum: 1.0e+18
          minimum: -1.0e+18
          type: string
          description: The amount in the specified currency
        currencyCode:
          pattern: ^[A-Z]{3}$
          type: string
          description: The alpha-3 code (complying with ISO 4217) of the currency that qualifies the amount
        additions:
          type: object
          additionalProperties:
            type: string
          description: Additional properties
    IdentifiedPaymentOrder:
      required:
      - id
      - status
      - version
      properties:
        id:
          pattern: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-5][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$
          type: string
          description: Unique identification of the payment order.
        approvalId:
          pattern: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-5][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$
          type: string
          description: The id of the approval request that is or was used to get this item approved.
        status:
          type: string
          description: The internal DBS status of the payment order..
          enum:
          - DRAFT
          - ENTERED
          - READY
          - ACCEPTED
          - PROCESSED
          - REJECTED
          - CANCELLED
          - CANCELLATION_PENDING
          - CONFIRMATION_PENDING
          - CONFIRMATION_DECLINED
        bankStatus:
          maxLength: 35
          type: string
          description: Internal status of the payment or batch order in the core banking system.
        reasonCode:
          maxLength: 4
          type: string
          description: Reason code the core banking system accepted/rejected the payment or batch.
        reasonText:
          maxLength: 35
          type: string
          description: Human readable reason the core banking system accepted/rejected the payment or batch.
        errorDescription:
          maxLength: 105
          type: string
          description: Additional information from the core banking system on why the payment was refused.
        createdBy:
          maxLength: 128
          type: string
          description: Creator user info.
        createdAt:
          type: string
          description: Date and time indicating when the payment was created
          format: date-time
        updatedBy:
          maxLength: 128
          type: string
          description: Updater user info.
        updatedAt:
          type: string
          description: Date and time indicating when the payment was updated
          format: date-time
        actions:
          $ref: '#/components/schemas/Actions'
        version:
          type: integer
          description: Indication of what version the payment order currently has
          format: int32
        contextualInformation:
          $ref: '#/components/schemas/ContextualInformation'
        intraLegalEntity:
          type: boolean
          description: Indication if this payment was an intra-company payment.
        originatorAccountCurrency:
          pattern: ^[A-Z]{3}$
          type: string
          description: Currency code of the payment order originating account
        confirmationId:
          maxLength: 36
          minLength: 1
          type: string
          description: The confirmation id for transaction signing.
        paymentSetupId:
          maxLength: 128
          type: string
          description: Generated when the PISP sets up the payments before the Backbase authorization flow.
        paymentSubmissionId:
          maxLength: 128
          type: string
          description: Generated when the PISP submits the payment which is after the Backbase authorization flow.
        originator:
          $ref: '#/components/schemas/InvolvedParty'
        originatorAccount:
          $ref: '#/components/schemas/OriginatorAccount'
        batchBooking:
          type: boolean
          description: Indicate whenever there should be only one debit posting for the whole set of instructions
        instructionPriority:
          type: string
          description: Specify the priority of execution of the payment order.
          enum:
          - NORM
          - HIGH
        requestedExecutionDate:
          type: string
          description: The preferred date for the payment order to be executed.
          format: date
        paymentMode:
          type: string
          description: Denotes whether payment will be single or will be recurring
          enum:
          - SINGLE
          - RECURRING
        paymentType:
          maxLength: 22
          minLength: 1
          type: string
          description: The type of payment.
        entryClass:
          maxLength: 3
          type: string
          description: Used for ACH Standard Entry Class (SEC) Code to designate how the transaction was authorized by the originator.
        schedule:
          $ref: '#/components/schemas/Schedule'
        transferTransactionInformation:
          $ref: '#/components/schemas/IdentifiedTransaction'
        totalAmount:
          $ref: '#/components/schemas/Currency'
        additions:
          type: object
          additionalProperties:
            type: string
    BreachInfo:
      required:
      - breachType
      - currentConsumption
      - currentThreshold
      type: object
      properties:
        breachType:
          type: string
          enum:
          - THRESHOLD
          - CONSUMPTION
        breachedLimitType:
          type: string
          enum:
          - PERIODIC
          - TRANSACTIONAL
        timeframe:
          $ref: '#/components/schemas/TimeFrame'
        currentConsumption:
          type: string
          description: The amount in the specified currency
        currentThreshold:
          type: string
          description: The amount in the specified currency
    Identification:
      required:
      - identification
      - schemeName
      type: object
      properties:
        identification:
          maxLength: 36
          type: string
          description: The identifier of the account. Can be a regular account number, or an ID.
        schemeName:
          type: string
          description: This describes the type of the account identifier. ID will mean it refers to an account known within DBS.
          enum:
          - IBAN
          - BBAN
          - ID
          - EXTERNAL_ID
    internal-server-error:
      title: InternalServerError
      type: object
      properties:
        message:
          type: string
          description: Further Information
      description: Represents HTTP 500 Internal Server Error
    OriginatorAccount:
      required:
      - arrangementId
      - identification
      properties:
        arrangementId:
          maxLength: 36
          minLength: 1
          type: string
          description: The unique arrangement id.
        externalArrangementId:
          maxLength: 70
          minLength: 1
          type: string
          description: The external unique arrangement id.
        identification:
          $ref: '#/components/schemas/Identification'
        name:
          maxLength: 140
          type: string
          description: This is the name of the account, and not the name of the account holder.
      description: The product identification of the originator
    RemittanceInformation:
      required:
      - content
      - type
      type: object
      properties:
        type:
          type: string
          description: When type is structured it consists of some XML tags used when the transaction was uploaded.
          enum:
          - STRUCTURED
          - UNSTRUCTURED
        content:
          maxLength: 140
          type: string
          description: The content of the remittance information.
      description: This is the object representation of the remittance info and can contain different types of remittance info. It is only used in responses, not for input requests!