Deutsche Bank Transaction Authorization API

openapi: 3.2.0
info:
  title: dbapi-transactionAuthorization Transaction Authorization API
  description: Accessing sensitive data like ID card information or performing actions such as initiating payments or investment orders need a second factor for authentication (2FA). The Transaction Authorization API lets you easily create proof tokens for 2FA that can be used with other APIs.
  termsOfService: https://developer.db.com/termsandconditions
  contact:
    url: https://developer.db.com/contact
    email: bank.api@db.com
  version: v2
servers:
- url: https://simulator-api.db.com:443/gw/dbapi/others/transactionAuthorization/v1
tags:
- name: Transaction Authorization
paths:
  /challenges/methods:
    get:
      tags:
      - Transaction Authorization
      summary: Returns the challenge methods usable for the customer during 2FA
      description: This service provides an overview of the customer's challenge methods and their respective status.
      operationId: getChallengeMethodsV2
      parameters:
      - name: Correlation-Id
        in: header
        description: Free form key controlled by the caller e.g. uuid
        required: false
        schema:
          maxLength: 50
          type: string
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChallengeMethodsAndTypes'
        '400':
          description: Unsuccessful operation, returns http status 400. See 'example' property for possible values.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
              - code: 2
                message: Invalid value for %s.
              - code: 3
                message: 'Invalid value for %s: %s.'
              - code: 16
                message: 'OTP invalid challenge response: %s.'
              - code: 17
                message: Invalid OTP.
              - code: 102
                message: Invalid value for parameter externalOrderReference or securityAccountId.
              - code: 111
                message: 2FA method is not ACTIVE.
              - code: 112
                message: OTP invalid challenge response.
              - code: 113
                message: OTP no challenge issued.
              - code: 114
                message: Unable to identify transaction by Id.
              - code: 127
                message: Booking date from must precede booking date to.
              - code: 131
                message: Invalid value for 'sortBy'. Valid values are 'bookingDate[ASC]' and 'bookingDate[DESC]'.
              - code: 132
                message: not supported
              - code: 138
                message: it seems that you started a non pushTAN challenge. Please use the PATCH endpoint to continue
              - code: 139
                message: it seems that you started a pushTAN challenge. Please use the GET endpoint to continue
              - code: 609
                message: Only one price should be provided for the order limit
              - code: 616
                message: Order not in orderbook
              - code: 634
                message: ExpiryDate is before current date
              - code: 639
                message: Either WKN or ISIN must be provided
              - code: 640
                message: invalid preview Signature
              - code: 641
                message: preview Signature expired
              - code: 642
                message: preview Signature order parameter mismatch
              - code: 643
                message: Unique external order reference missing
              - code: 668
                message: Security data not found
              - code: 670
                message: Market place ID not provided
        '401':
          description: Unsuccessful operation, returns http status 401. See 'example' property for possible values.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
              - code: 401
                message: The requested function requires a SCA Level Authentication.
              - code: 646
                message: Daily order limit exceeded
      security:
      - api_auth_code:
        - read_partners_legi
        - order_securities
        - instant_sepa_credit_transfers
        - sepa_direct_debit_core
        - sepa_credit_transfers
        - sepa_direct_debit_B2B
        - bulk_sepa_credit_transfers
      - api_db_smart_access:
        - instant_sepa_credit_transfers
        - sepa_direct_debit_core
        - sepa_credit_transfers
        - sepa_direct_debit_B2B
        - bulk_sepa_credit_transfers
        - bulk_instant_sepa_credit_transfers
  /challenges:
    post:
      tags:
      - Transaction Authorization
      summary: Initiate a challenge request
      description: This service generates a challenge request for the given method and transaction details. It returns among other details a unique id which can be used in further processing afterwards.
      operationId: createChallengeV2
      parameters:
      - name: Correlation-Id
        in: header
        description: Free form key controlled by the caller e.g. uuid
        required: false
        schema:
          maxLength: 50
          type: string
      requestBody:
        description: Input parameters to start a challenge
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ChallengeStart'
        required: true
      responses:
        '201':
          description: successful operation
          headers:
            location:
              description: URI of the created challenge resource
              style: simple
              explode: false
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChallengeRequest'
        '400':
          description: Unsuccessful operation, returns http status 400. See 'example' property for possible values.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
              - code: 2
                message: Invalid value for %s.
              - code: 3
                message: 'Invalid value for %s: %s.'
              - code: 16
                message: 'OTP invalid challenge response: %s.'
              - code: 17
                message: Invalid OTP.
              - code: 102
                message: Invalid value for parameter externalOrderReference or securityAccountId.
              - code: 111
                message: 2FA method is not ACTIVE.
              - code: 112
                message: OTP invalid challenge response.
              - code: 113
                message: OTP no challenge issued.
              - code: 114
                message: Unable to identify transaction by Id.
              - code: 127
                message: Booking date from must precede booking date to.
              - code: 131
                message: Invalid value for 'sortBy'. Valid values are 'bookingDate[ASC]' and 'bookingDate[DESC]'.
              - code: 132
                message: not supported
              - code: 138
                message: it seems that you started a non pushTAN challenge. Please use the PATCH endpoint to continue
              - code: 139
                message: it seems that you started a pushTAN challenge. Please use the GET endpoint to continue
              - code: 609
                message: Only one price should be provided for the order limit
              - code: 616
                message: Order not in orderbook
              - code: 634
                message: ExpiryDate is before current date
              - code: 639
                message: Either WKN or ISIN must be provided
              - code: 640
                message: invalid preview Signature
              - code: 641
                message: preview Signature expired
              - code: 642
                message: preview Signature order parameter mismatch
              - code: 643
                message: Unique external order reference missing
              - code: 668
                message: Security data not found
              - code: 670
                message: Market place ID not provided
        '401':
          description: Unsuccessful operation, returns http status 401. See 'example' property for possible values.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
              - code: 401
                message: The requested function requires a SCA Level Authentication.
              - code: 646
                message: Daily order limit exceeded
      security:
      - api_auth_code:
        - read_partners_legi
        - order_securities
        - instant_sepa_credit_transfers
        - sepa_direct_debit_core
        - sepa_credit_transfers
        - sepa_direct_debit_B2B
        - bulk_sepa_credit_transfers
      - api_db_smart_access:
        - instant_sepa_credit_transfers
        - sepa_direct_debit_core
        - sepa_credit_transfers
        - sepa_direct_debit_B2B
        - bulk_sepa_credit_transfers
        - bulk_instant_sepa_credit_transfers
      x-codegen-request-body-name: challengeStart
  /challenges/{id}:
    get:
      tags:
      - Transaction Authorization
      summary: Verify a PushTAN challenge request
      description: This service checks the status of a previously initated challenge request identified by the given id.
      operationId: verifyPushTANChallengeV2
      parameters:
      - name: id
        in: path
        description: Identifier for the challenge resource
        required: true
        style: simple
        explode: false
        schema:
          type: string
      - name: Correlation-Id
        in: header
        description: Free form key controlled by the caller e.g. uuid
        required: false
        schema:
          maxLength: 50
          type: string
      responses:
        '200':
          description: successful operation
          headers:
            location:
              description: URI of the created challenge resource
              style: simple
              explode: false
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChallengeResult'
        '400':
          description: Unsuccessful operation, returns http status 400. See 'example' property for possible values.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
              - code: 2
                message: Invalid value for %s.
              - code: 3
                message: 'Invalid value for %s: %s.'
              - code: 16
                message: 'OTP invalid challenge response: %s.'
              - code: 17
                message: Invalid OTP.
              - code: 102
                message: Invalid value for parameter externalOrderReference or securityAccountId.
              - code: 111
                message: 2FA method is not ACTIVE.
              - code: 112
                message: OTP invalid challenge response.
              - code: 113
                message: OTP no challenge issued.
              - code: 114
                message: Unable to identify transaction by Id.
              - code: 127
                message: Booking date from must precede booking date to.
              - code: 131
                message: Invalid value for 'sortBy'. Valid values are 'bookingDate[ASC]' and 'bookingDate[DESC]'.
              - code: 132
                message: not supported
              - code: 138
                message: it seems that you started a non pushTAN challenge. Please use the PATCH endpoint to continue
              - code: 139
                message: it seems that you started a pushTAN challenge. Please use the GET endpoint to continue
              - code: 609
                message: Only one price should be provided for the order limit
              - code: 616
                message: Order not in orderbook
              - code: 634
                message: ExpiryDate is before current date
              - code: 639
                message: Either WKN or ISIN must be provided
              - code: 640
                message: invalid preview Signature
              - code: 641
                message: preview Signature expired
              - code: 642
                message: preview Signature order parameter mismatch
              - code: 643
                message: Unique external order reference missing
              - code: 668
                message: Security data not found
              - code: 670
                message: Market place ID not provided
        '401':
          description: Unsuccessful operation, returns http status 401. See 'example' property for possible values.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
              - code: 401
                message: The requested function requires a SCA Level Authentication.
              - code: 646
                message: Daily order limit exceeded
      security:
      - api_auth_code:
        - read_partners_legi
        - order_securities
        - instant_sepa_credit_transfers
      - api_db_smart_access:
        - instant_sepa_credit_transfers
        - sepa_direct_debit_core
        - sepa_credit_transfers
        - sepa_direct_debit_B2B
        - bulk_sepa_credit_transfers
        - bulk_instant_sepa_credit_transfers
    patch:
      tags:
      - Transaction Authorization
      summary: Reply to a challenge request
      description: If given the correct challenge response for a previously initiated challenge request, this service returns a proof token.
      operationId: verifyChallengeV2
      parameters:
      - name: id
        in: path
        description: Identifier for the challenge resource
        required: true
        style: simple
        explode: false
        schema:
          type: string
      - name: Correlation-Id
        in: header
        description: Free form key controlled by the caller e.g. uuid
        required: false
        schema:
          maxLength: 50
          type: string
      requestBody:
        description: Challenge response
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ChallengeResponse'
        required: true
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChallengeResult'
        '400':
          description: Unsuccessful operation, returns http status 400. See 'example' property for possible values.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
              - code: 2
                message: Invalid value for %s.
              - code: 3
                message: 'Invalid value for %s: %s.'
              - code: 16
                message: 'OTP invalid challenge response: %s.'
              - code: 17
                message: Invalid OTP.
              - code: 102
                message: Invalid value for parameter externalOrderReference or securityAccountId.
              - code: 111
                message: 2FA method is not ACTIVE.
              - code: 112
                message: OTP invalid challenge response.
              - code: 113
                message: OTP no challenge issued.
              - code: 114
                message: Unable to identify transaction by Id.
              - code: 127
                message: Booking date from must precede booking date to.
              - code: 131
                message: Invalid value for 'sortBy'. Valid values are 'bookingDate[ASC]' and 'bookingDate[DESC]'.
              - code: 132
                message: not supported
              - code: 138
                message: it seems that you started a non pushTAN challenge. Please use the PATCH endpoint to continue
              - code: 139
                message: it seems that you started a pushTAN challenge. Please use the GET endpoint to continue
              - code: 609
                message: Only one price should be provided for the order limit
              - code: 616
                message: Order not in orderbook
              - code: 634
                message: ExpiryDate is before current date
              - code: 639
                message: Either WKN or ISIN must be provided
              - code: 640
                message: invalid preview Signature
              - code: 641
                message: preview Signature expired
              - code: 642
                message: preview Signature order parameter mismatch
              - code: 643
                message: Unique external order reference missing
              - code: 668
                message: Security data not found
              - code: 670
                message: Market place ID not provided
        '401':
          description: Unsuccessful operation, returns http status 401. See 'example' property for possible values.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
              - code: 401
                message: The requested function requires a SCA Level Authentication.
              - code: 646
                message: Daily order limit exceeded
      security:
      - api_auth_code:
        - read_partners_legi
        - order_securities
        - instant_sepa_credit_transfers
        - sepa_direct_debit_core
        - sepa_credit_transfers
        - sepa_direct_debit_B2B
        - bulk_sepa_credit_transfers
      - api_db_smart_access:
        - instant_sepa_credit_transfers
        - sepa_direct_debit_core
        - sepa_credit_transfers
        - sepa_direct_debit_B2B
        - bulk_sepa_credit_transfers
        - bulk_instant_sepa_credit_transfers
      x-codegen-request-body-name: challengeResponse
  /challenges/{id}/method:
    patch:
      tags:
      - Transaction Authorization
      summary: Switch the authorization method
      description: Switch the authorization method for a previously initiated challenge request to a different method.
      operationId: switchMethodV2
      parameters:
      - name: id
        in: path
        description: Identifier for the challenge resource
        required: true
        style: simple
        explode: false
        schema:
          type: string
      - name: Correlation-Id
        in: header
        description: Free form key controlled by the caller e.g. uuid
        required: false
        schema:
          maxLength: 50
          type: string
      requestBody:
        description: Authorization method
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ChallengeRequestSwitchMethod'
        required: true
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChallengeRequest'
        '400':
          description: Unsuccessful operation, returns http status 400. See 'example' property for possible values.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
              - code: 2
                message: Invalid value for %s.
              - code: 3
                message: 'Invalid value for %s: %s.'
              - code: 16
                message: 'OTP invalid challenge response: %s.'
              - code: 17
                message: Invalid OTP.
              - code: 102
                message: Invalid value for parameter externalOrderReference or securityAccountId.
              - code: 111
                message: 2FA method is not ACTIVE.
              - code: 112
                message: OTP invalid challenge response.
              - code: 113
                message: OTP no challenge issued.
              - code: 114
                message: Unable to identify transaction by Id.
              - code: 127
                message: Booking date from must precede booking date to.
              - code: 131
                message: Invalid value for 'sortBy'. Valid values are 'bookingDate[ASC]' and 'bookingDate[DESC]'.
              - code: 132
                message: not supported
              - code: 138
                message: it seems that you started a non pushTAN challenge. Please use the PATCH endpoint to continue
              - code: 139
                message: it seems that you started a pushTAN challenge. Please use the GET endpoint to continue
              - code: 609
                message: Only one price should be provided for the order limit
              - code: 616
                message: Order not in orderbook
              - code: 634
                message: ExpiryDate is before current date
              - code: 639
                message: Either WKN or ISIN must be provided
              - code: 640
                message: invalid preview Signature
              - code: 641
                message: preview Signature expired
              - code: 642
                message: preview Signature order parameter mismatch
              - code: 643
                message: Unique external order reference missing
              - code: 668
                message: Security data not found
              - code: 670
                message: Market place ID not provided
        '401':
          description: Unsuccessful operation, returns http status 401. See 'example' property for possible values.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
              - code: 401
                message: The requested function requires a SCA Level Authentication.
              - code: 646
                message: Daily order limit exceeded
      security:
      - api_auth_code:
        - read_partners_legi
        - order_securities
        - instant_sepa_credit_transfers
        - sepa_direct_debit_core
        - sepa_credit_transfers
        - sepa_direct_debit_B2B
        - bulk_sepa_credit_transfers
      - api_db_smart_access:
        - instant_sepa_credit_transfers
        - sepa_direct_debit_core
        - sepa_credit_transfers
        - sepa_direct_debit_B2B
        - bulk_sepa_credit_transfers
        - bulk_instant_sepa_credit_transfers
      x-codegen-request-body-name: switchMethod
components:
  schemas:
    ChallengeRequestSwitchMethod:
      required:
      - method
      type: object
      properties:
        method:
          $ref: '#/components/schemas/ChallengeMethodType'
    ChallengeMethodType:
      type: string
      description: Challenge method
      enum:
      - MTAN
      - PHOTOTAN
      - PUSHTAN
    ChallengeStart:
      required:
      - method
      - requestData
      - requestType
      type: object
      properties:
        method:
          $ref: '#/components/schemas/ChallengeMethodType'
        requestType:
          type: string
          description: The type of the challenge to start.
          enum:
          - TRANSFER_PARTNER_LEGI_DATA
          - SECURITIES_ORDER_ENTRY
          - SECURITIES_ORDER_MODIFY
          - SECURITIES_ORDER_DELETE
          - SECURITIES_ORDER_SESSION
          - INSTANT_SEPA_CREDIT_TRANSFERS
          - SEPA_TRANSFER_GRANT
          - SEPA_TRANSFER_CANCELLATION
          - SEPA_BULK_MONEY_TRANSFER_CREATE
          - SEPA_BULK_MONEY_TRANSFER_CANCEL
        requestData:
          type: object
          properties: {}
          description: object depending on requestType. E.g. SECURITIES_ORDER_ENTRY use model ChallengeRequestDataSecuritiesOrderEntry.
        language:
          type: string
          description: The language that should be used in customer facing texts created in the challenge process, i.e. SMS or photoTAN app. ISO-639-1 code.
          default: de
          enum:
          - de
          - en
    ChallengeMethodsAndTypes:
      required:
      - methods
      type: object
      properties:
        methods:
          type: array
          items:
            $ref: '#/components/schemas/ChallengeMethodItem'
    ChallengeMethodMetadata:
      type: object
      properties:
        mobilePhoneNumber:
          type: string
          description: The telephone number the short message is being sent to
        activeDevicesCount:
          type: integer
          description: Number of active devices for this method type.
    ChallengeMethodItem:
      required:
      - method
      - status
      type: object
      properties:
        method:
          $ref: '#/components/schemas/ChallengeMethodType'
        status:
          type: string
          description: Challenge method status
          enum:
          - ACTIVE
          - INACTIVE
          - DEACTIVATED
          - DEVICE_STATUS_ACTIVATING
          - PERMANENTLY_LOCKED
          - TEMPORARILY_LOCKED
          - UNKNOWN
        metadata:
          $ref: '#/components/schemas/ChallengeMethodMetadata'
    ErrorResponse:
      required:
      - code
      - message
      type: object
      properties:
        code:
          type: integer
          description: The error code
        message:
          type: string
          description: Description of the belonging error code.
        messageId:
          type: string
          description: dbAPI internal message-id (unique identifier) that allow reference to each of your API calls.
      description: Default error response message
    ChallengeResult:
      type: object
      properties:
        challengeProofToken:
          type: string
          description: In case of a one-time/single transaction authorization it is valid once, for the current user, the provided request type and the current access_token only. The returned one-time/single transaction authorization should be treated as random string, with no structure and semantic. In case of a session transaction authorization it is time-based
        status:
          type: string
          description: Specifies the status
          enum:
          - PENDING
          - EXPIRED
          - REJECTED
          - VALIDATED
          - EIDP_ERROR
    ChallengeRequest:
      required:
      - id
      - method
      type: object
      properties:
        id:
          type: string
          description: the ID of the created challenge request
        method:
          $ref: '#/components/schemas/ChallengeMethodType'
        challenge:
          type: object
          properties: {}
          description: The sub-type of the response challenge. Depending on the value see swagger model ChallengeMethodMTAN or ChallengeMethodPHOTOTAN. This is actually a constrain of the swagger 2.0 spec.
    ChallengeResponse:
      required:
      - challengeResponse
      type: object
      properties:
        challengeResponse:
          type: string
          description: 'The TAN token to the created challenge. '
  securitySchemes:
    api_auth_code:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://simulator-api.db.com:443/gw/oidc/oauth2/authorize
          tokenUrl: https://simulator-api.db.com:443/gw/oidc/oauth2/token
          scopes:
            read_partners_legi: Grants read access to legitimation data of the current partner/customer. This data is only available for natural persons. Legitimation data contains information, e.g. about the document type, document number and document issue date for the given customer.
            order_securities: Order Securities
            instant_sepa_credit_transfers: Initiate and check status of Instant SEPA Credit Transfers
            sepa_direct_debit_core: Initiate and check status of SEPA Direct Debit Core
            sepa_direct_debit_B2B: Initiate and check status of SEPA Direct Debit B2B
            bulk_sepa_credit_transfers: Initiate and check status of Bulk SEPA Credit Transfers
            sepa_credit_transfers: Initiate and check status of SEPA Credit Transfers
            openid: Request access to OpenId Connect functionality
            offline_access: Request an OAuth2 Refresh Token
    api_db_smart_access:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://simulator-api.db.com:443/gw/oidc/oauth2/token
          scopes:
            bulk_instant_sepa_credit_transfers: Initiate and check status of Bulk Instant SEPA Credit Transfers
            instant_sepa_credit_transfers: Initiate and check status of Instant SEPA Credit Transfers
            sepa_direct_debit_core: Initiate and check status of SEPA Direct Debit Core
            sepa_direct_debit_B2B: Initiate and check status of SEPA Direct Debit B2B
            bulk_sepa_credit_transfers: Initiate and check status of Bulk SEPA Credit Transfers
            sepa_credit_transfers: Initiate and check status of SEPA Credit Transfers
x-original-swagger-version: '2.0'