BankID Other API

openapi: 3.2.0
info:
  description: BankID Relying Party API v6.0
  license:
    name: BankID Privacy policy
    url: https://www.bankid.com/en/integritetspolicy
  title: Relying Party Other API
  version: 6.1.11
servers:
- description: Test server
  url: https://appapi2.test.bankid.com/rp/v6.0
- description: Production server
  url: https://appapi2.bankid.com/rp/v6.0
tags:
- name: Other
paths:
  /other/payment:
    post:
      description: 'Initiates a card payment order when your organization is not talking to user over the phone and you are unable to start the order with autostart or QR code.

        Using the endpoint /payment is preferred. Only use /other/payment for the edge case where neither autostart nor QR code are feasible.


        Use the `/collect` method to query the status of the order.'
      operationId: otherPayment
      requestBody:
        content:
          application/json:
            examples:
              request:
                summary: A payment request
                value:
                  personalNumber: '200001012384'
                  riskFlags:
                  - largeAmount
                  - newCustomer
                  - newCard
                  userVisibleTransaction:
                    transactionType: card
                    recipient:
                      nameB64: UGF5bWVudCBSZWNpcGllbnRzIEluYy4=
                    money:
                      amount: 100,00
                      currency: EUR
                    riskWarning: largeAmount
                  userVisibleData: IyBFeGFtcGxlClRoaXMgaXMgYW4gKmV4YW1wbGUqIHRleHQ=
                  userVisibleDataFormat: simpleMarkdownV1
                  userNonVisibleData: VGV4dCBpbmNsdWRlZCBidXQgbm90IGRpc3BsYXllZCB0byB0aGUgdXNlcg==
                  returnUrl: https://bankid.example/auth/login_page#nonce=a3618c72-bc71-4002-b3de-509555b175db
              stepUp:
                summary: Require the user to perform a step up by either verifying ID document or using facial recognition
                value:
                  personalNumber: '200001012384'
                  userVisibleTransaction:
                    transactionType: card
                    recipient:
                      name: Payment Recipients Inc.
                  requirement:
                    stepUp:
                    - mrtd
                    - face
            schema:
              $ref: '#/components/schemas/otherPayment_request'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/limited_response'
          description: Request successful.
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_response'
          description: Bad request.
        '401':
          description: You do not have access to the service.
        '403':
          description: You do not have access to the service.
        '404':
          description: An invalid URL path was used.
        '405':
          description: Only HTTP method POST is allowed.
        '408':
          description: Timeout while transmitting the request.
        '415':
          description: The type is missing or invalid.
        '500':
          description: Internal technical error in the BankID system.
        '503':
          description: The service is temporarily unavailable.
      summary: Create a payment order for other situations
      tags:
      - Other
components:
  schemas:
    otherPayment_request:
      properties:
        app:
          $ref: '#/components/schemas/app'
        personalNumber:
          description: 'The ID number of the user.


            The ID number is a Swedish national identification number (12 digits).'
          example: '200001012384'
          maxLength: 12
          minLength: 12
          pattern: ^[0-9]*$
          type: string
        returnRisk:
          description: If this is set to `true` a risk indicator will be included in the collect response when the order completes.
          example: true
          type: boolean
        riskFlags:
          description: 'Indicate to the risk assessment system that the payment has a higher risk or is unusual for the user.

            The riskFlags will not be displayed to the end user.'
          example:
          - largeAmount
          - newCustomer
          - newCard
          items:
            enum:
            - newCard
            - newCustomer
            - newRecipient
            - highRiskRecipient
            - largeAmount
            - foreignCurrency
            - cryptoCurrencyPurchase
            - moneyTransfer
            - overseasTransaction
            - recurringPayment
            - suspiciousPaymentPattern
            - partialNameMatch
            - noNameMatch
            - other
            type: string
          type: array
        returnUrl:
          description: 'Orders started on the same device as where the user''s BankID is stored (started with autostart token) will call

            this URL when the order is completed.


            Any return URL provided in the start URL when the BankID app was launched will be ignored. If the user has a

            version of the BankID app that does not support getting the `returnUrl` from the server, the order will be

            cancelled and the user will be asked to update their app.


            The return URL you provide should include a nonce to the session. When the user returns to your app or web page,

            your service should verify that the order was completed successfully and that the device receiving the

            `returnUrl` is the same device that started the order.


            Using this parameter will make your service more secure and strengthen the channel binding between you and the

            user.


            Ensure that the cookie or user IP address has not changed from the starting page to the `returnUrl` page.'
          example: https://bankid.example/auth/login_page#nonce=a3618c72-bc71-4002-b3de-509555b175db
          maxLength: 512
          minLength: 1
          type: string
        userNonVisibleData:
          description: 'Data that you wish to include but not display to the user.


            The value must be base 64-encoded.'
          example: VGV4dCBpbmNsdWRlZCBidXQgbm90IGRpc3BsYXllZCB0byB0aGUgdXNlcg==
          maxLength: 1000
          minLength: 1
          type: string
        userVisibleData:
          description: 'Text displayed to the user during the order.


            The purpose is to provide context, thereby enabling the user to detect identification errors and avert fraud

            attempts.


            The text can be formatted using CR, LF and CRLF for new lines. The text must be encoded as UTF-8 and then base 64

            encoded.'
          example: VGhpcyBpcyBhIHNhbXBsZSB0ZXh0Cg==
          maxLength: 1000
          minLength: 1
          type: string
        userVisibleDataFormat:
          $ref: '#/components/schemas/userVisibleDataFormat'
        userVisibleTransaction:
          $ref: '#/components/schemas/UserVisibleTransactionCardNpa'
        web:
          $ref: '#/components/schemas/web'
        requirement:
          $ref: '#/components/schemas/otherPayment_request_requirement'
      required:
      - personalNumber
      - userVisibleTransaction
      type: object
    RecipientCard:
      allOf:
      - $ref: '#/components/schemas/RecipientCommon'
      - properties:
          name:
            description: 'The name of the recipient of the payment.


              For the transaction type `"card"`, this is the merchant name.

              This property is here for backwards compatibility only.

              The preferred way of declaring the name of the recipient is to use nameB64 instead.'
            maxLength: 40
            type: string
        type: object
      description: 'Displayed name for the recipient of the payment.

        Exactly one of `name` and `nameB64` must be populated.'
      title: recipientCard
    CardTypeCardNpa:
      allOf:
      - $ref: '#/components/schemas/UserVisibleTransactionCardNpaParentType'
      - properties:
          money:
            $ref: '#/components/schemas/Money'
          recipient:
            $ref: '#/components/schemas/RecipientCard'
      required:
      - recipient
      title: card
      type: object
    riskWarning:
      description: "Indicate to the user that the payment has higher risk or is unusual for the user.\nThis will be indicated in the UI.\n\n<table>\n  <thead>\n    <tr>\n      <td>riskWarning</td>\n      <td>text displayed to user</td>\n    </tr>\n  </thead>\n  <tr>\n    <td>newRecipient</td>\n    <td>New recipient</td>\n  </tr>\n  <tr>\n    <td>largeAmount</td>\n    <td>Large amount</td>\n  </tr>\n  <tr>\n    <td>foreignCurrency</td>\n    <td>Foreign currency</td>\n  </tr>\n  <tr>\n    <td>cryptoCurrencyPurchase</td>\n    <td>Purchase of crypto currency</td>\n  </tr>\n  <tr>\n    <td>moneyTransfer</td>\n    <td>Money transfer</td>\n  </tr>\n  <tr>\n    <td>overseasTransaction</td>\n    <td>International payment</td>\n  </tr>\n  <tr>\n    <td>recurringPayment</td>\n    <td>Recurring payment</td>\n  </tr>\n  <tr>\n    <td>partialNameMatch</td>\n    <td>IBAN and name don’t fully match</td>\n  </tr>\n  <tr>\n    <td>noNameMatch</td>\n    <td>IBAN and name don’t match</td>\n  </tr>\n  <tr>\n    <td>other</td>\n    <td>Please verify the details above</td>\n  </tr>\n</table>"
      enum:
      - newRecipient
      - largeAmount
      - foreignCurrency
      - cryptoCurrencyPurchase
      - moneyTransfer
      - overseasTransaction
      - recurringPayment
      - partialNameMatch
      - noNameMatch
      - other
      type: string
    limited_response:
      example:
        orderRef: 131daac9-16c6-4618-beb0-365768f37288
      properties:
        orderRef:
          description: 'A reference ID for an order.


            This is used to query the status of the order or to cancel it.'
          example: 131daac9-16c6-4618-beb0-365768f37288
          type: string
      required:
      - orderRef
      type: object
    cardReader:
      description: "Whether the user needs to complete the order using a card reader for the signature.\n\nThe possible values have the following meaning:\n\n  *  `class1`: The order must be confirmed with a card reader where the PIN code is entered on a computer keyboard,\n     or a card reader of higher class.\n  *  `class2`: The order must be confirmed with a card reader where the PIN code is entered on the reader.\n\nThis condition should always be combined with a `certificatePolicies` for a smart card to avoid undefined\nbehaviour.\n\nNo card reader is required by default."
      enum:
      - class1
      - class2
      type: string
    UserVisibleTransactionCardNpa:
      description: Information about the transaction being approved.
      discriminator:
        mapping:
          card: '#/components/schemas/CardTypeCardNpa'
          npa: '#/components/schemas/NpaTypeCardNpa'
        propertyName: transactionType
      oneOf:
      - $ref: '#/components/schemas/CardTypeCardNpa'
      - $ref: '#/components/schemas/NpaTypeCardNpa'
      required:
      - transactionType
      type: object
    error_response:
      description: Generic error response
      example:
        errorCode: invalidParameters
        details: Incorrect personalNumber
      properties:
        errorCode:
          description: The error code.
          example: invalidParameters
          type: string
        details:
          description: Additional details specific to the error code.
          example: Incorrect personalNumber
          type: string
      required:
      - details
      - errorCode
      type: object
    RecipientNpa:
      allOf:
      - $ref: '#/components/schemas/RecipientCommon'
      - properties:
          name:
            description: 'The name of the recipient of the payment.

              This property is here for backwards compatibility only.

              The preferred way of declaring the name of the recipient is to use nameB64 instead.'
            maxLength: 40
            type: string
        type: object
      description: 'Displayed name for the recipient of the payment.

        Exactly one of `name` and `nameB64` must be populated.'
      title: recipientNpa
    UserVisibleTransactionCardNpaParentType:
      properties:
        transactionType:
          description: 'The type of transaction.


            The possible values have the following meaning:


            - `card`: Card payment.

            - `npa`: Non-payment authentication.'
          enum:
          - card
          - npa
          type: string
        date:
          description: 'The date for the payment to occur.


            Should be a formatted as YYYY-MM-DD.'
          format: date
          type: string
        riskWarning:
          $ref: '#/components/schemas/riskWarning'
        recurring:
          default: false
          description: Indicate to the user if the payment is a recurring one or not.
          type: boolean
        thirdPartyInitiatorB64:
          description: 'The third party initiating the payment.


            Should be a base64 encoded utf-8 string with a maximum length of 40 unicode code points.'
          maxLength: 270
          minLength: 1
          type: string
      type: object
    Money:
      description: Object that sets monetary amount for the payment.<br>If the transactionType is npa this isn't allowed to be set.
      properties:
        amount:
          description: 'The monetary amount of the payment.


            The string can contain one decimal separator which must be `","`. The rest of the input must be numbers.


            Examples: `"1000,00"`, `"100,000"`, `"100"`, `"0"`'
          example: 100,00
          maxLength: 48
          minLength: 1
          type: string
        currency:
          description: 'The currency of the payment.


            This must be an ISO 4217 alphabetic currency code.'
          example: EUR
          maxLength: 3
          minLength: 3
          type: string
      required:
      - amount
      - currency
      title: money
      type: object
    userVisibleDataFormat:
      description: "If present and set to `\"simpleMarkdownV1\"`, this parameter indicates that `userVisibleData` holds formatting\ncharacters.\n\nThe possible values have the following meaning:\n\n-  `plaintext`: `userVisibleData` contains base 64 encoded text using a sub-set of UTF-8 and CR, LF or CRLF for\n   line breaks..\n-  `simpleMarkdownV1`: `userVisibleData` contains Simple Markdown version 1.\n\nPlease see\n[the documentation](https://developers.bankid.com/getting-started/backend/formatting-text/syntax-special-characters-and-rendering)\nfor more information about the format."
      enum:
      - plaintext
      - simpleMarkdownV1
      type: string
    web:
      description: 'Additional data included when creating an order from your web page.


        When starting an order from your web page this data may be included in the request.


        You can send the parameter `web` or `app`, not both. If providing this parameter, at least one of its members must

        be specified.'
      properties:
        deviceIdentifier:
          description: 'The identifier of the device running your client.


            Do not use a session cookie. Use a separate cookie or the hash of one.


            This value should be unique to the user''s browser and persist across sessions.'
          example: e753b91e-9c84-4441-aadb-0832f4c71fac
          maxLength: 64
          minLength: 1
          type: string
        referringDomain:
          description: 'The domain that starts the BankID app.


            This should generally be your domain name followed by the public suffix, which will generally be the top level

            domain.


            Only the digits 0 to 9, the letters a to z, dot (".") and dash ("-") are allowed. When using an International

            Domain Name, the string must be punycode encoded.'
          example: example.com
          maxLength: 253
          minLength: 3
          pattern: '[0-9a-z-.]*'
          type: string
        userAgent:
          description: The user agent of the user interacting with your web page.
          example: Mozilla/5.0 (iPhone; CPU iPhone OS 17_4_1 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/17.4.1 Mobile/15E148 Safari/604.1
          maxLength: 512
          minLength: 1
          type: string
      type: object
    app:
      description: 'Additional data included when creating an order from your app.


        When starting an order from your app client this data may be included in the request.


        You can send the parameter `web` or `app`, not both. If providing this parameter, at least one of its members must

        be specified.'
      properties:
        appIdentifier:
          description: 'The identifier of your application.


            This is the package name on Android and the bundle identifier on iOS.


            It is vital to use the correct value. If your service does not supply the correct value legitimate orders might

            be blocked.'
          example: se.demobank.app1
          maxLength: 256
          minLength: 2
          type: string
        deviceOS:
          description: The device operating system where your app is running.
          example: ANDROID 14.0
          maxLength: 128
          minLength: 1
          type: string
        deviceIdentifier:
          description: 'The identifier of the device your client is running on.


            This is used to uniquely identify the device and should be a value that is not tied to a single user of the

            device. Preferably, it should remain the same even if your app is reinstalled.'
          example: e753b91e-9c84-4441-aadb-0832f4c71fac
          maxLength: 64
          minLength: 1
          type: string
        deviceModelName:
          description: The model of the device your app is running on.
          example: Apple iPhone14,3
          maxLength: 128
          minLength: 1
          type: string
      type: object
    otherPayment_request_requirement:
      description: Requirements on how the payment order must be performed.
      properties:
        cardReader:
          $ref: '#/components/schemas/cardReader'
        certificatePolicies:
          description: 'The OID in certificate policies in the user certificate.


            One wildcard is allowed from position 5 and forward (`"1.2.752.78.*"`).


            Available values for production BankIDs are:

            *  `"1.2.752.78.1.1"` - BankID on file

            *  `"1.2.752.78.1.2"` - BankID on card

            *  `"1.2.752.78.1.5"` - Mobile BankID


            Available values for test BankIDs are:

            *  `"1.2.3.4.5"` - BankID on file

            *  `"1.2.3.4.10"` - BankID on card

            *  `"1.2.3.4.25"` - Mobile BankID

            *  `"1.2.752.60.1.6"` - Test BankID for some BankID banks


            When using one of the _BankID on card_ policies, the `cardReader` requirement can be used to further restrict the

            type of card reader allowed. If no `cardReader` requirement is passed, all supported kinds of card readers are

            permitted.'
          example:
          - 1.2.752.78.1.1
          items:
            type: string
          type: array
        mrtd:
          description: 'Whether the user needs to confirm their identity with a valid Swedish passport or national ID card to complete the

            order.


            No identity confirmation is required by default.'
          type: boolean
        pinCode:
          description: Users are required to confirm the order with their security code even if they have biometrics activated.
          example: false
          type: boolean
        stepUp:
          description: 'Whether the user needs to perform a step up.


            The possible values have the following meaning:

            - `mrtd`: Confirm identity with a valid Swedish passport or national ID card to complete the order.

            - `face`: Confirm identity with facial recognition.


            Use multiple values to let the user choose between the available identity confirmations.


            The `requirement.stepUp` property can not be used in combination with the property `requirement.mrtd`.


            Requesting identity confirmation with facial recognition as the only option is not supported.


            No identity confirmation is required by default.'
          items:
            type: string
          type: array
      type: object
    NpaTypeCardNpa:
      allOf:
      - $ref: '#/components/schemas/UserVisibleTransactionCardNpaParentType'
      - properties:
          recipient:
            $ref: '#/components/schemas/RecipientNpa'
      required:
      - recipient
      title: npa
      type: object
    RecipientCommon:
      properties:
        nameB64:
          description: 'The name of the recipient of the payment.


            For the transaction type `"card"`, this is the merchant name.


            Should be a base64 encoded utf-8 string with a maximum length of 40 unicode code points.'
          maxLength: 215
          minLength: 1
          type: string
      type: object