collect_response

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://raw.githubusercontent.com/api-evangelist/bankid/main/json-schema/bankid-collect-response-schema.json",
  "title": "collect_response",
  "x-generated": "2026-10-15",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/_original/bankid-openapi-openapi.yml#/components/schemas/collect_response",
  "properties": {
    "orderRef": {
      "description": "A reference ID for an order.\n\nThis is used to query the status of the order or to cancel it.",
      "type": "string"
    },
    "status": {
      "$ref": "#/$defs/status"
    },
    "completionData": {
      "$ref": "#/$defs/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",
  "$defs": {
    "collect_response_completionData": {
      "description": "Information about the user and the completed order.\n\nThe user has completed the order. `completionData` includes the signature, user information and the OCSP\nresponse. You should verify user information to proceed. You should retain completion data for future reference,\ncompliance and audit purposes.",
      "properties": {
        "user": {
          "$ref": "#/$defs/collect_response_completionData_user"
        },
        "device": {
          "$ref": "#/$defs/collect_response_completionData_device"
        },
        "stepUp": {
          "$ref": "#/$defs/collect_response_completionData_stepUp"
        },
        "bankIdIssueDate": {
          "description": "The date the BankID was issued to the user.\n\nThe issue date is expressed using date format YYYY-MM-DD with a suffix 'Z' to indicate UTC time zone offset.",
          "type": "string"
        },
        "signature": {
          "description": "The signature that is the result of the order.\n\nThis is a base 64 encoded XML signature string.",
          "type": "string"
        },
        "ocspResponse": {
          "description": "The OCSP response.\n\nThis is a base 64 encoded OCSP response.\n\nThe OCSP response is signed by a certificate that has the same issuer as the certificate being verified, and it has\na nonce extension. The nonce is calculated as:\n\n*  SHA-1 hash over the base 64 XML signature encoded as UTF-8.\n*  12 random bytes added after the hash.\n\nThe nonce is 32 bytes (20 + 12).",
          "type": "string"
        },
        "risk": {
          "$ref": "#/$defs/risk"
        }
      },
      "type": "object"
    },
    "collect_response_completionData_device": {
      "description": "Information related to the device.",
      "properties": {
        "ipAddress": {
          "description": "The IP address of the user agent as the BankID server sees it.\n\nWhen an order is started with `autoStartToken` you can check that it matches the IP you service observes to ensure\nsession fixation.",
          "type": "string"
        },
        "uhi": {
          "description": "Unique hardware identifier for the user's device.",
          "type": "string"
        }
      },
      "type": "object"
    },
    "collect_response_completionData_stepUp": {
      "description": "Information about additional verifications that were part of the order.",
      "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.",
      "properties": {
        "personalNumber": {
          "description": "The ID number of the user.\n\nThe ID number is a Swedish national identification number (12 digits).",
          "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"
    },
    "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"
    },
    "status": {
      "description": "The current status of the order.\n\nThe possible values have the following meaning:\n\n-  `pending`: The order is being processed. `hintCode` describes the status of the order.\n-  `complete`: The order is complete. completionData holds user information.\n-  `failed`: Something went wrong with the order. `hintCode` describes the error.",
      "enum": [
        "pending",
        "complete",
        "failed"
      ],
      "type": "string"
    }
  }
}