Deutsche Bank Risk Management API

openapi: 3.2.0
info:
  title: Merchant-Server II REST Services Risk Management API
  version: v2.1
  description: The Risk Management API contains endpoints to add and remove risk list entries and to calculate a risk score.
servers:
- url: https://testmerch.directpos.de/rest-api/services/v2.1/
security:
- bearerAuth: []
tags:
- name: Risk Management
  description: The Risk Management API contains endpoints to add and remove risk list entries and to calculate a risk score.
paths:
  /riskmanagement/entry/{event_id}:
    post:
      tags:
      - Risk Management
      summary: Adds data to or deletes data from the positive or the negative list
      operationId: riskmanagementEntryPost
      parameters:
      - name: Merchant-ID
        in: header
        description: Unique identification of the merchant for whom the transaction is carried out. This parameter is  required if the `Merchant-ID` cannot be derived from the `client_id` you used for authentication.
        required: false
        style: simple
        explode: false
        schema:
          maxLength: 10
          minLength: 10
          pattern: '[0-9]+'
          type: string
      - name: event_id
        in: path
        description: A unique ID for the event.
        required: true
        style: simple
        explode: false
        schema:
          maxLength: 50
          minLength: 1
          pattern: '[\/0-9a-zA-Z_.:,\-+*$%]+'
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RiskmanagementEntryRequest'
            examples:
              sample21:
                summary: Sample risk management entry request.
                description: sample21
                value:
                  credit_card_data:
                    number: '4000056655665556'
                    code: '123'
                    cardholder: Card T. Holder
                    expiry_date:
                      year: 2028
                      month: 11
                  bank_account:
                    bic: HYVEDEMMXXX
                    iban: DE02700202700010108669
                    account_holder: Rene Meier
                    bank_name: UniCredit Bank - HypoVereinsbank
                  address:
                    first_name: Fritz
                    last_name: Mustermann
                    address_line_1: Musterteichstr 18
                    address_line_2: EG R. 184
                    address_line_3: Wohnhaus
                    state: SN
                    postal_code: '94347'
                    city: Musterhausen
                    country: DE
                  billing_address:
                    first_name: Heinz
                    last_name: Mustermann
                    address_line_1: Musterstraße 18
                    address_line_2: EG Rechnungsraum. 184
                    address_line_3: Rechnungsgebäude/Buchhaltung
                    state: SN
                    postal_code: '84347'
                    city: Musterstadt
                    country: DE
                    email: heinz.mustermann@example.com
                    phone_contact:
                      phone_type: MOBILE
                      phone_number: '+442071838750'
                  shipping_address:
                    first_name: Klaus
                    last_name: Mustermann
                    address_line_1: Musterstratße 7
                    address_line_2: 2. OG Lieferraum 333
                    address_line_3: Lieferhaus
                    state: BE
                    postal_code: '10243'
                    city: Musterdorf
                    country: DE
                  amount_total:
                    amount: '100050'
                    currency: EUR
                  basket:
                    basket_id: 123456-basketId-dummy
                    order_amount:
                      amount: '100050'
                      currency: EUR
                    shipping_costs:
                      amount: '50'
                      currency: EUR
                    basket_type: PHYSICAL
                    basket_items:
                    - name: productName1
                      description: productDescription1
                      reference: reference1
                      quantity:
                        quantity_amount: 1
                        quantity_unit: pcs
                      unit_price:
                        net: '84034'
                        gross: '100000'
                        currency: EUR
                        tax: '1900'
                      item_discount:
                        net: '0'
                        gross: '0'
                        currency: EUR
                        tax: '1900'
                      extensions:
                        riskcheck_data:
                          riskcheck_type: SHIPPING_ONLY
                          distributor_product_sku: '1234567890'
                          gift_card_currency: EUR
                          is_gift: 'false'
                          product_risk: LOW
                          risk_check_passenger:
                            type: ADT
                            status: standard
                            phone:
                              phone_type: MOBILE
                              phone_number: '+4917223456789'
                            first_name: Maria
                            last_name: Musterfrau
                            id: B7564
                            email: maria.musterfrau@passenger.com
                            country: DE
                          shipping_destination_types: RESIDENTIAL
                  device_information:
                    cookies_accepted: 'true'
                    http_accept_browser_value: text/html, application/xhtml+xml, application/xml;q=0.9, image/webp, */*;q=0.8
                    http_accept_content: text/html, application/xhtml+xml, application/xml;q=0.9, image/webp, */*;q=0.8
                    color_depth: B24
                    http_browser_email: mustermann@example.com
                    http_browser_java_enabled: 'true'
                    http_browser_java_script_enabled: 'true'
                    http_browser_language: de-DE
                    http_browser_screen_height: '1080'
                    http_browser_screen_width: '1920'
                    http_browser_time_difference: '60'
                    ip_address: 192.168.0.1
                    user_agent: Mozilla
                    user_agent_browser_value: Mozilla/5.0 (X11; Linux x86_64; rv:78.0) Gecko/20100101 Firefox/78.0
                  customer_information:
                    date_of_birth: '1985-12-30'
                    gender: FEMALE
                    title: Prof. Dr. Dr.
                    personal_identifications: []
                    contacts:
                      phone_contacts:
                      - phone_type: MOBILE
                        phone_number: '+442071838750'
                      - phone_type: FAX
                        phone_number: '+442071838751'
                  reason: SUSPECTED
                  action: DELETE
                  list_name: NEGATIVE
      responses:
        '400':
          description: Response in case of an error. Includes a response code and an error message.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
        '401':
          description: Unauthorized request. Response body may be empty.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
        '200':
          description: Indicates the list interaction to add/remove an entry was performed. Result can be success or information regarding the problems occured.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RiskmanagementEntryResponse'
  /riskmanagement/scoring/{event_id}:
    post:
      tags:
      - Risk Management
      summary: Calculates risk score of given data
      operationId: riskmanagementScoringPost
      parameters:
      - name: Merchant-ID
        in: header
        description: Unique identification of the merchant for whom the transaction is carried out. This parameter is  required if the `Merchant-ID` cannot be derived from the `client_id` you used for authentication.
        required: false
        style: simple
        explode: false
        schema:
          maxLength: 10
          minLength: 10
          pattern: '[0-9]+'
          type: string
      - name: event_id
        in: path
        description: A unique ID for the event.
        required: true
        style: simple
        explode: false
        schema:
          maxLength: 50
          minLength: 1
          pattern: '[\/0-9a-zA-Z_.:,\-+*$%]+'
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RiskmanagementScoringRequest'
            examples:
              sample21:
                summary: Sample risk management scoring request.
                description: sample21
                value:
                  credit_card_data:
                    number: '4000056655665556'
                    code: '123'
                    cardholder: Card T. Holder
                    expiry_date:
                      year: 2028
                      month: 11
                  bank_account:
                    bic: HYVEDEMMXXX
                    iban: DE02700202700010108669
                    account_holder: Rene Meier
                    bank_name: UniCredit Bank - HypoVereinsbank
                  address:
                    first_name: Fritz
                    last_name: Mustermann
                    address_line_1: Musterteichstr 18
                    address_line_2: EG R. 184
                    address_line_3: Wohnhaus
                    state: SN
                    postal_code: '94347'
                    city: Musterhausen
                    country: DE
                  billing_address:
                    first_name: Heinz
                    last_name: Mustermann
                    address_line_1: Musterstraße 18
                    address_line_2: EG Rechnungsraum. 184
                    address_line_3: Rechnungsgebäude/Buchhaltung
                    state: SN
                    postal_code: '84347'
                    city: Musterstadt
                    country: DE
                    email: heinz.mustermann@example.com
                    phone_contact:
                      phone_type: MOBILE
                      phone_number: '+442071838750'
                  amount_total:
                    amount: '100050'
                    currency: EUR
                  basket:
                    basket_id: 123456-basketId-dummy
                    order_amount:
                      amount: '100000'
                      currency: EUR
                    shipping_costs:
                      amount: '50'
                      currency: EUR
                    basket_type: PHYSICAL
                    basket_items:
                    - name: productName1
                      description: productDescription1
                      reference: reference1
                      quantity:
                        quantity_amount: 1
                        quantity_unit: pcs
                      unit_price:
                        net: '84034'
                        gross: '100000'
                        currency: EUR
                        tax: '1900'
                      item_discount:
                        net: '0'
                        gross: '0'
                        currency: EUR
                        tax: '1900'
                      extensions:
                        riskcheck_data:
                          riskcheck_type: SHIPPING_ONLY
                          distributor_product_sku: '1234567890'
                          gift_card_currency: EUR
                          is_gift: 'false'
                          product_risk: LOW
                          risk_check_passenger:
                            type: ADT
                            status: standard
                            phone:
                              phone_type: MOBILE
                              phone_number: '+4917223456789'
                            first_name: Maria
                            last_name: Musterfrau
                            id: B7564
                            email: maria.musterfrau@passenger.com
                            country: DE
                          shipping_destination_types: RESIDENTIAL
                  shipping_address:
                    first_name: Klaus
                    last_name: Mustermann
                    email: klaus-mustermann-shipping@example.com
                    address_line_1: Musterstratße 7
                    address_line_2: 2. OG Lieferraum 333
                    address_line_3: Lieferhaus
                    state: BE
                    postal_code: '10243'
                    city: Musterdorf
                    country: DE
                  customer_information:
                    date_of_birth: '1985-12-30'
                    gender: FEMALE
                    title: Prof. Dr. Dr.
                    personal_identifications:
                    - type: PASSPORT
                      id: T220001297
                      issued_by: DE
                    - type: DRIVERS_LICENSE
                      id: DL220001297
                      issued_by: BE
                    contacts:
                      phone_contacts:
                      - phone_type: MOBILE
                        phone_number: '+442071838750'
                      - phone_type: FAX
                        phone_number: '+442071838751'
                  device_information:
                    cookies_accepted: 'true'
                    http_accept_browser_value: text/html, application/xhtml+xml, application/xml;q=0.9, image/webp, */*;q=0.8
                    http_accept_content: text/html, application/xhtml+xml, application/xml;q=0.9, image/webp, */*;q=0.8
                    color_depth: B24
                    http_browser_email: mustermann@example.com
                    http_browser_java_enabled: 'true'
                    http_browser_java_script_enabled: 'true'
                    http_browser_language: de-DE
                    http_browser_screen_height: '1080'
                    http_browser_screen_width: '1920'
                    http_browser_time_difference: '60'
                    ip_address: 192.168.0.1
                    user_agent: Mozilla
                    user_agent_browser_value: Mozilla/5.0 (X11; Linux x86_64; rv:78.0) Gecko/20100101 Firefox/78.0
                  account_information:
                    account_change_date: '2021-10-25'
                    account_creation_indicator: GUEST
                    account_id: MC_ACC_12345678
                    account_opened_date: '2021-10-25'
                    modification_indicator: ACCOUNT_UPDATED_NOW
                    password_change_date: '2021-10-25'
                    password_change_indicator: PASSWORD_CHANGED_NOW
                    payment_account_date: '2021-10-25'
                    payment_account_history: PAYMENT_ACCOUNT_ADDED_NOW
                    add_card_attempts: '1'
                    provisioning_day_count: '1'
                    purchases_six_month_count: '2'
                    shipping_address_first_use_date: '2021-10-25'
                    shipping_address_first_use: 'false'
                    shipping_name_indicator: '02'
                    suspicious_account_activity: 'false'
                    transactions_day_count: '1'
                    transactions_year_count: '1'
                  merchant_risk_indicators:
                    delivery_email_address: delivery@example.com
                    delivery_timeframe: MORE_THAN_ONE_DAY
                    gift_card_amount: '0'
                    gift_card_count: '0'
                    gift_card_currency: EUR
                    pre_order_date: '2021-10-25'
                    pre_order_purchase_indicator: AVAILABLE
                    reordered_items_indicator: FIRST
                    shipping_indicator: DIGITAL
                  travel_information:
                    actual_final_destination: LEJ
                    complete_route: LEJ-LHR:LHR-JFK:JFK-LHR:LHR-LEJ
                    departure_time: 2024-07-01T07:40+01:00
                    journey_type: ROUNDTRIP
                    legs:
                    - origination: LEJ
                      destination: LHR
                      carrier_code: LH
                      departure_date: '20240701'
                    - origination: LHR
                      destination: JFK
                      carrier_code: BA
                      departure_date: '20240701'
                    - origination: JFK
                      destination: LHR
                      carrier_code: BA
                      departure_date: '20240714'
                    - origination: LHR
                      destination: LEJ
                      carrier_code: LH
                      departure_date: '20240714'
                    number_of_passengers: 2
                    passengers:
                    - first_name: Heinz
                      last_name: Mueller
                    - first_name: Klaus
                      last_name: Mueller
                  merchant_defined_information:
                  - key: '11'
                    value: nightly_order
                  - key: '2'
                    value: high_volume_order
                  - key: '52'
                    value: donation
                  - key: '99'
                    value: multi-packaging
                  - key: '100'
                    value: reordered-8times
                  - key: '103'
                    value: devices
                  risk_check_additional_information:
                    fingerprint_session_id: 1234567890-0000000005
      responses:
        '400':
          description: Response in case of an error. Includes a response code and an error message.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
        '401':
          description: Unauthorized request. Response body may be empty.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
        '200':
          description: Calculates the score of the given data and gives back more detailed information regarding the result calculation.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RiskmanagementScoringResponse'
components:
  schemas:
    ExpiryDate:
      required:
      - month
      - year
      type: object
      properties:
        year:
          maximum: 2099
          minimum: 2000
          type: integer
          description: The credit card expiry year.
          format: int32
          example: 2021
        month:
          maximum: 12
          minimum: 1
          type: integer
          description: The credit card expiry month.
          format: int32
          example: 11
      description: The credit card expiry date.
    CommonAddressExtensions:
      type: object
      properties:
        alternative_address_data:
          $ref: '#/components/schemas/AlternativeAddressData'
        paydirekt_data:
          $ref: '#/components/schemas/AddressPaydirektData'
      description: Service specific address fields.
    TaxInfo:
      required:
      - tax_id
      - tax_id_type
      type: object
      properties:
        tax_id:
          type: string
          description: The customer's tax ID value.
          example: 867.226.847-41
        tax_id_type:
          type: string
          description: 'Type of tax ID. May be country specific. Different types may adhere to different patterns.


            * `BR_CPF` : Brazilian individual tax id type.

            * `BR_CNPJ` : Brazilian business tax id type.

            * `OTHER` : None of the above.

            '
          example: BR_CPF
          enum:
          - BR_CPF
          - BR_CNPJ
          - OTHER
      description: Legal tax information of the payer.
    BankAccount:
      required:
      - iban
      type: object
      properties:
        bic:
          maxLength: 11
          minLength: 11
          pattern: '[A-Z]{6}[A-Z2-9][A-NP-Z0-9][A-Z0-9]{3}'
          type: string
          description: "The business identifier code (BIC) of a bank account. If the branch identifier\n                (positions 9 to 11) is not applicable, it is set to \"XXX\". "
          example: VZVDDED1XXX
        iban:
          maxLength: 34
          minLength: 15
          pattern: '[A-Z]{2}[0-9]{2}[A-Z0-9*]{11,30}'
          type: string
          description: The international bank account number of a bank account.
          example: DE17215730140403340300
        account_holder:
          maxLength: 27
          minLength: 1
          pattern: .*
          type: string
          description: The account holder of the bank account.
          example: Max Muster
        bank_name:
          type: string
          description: Name of the bank.
          example: Musterbank
      description: Information about a bank account.
    BasketItem:
      type: object
      properties:
        name:
          maxLength: 127
          minLength: 0
          type: string
          description: Descriptive name of the order item. Mandatory for PayPal.
          example: A fine shirt
        description:
          maxLength: 127
          minLength: 0
          type: string
          description: Used for storing merchant's internal order number or other reference.
          example: BI123456
        reference:
          maxLength: 64
          minLength: 0
          type: string
          description: Article number, SKU or similar.
          example: UGG-BB-PUR-06
        quantity:
          $ref: '#/components/schemas/Quantity'
        unit_price:
          $ref: '#/components/schemas/TaxedAmountCurrency'
        item_discount:
          $ref: '#/components/schemas/TaxedAmountCurrency'
        extensions:
          $ref: '#/components/schemas/BasketItemExtensions'
      description: A purchasable item that is part of a shopping basket's list of items.
    RiskmanagementInfoResponse:
      type: object
      properties:
        case_priority:
          type: string
          description: Riskcheck information regarding the case priority.
          example: '1'
        error_information:
          $ref: '#/components/schemas/RiskmanErrorInformation'
        event_id:
          maxLength: 50
          minLength: 1
          pattern: '[\/0-9a-zA-Z_.:,\-+*$%]+'
          type: string
          description: A unique ID for the event.
          example: E5686585867636541231230
        infocodes_address:
          type: array
          items:
            type: string
            description: Riskcheck information regarding the address risk check. See user guide for details and all possible values.
            example: '["COR-BA","COR-SA","MM-A","MM-Z"]'
        infocodes_customerlist:
          type: array
          items:
            type: string
            description: Riskcheck information regarding the customer list risk check.  See user guide for details and all possible values.
            example: '["CONPOSNEG","NEG-BCO"]'
        infocodes_device_behaviour:
          type: array
          items:
            type: string
            description: Indicates the device behavior information code(s) returned from device fingerprinting. See user guide for details and all possible values.
            example: '["MouseOffPageDetected"]'
        infocodes_globalvelocity:
          type: array
          items:
            type: string
            description: Riskcheck information regarding the velocity risk check. See user guide for details and all possible values.
            example: '["VEL-ADDR","VELS-FP"]'
        infocodes_identitychange:
          type: array
          items:
            type: string
            description: Riskcheck information regarding the identity change. See user guide for details and all possible values.
            example: '["ID-M-HPOS"]'
        infocodes_internet:
          type: array
          items:
            type: string
            description: Riskcheck information regarding the internet check. See user guide for details and all possible values.
            example: '["FREE-EM"]'
        infocodes_phone:
          type: array
          items:
            type: string
            description: Riskcheck information regarding the phone risk check. See user guide for details and all possible values.
            example: '["MMACBST, "UNV-PH" ]'
        infocodes_suspicious:
          type: array
          items:
            type: string
            description: Riskcheck information regarding suspicious risk. See user guide for details and all possible values.
            example: '["BAD-FP","MUL-EM"]'
        infocodes_velocity:
          type: array
          items:
            type: string
            description: 'List of information codes triggered by the order. These information codes were generated when you created

              the order and product velocity rules and are returned so that you can associate them with the rules. See user guide for details and all possible values.'
            example: '["GVEL-R20","GVEL-R21"]'
        localtime:
          type: string
          description: Riskcheck information regarding the local time of the risk check.
          example: '55083'
        profile_destination_queue:
          type: string
          description: Riskcheck information regarding the profile destination queue of the risk check.
          example: dst-queue
        profile_name:
          type: string
          description: Riskcheck information regarding the profile of the risk check.
          example: example-profile
        profile_selectorrule:
          type: string
          description: Riskcheck information regarding the profile selector rule risk check.
          example: example-rule
        providers:
          type: array
          items:
            type: string
            description: Providers used to calculate the risk.
            example: '["provider1","provider2"]'
        rules:
          type: array
          items:
            type: string
            description: Riskcheck information regarding the matched rules in risk check.
            example: '["example-rule"]'
        score:
          type: string
          description: Calculated risk score of request data.
          example: '14'
        score_factor_codes:
          type: array
          items:
            type: string
            description: Riskcheck information regarding the profile factor codes of the risk check. See user guide for all possible values.
            example: '["G","H","Y","Z"]'
        score_model_used:
          type: string
          description: Name of the score model used for the transaction. This field contains the name of risk management’s selected model.
          example: default_eu
        travel_actual_final_dst_country:
          type: string
          description: Actual country of final destination of the travel.
          example: US
        travel_actual_final_dst_locality:
          type: string
          description: Actual city of final destination of the travel.
          example: Chicago
        travel_first_departure_country:
          type: string
          description: First departure country of the travel.
          example: US
        travel_first_departure_locality:
          type: string
          description: First departure city of the travel.
          example: San Francisco
        tx_risk_status:
          type: string
          description: Status result of an external risk management transaction. See user guide for all possible values.
          example: ACCEPTED
        tx_scoring_id:
          type: string
          description: Unique scoring transaction identifier. Can be used to reference the depending scoring transaction.
          example: '6373172383866963604006'
        utc_time:
          type: string
          description: Riskcheck information regarding the UTC time of the risk check, used in error cases.
          example: '2021-12-21T14:18:04Z'
    PhoneContact:
      required:
      - phone_number
      - phone_type
      type: object
      properties:
        phone_type:
          type: string
          description: 'The phone type.


            * `FAX`

            * `HOME`

            * `MOBILE`

            * `OTHER`

            * `PAGER`

            * `WORK`

            '
          example: FAX
          enum:
          - FAX
          - HOME
          - MOBILE
          - OTHER
          - PAGER
          - WORK
        phone_number:
          maxLength: 16
          minLength: 0
          pattern: \+[1-9]\d{1,14}
          type: string
          description: A phone number in its canonical international E.164 numbering plan format.
          example: '+442071838750'
      description: A means of contacting a customer by phone.
      example:
        phone_type: FAX
        phone_number: '+442071838750'
    MerchantInformationKlarnaData:
      type: object
      properties:
        custom_payment_method_ids:
          type: array
          description: List of custom payment method ids.
          example:
          - klarna_invoice
          - klarna_installments
          items:
            type: string
            description: List of custom payment method ids.
            example: '["klarna_invoice","klarna_installments"]'
      description: Klarna specific MerchantInformation fields.
    CommonAddress:
      type: object
      properties:
        title:
          type: string
          description: Customer's title.
          example: Ms
        first_name:
          maxLength: 60
          minLength: 0
          type: string
          description: First name of the individual.
          example: Jane
        last_name:
          maxLength: 60
          minLength: 0
          type: string
          description: Last name of the individual.
          example: Doe
        company_name:
          maxLength: 60
          minLength: 0
          type: string
          description: Name of the company.
          example: Acme Inc.
        email:
          maxLength: 255
          minLength: 0
          type: string
          description: Email address of the individual.
          example: test_jane@gmail.com
        phone_contact:
          $ref: '#/components/schemas/PhoneContact'
        address_line_1:
          maxLength: 60
          minLength: 0
          type: string
          description: An address line.
          example: Main Street 123
        address_line_2:
          maxLength: 60
          minLength: 0
          type: string
          description: An address line. For 3DS this maps to additional1.
          example: Building A
        address_line_3:
          maxLength: 60
          minLength: 0
          type: string
          description: An address line. For 3DS this maps to additional2.
          example: Apartment 12
        postal_code:
          maxLength: 60
          minLength: 0
          type: string
          description: Postal code of the address.
          example: '80469'
        city:
          maxLength: 60
          minLength: 0
          type: string
          description: City of the address.
          example: Munich
        state:
          maxLength: 300
          minLength: 0
          type: string
          description: State or province of the address.
          example: BY
        country:
          maxLength: 2
          minLength: 2
          pattern: '[A-Z]{2}'
          type: string
          description: The ISO 3166 Alpha-2 country code (upper case) of the individual's homeland.
          example: DE
        extensions:
          $ref: '#/components/schemas/CommonAddressExtensions'
      description: Address data as applicable to most use cases.
    RiskmanErrorFieldInformation:
      type: object
      properties:
        field:
          type: string
          description: The name of the field which was the reason of the request rejection.
          example: orderInformation.billTo.firstName
  

# --- truncated at 32 KB (73 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/deutsche-bank/refs/heads/main/openapi/deutsche-bank-risk-management-api-openapi.yml