BankID Collect 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 Collect 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: Collect
paths:
  /collect:
    post:
      description: 'Collects the result of an order using `orderRef` as reference.


        Your service should continue calling collect every two seconds if the status reported is is `pending`. Your

        service must abort if the status is `failed`.


        The user identity is returned when complete.'
      operationId: collect
      requestBody:
        content:
          application/json:
            examples:
              simple:
                summary: A request identifying the order to collect
                value:
                  orderRef: 131daac9-16c6-4618-beb0-365768f37288
            schema:
              $ref: '#/components/schemas/collect_request'
        required: true
      responses:
        '200':
          content:
            application/json:
              examples:
                Order completed:
                  description: A collect response indicating a successfully completed order
                  value:
                    orderRef: 131daac9-16c6-4618-beb0-365768f37288
                    status: complete
                    completionData:
                      user:
                        personalNumber: '200001012384'
                        name: Alex Johnson
                        givenName: Alex
                        surname: Johnson
                      device:
                        ipAddress: 192.168.1.1
                        uhi: OZvYM9VvyiAmG7NA5jU5zqGcVpo=
                      bankIdIssueDate: 2023-04-01Z
                      stepUp:
                        mrtd: true
                      signature: <base64-encoded data>
                      ocspResponse: <base64-encoded data>
                      risk: low
                Order pending:
                  description: A collect response indicating that the order is not yet completed by the user
                  value:
                    orderRef: 131daac9-16c6-4618-beb0-365768f37288
                    status: pending
                    hintCode: userSign
                Order failed:
                  description: A collect response indicating that the order failed to complete. In this example, the reason is that the user cancelled the order
                  value:
                    orderRef: 131daac9-16c6-4618-beb0-365768f37288
                    status: failed
                    hintCode: userCancel
              schema:
                $ref: '#/components/schemas/collect_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: Gather order information and status
      tags:
      - Collect
components:
  schemas:
    risk:
      description: "Indicates the risk level of the order based on data available in the order.\n\nThe possible values have the following meaning:\n\n-  `low`: No or low risk identified in the available order data.\n-  `moderate`: Might require further action, investigation or follow-up by you based on the order data.\n-  `high`: The order should be blocked or cancelled by you and needs further action, investigation or follow-up.\n   This value will only be returned if you have requested to have the risk assement to be provided, but not\n   supplied a `risk` condition.\n\nThis is only returned if requested in the order, and it may be absent if the risk could not be calculated.\n\nIf you have sent the correct `endUserIp` and additional data, a risk indication with the value `\"high\"` means\nthere are signs of the channel binding being compromised, or other highly concerning circumstances."
      enum:
      - low
      - moderate
      - high
      type: string
    collect_response_completionData:
      description: 'Information about the user and the completed order.


        The user has completed the order. `completionData` includes the signature, user information and the OCSP

        response. You should verify user information to proceed. You should retain completion data for future reference,

        compliance and audit purposes.'
      example:
        signature: signature
        ocspResponse: ocspResponse
        stepUp:
          face: true
          mrtd: true
        bankIdIssueDate: 2023-04-01Z
        risk: low
        user:
          surname: surname
          givenName: givenName
          name: name
          personalNumber: '200001012384'
        device:
          uhi: OZvYM9VvyiAmG7NA5jU5zqGcVpo=
          ipAddress: 192.168.1.2
      properties:
        user:
          $ref: '#/components/schemas/collect_response_completionData_user'
        device:
          $ref: '#/components/schemas/collect_response_completionData_device'
        stepUp:
          $ref: '#/components/schemas/collect_response_completionData_stepUp'
        bankIdIssueDate:
          description: 'The date the BankID was issued to the user.


            The issue date is expressed using date format YYYY-MM-DD with a suffix ''Z'' to indicate UTC time zone offset.'
          example: 2023-04-01Z
          type: string
        signature:
          description: 'The signature that is the result of the order.


            This is a base 64 encoded XML signature string.'
          type: string
        ocspResponse:
          description: 'The OCSP response.


            This is a base 64 encoded OCSP response.


            The OCSP response is signed by a certificate that has the same issuer as the certificate being verified, and it has

            a nonce extension. The nonce is calculated as:


            *  SHA-1 hash over the base 64 XML signature encoded as UTF-8.

            *  12 random bytes added after the hash.


            The nonce is 32 bytes (20 + 12).'
          type: string
        risk:
          $ref: '#/components/schemas/risk'
      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
    collect_response_completionData_device:
      description: Information related to the device.
      example:
        uhi: OZvYM9VvyiAmG7NA5jU5zqGcVpo=
        ipAddress: 192.168.1.2
      properties:
        ipAddress:
          description: 'The IP address of the user agent as the BankID server sees it.


            When an order is started with `autoStartToken` you can check that it matches the IP you service observes to ensure

            session fixation.'
          example: 192.168.1.2
          type: string
        uhi:
          description: Unique hardware identifier for the user's device.
          example: OZvYM9VvyiAmG7NA5jU5zqGcVpo=
          type: string
      type: object
    status:
      description: 'The current status of the order.


        The possible values have the following meaning:


        -  `pending`: The order is being processed. `hintCode` describes the status of the order.

        -  `complete`: The order is complete. completionData holds user information.

        -  `failed`: Something went wrong with the order. `hintCode` describes the error.'
      enum:
      - pending
      - complete
      - failed
      type: string
    collect_response:
      example:
        orderRef: 131daac9-16c6-4618-beb0-365768f37288
        hintCode: hintCode
        completionData:
          signature: signature
          ocspResponse: ocspResponse
          stepUp:
            face: true
            mrtd: true
          bankIdIssueDate: 2023-04-01Z
          risk: low
          user:
            surname: surname
            givenName: givenName
            name: name
            personalNumber: '200001012384'
          device:
            uhi: OZvYM9VvyiAmG7NA5jU5zqGcVpo=
            ipAddress: 192.168.1.2
        status: pending
      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
        status:
          $ref: '#/components/schemas/status'
        completionData:
          $ref: '#/components/schemas/collect_response_completionData'
        hintCode:
          description: "When an order is pending, you should use the hintCode to provide the user with details and instructions and keep\ncalling collect until order fails or is complete.\n\n<table>\n  <thead>\n    <tr>\n      <td>hintCode</td>\n      <td>Reason</td>\n      <td>Action by your service</td>\n    </tr>\n  </thead>\n  <tr>\n    <td>outstandingTransaction</td>\n    <td>\n      Order is pending. The BankID app has not received the order yet. The hintCode will later change to noClient,\n      started or userSign.\n    </td>\n    <td>\n      If you tried to launch the user's client automatically you should inform the user that the app is launching.\n      Message RFA13 should be used.\n      <br>\n      If you did not try to start the user's client automatically, you should prompt the user to start the app.\n      Message RFA1 should be used.\n    </td>\n  </tr>\n  <tr>\n    <td>noClient</td>\n    <td>\n      Order is pending. The client has not yet received the order.\n    </td>\n    <td>\n      If you tried to launch the user's client automatically this status indicates that the launch failed, or that\n      the user's BankID wasn't available in their client. You should inform the user. Message RFA1 should be used.\n      <br>\n      If you did not try to launch the client automatically this status indicates that the user has not launched\n      their client yet. You should inform the user. Message RFA1 should be used.\n    </td>\n  </tr>\n  <tr>\n    <td>started</td>\n    <td>\n      Order is pending. A BankID client has launched with autostarttoken but a usable ID has not yet been found in\n      the client. When the client launches there may be a short delay until all IDs are registered. The user may\n      not have any usable IDs, or has yet to insert their smart card.\n    </td>\n    <td>\n      You should inform the user of possible solutions. Message RFA15 should be used.<br>Note: started is not an\n      error, you should keep on polling using collect.\n    </td>\n  </tr>\n  <tr>\n    <td>userMrtd</td>\n    <td>\n      Order is pending. A client has launched and received the order but additional steps for providing MRTD\n      information is required to proceed with the order.\n    </td>\n    <td>\n      You should inform the user. User message RFA23 should be used.\n    </td>\n  </tr>\n  <tr>\n    <td>userCallConfirm</td>\n    <td>\n      Order is waiting for the user to confirm that they have received this order while in a call with your\n      organization.\n    </td>\n    <td>\n    </td>\n  </tr>\n  <tr>\n    <td>userSign</td>\n    <td>\n      The order is pending. The client has received the order.\n    </td>\n    <td>\n      You should inform the user. Message RFA9 should be used.\n    </td>\n  </tr>\n  <tr>\n    <td>processing</td>\n    <td>The order is pending. The client has received and signed the order, but signature processing is underway.</td>\n    <td>\n      The RP should inform the user. Message RFA21 should be used.\n    </td>\n  </tr>\n  <tr>\n    <td>userStepUp</td>\n    <td>The order is pending. The client is waiting for the user to choose how to confirm their identity.</td>\n    <td>\n      You should inform the user. User message RFA25 should be used.\n    </td>\n  </tr>\n  <tr>\n    <td>userFace</td>\n    <td>\n      Order is pending. A client has launched and received the order but additional steps for providing facial\n      recognition information is required to proceed with the order.\n    </td>\n    <td>\n      You should inform the user. User message RFA24 should be used.\n    </td>\n  </tr>\n  <tr>\n    <td>Unknown hint code</td>\n    <td>\n      We may introduce new hint codes without prior notice. You must handle unknown hint codes in your\n      implementations.\n    </td>\n    <td>\n      If an unknown hintCode is returned for a pending order, you should inform the user. Message RFA21 should be\n      used.\n      <br>\n      You should update your implementation to support the new hintCode as soon as possible.\n    </td>\n  </tr>\n</table>\n\nThis is a final state when an order fails. You should use the hintCode to provide the user with details and\ninstructions. The same orderRef must not be used for additional collect requests.\n\n<table>\n  <thead>\n    <tr>\n      <td>hintCode</td>\n      <td>Reason</td>\n      <td>Action by your service</td>\n    </tr>\n  </thead>\n  <tr>\n    <td>expiredTransaction</td>\n    <td>\n      The order has expired. The BankID security app / program did not launch, the user did not finalise the\n      signature or you called collect too late.\n    </td>\n    <td>\n      You must inform the user. User message RFA8 should be used.\n    </td>\n  </tr>\n  <tr>\n    <td>certificateErr</td>\n    <td>\n      This error is returned if:\n      <ul>\n        <li>\n          The user has entered the wrong PIN code too many times. The BankID cannot be used.\n        </li>\n        <li>\n          The user's BankID is blocked.\n        </li>\n        <li>\n          The user's BankID is invalid.\n        </li>\n      </ul>\n    </td>\n    <td>\n      You must inform the user. User message RFA16 should be used.\n    </td>\n  </tr>\n  <tr>\n    <td>userCancel</td>\n    <td>\n      The order was cancelled by the user. userCancel may also be returned in some rare cases related to other\n      user interactions.\n    </td>\n    <td>\n      You must inform the user. User message RFA6 should be used.\n    </td>\n  </tr>\n  <tr>\n    <td>cancelled</td>\n    <td>\n      The order was cancelled or the system received a new order for the user.\n    </td>\n    <td>\n      You must inform the user. User message RFA3 should be used.\n    </td>\n  </tr>\n  <tr>\n    <td>startFailed</td>\n    <td>\n      The user did not provide their ID or the client did not launch within a certain time limit. Potential\n      causes are:\n      <ul>\n        <li>\n          You did not use autoStartToken when launching the BankID app. You must correct this in your\n          implementation.\n        </li>\n        <li>\n          The user's client software was not installed or there was some other problem with the user's device.\n        </li>\n      </ul>\n    </td>\n    <td>\n      You must inform the user. User message RFA17 should be used.\n    </td>\n  </tr>\n  <tr>\n    <td>userDeclinedCall</td>\n    <td>\n      The order was cancelled because the user indicated in the app that they are not in a call with your\n      organization.\n    </td>\n    <td>\n    </td>\n  </tr>\n  <tr>\n    <td>notSupportedByUserApp</td>\n    <td>\n      The order was picked up by a client that does not support the requested feature. The BankID client used by\n      the user needs to be updated to a later version that supports the features that are required to complete\n      the order.\n    </td>\n    <td>\n      Ask the user to update to the latest version of the BankID client.\n    </td>\n  </tr>\n  <tr>\n    <td>mrtdVerificationFailed</td>\n    <td>\n      Identity confirmation using MRTD failed.\n    </td>\n    <td>\n      You must inform the user. User message RFA26 should be used.\n    </td>\n  </tr>\n  <tr>\n    <td>facialRecognitionFailed</td>\n    <td>\n      Identity confirmation using facial recognition failed.\n    </td>\n    <td>\n      You must inform the user. User message RFA27 should be used.\n    </td>\n  </tr>\n  <tr>\n    <td>nfcNotSupportedByDevice</td>\n    <td>\n      The order was picked up by a client device that does not support NFC.\n    </td>\n    <td>\n      You must inform the user. User message RFA28 should be used.\n    </td>\n  </tr>\n  <tr>\n    <td>multipleBankIdsOnDevice</td>\n    <td>\n      The requested feature does not support having multiple Bank IDs on the device.\n    </td>\n    <td>\n      You must inform the user. User message RFA29 should be used.\n    </td>\n  </tr>\n  <tr>\n    <td>stepUpFailed</td>\n    <td>\n      Identity confirmation failed.\n    </td>\n    <td>\n      You must inform the user. User message RFA30 should be used.\n    </td>\n  </tr>\n  <tr>\n    <td>Unknown hint code</td>\n    <td>\n      We may introduce new hint codes without prior notice. You must handle unknown hint codes in your\n      implementations.\n    </td>\n    <td>\n      If an unknown hintCode is returned for a failed order, you should inform the user. Message RFA22 should be\n      used. You should update your implementation to support the new hintCode as soon as possible.\n    </td>\n  </tr>\n</table>"
          type: string
      required:
      - orderRef
      - status
      type: object
    collect_request:
      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
    collect_response_completionData_stepUp:
      description: Information about additional verifications that were part of the order.
      example:
        face: true
        mrtd: true
      properties:
        mrtd:
          description: Whether an MRTD check was performed before the order was completed.
          type: boolean
        face:
          description: Whether order was stepped up with facial recognition.
          type: boolean
      type: object
    collect_response_completionData_user:
      description: Information related to the user.
      example:
        surname: surname
        givenName: givenName
        name: name
        personalNumber: '200001012384'
      properties:
        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
        name:
          description: The first and last name of the user.
          type: string
        givenName:
          description: The first name of the user.
          type: string
        surname:
          description: The surname of the user.
          type: string
      type: object