Driftstatus:
Integrationsguide

Collect

Collects the result of a sign or auth order using the orderRef as reference. RP should keep on calling collect every two seconds as long as status indicates pending. RP must abort if status indicates failed. The user identity is returned when complete.

Example request collect

POST /rp/v5.1/collect HTTP/1.1
Content-Type: application/json
Host: appapi2.bankid.com
{
  "orderRef":"131daac9-16c6-4618-beb0-365768f37288"
}

Parameters for collect

Name Value

orderRef

The orderRef returned from auth or sign.
Name

orderRef

Value

The orderRef returned from auth or sign.

Response from collect

The response will have different content depending on status of the order. The status may be pending, failed or complete.

Name Value

orderRef

The orderRef in question.

status

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

  • failed: Something went wrong with the order. hintCode describes the error.
  • complete: The order is complete. completionData holds user information.

hintCode

Only present for pending and failed orders. See below.

completionData

Only present for complete orders. See below.
Name

orderRef

Value

The orderRef in question.

Name

status

Value

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

  • failed: Something went wrong with the order. hintCode describes the error.
  • complete: The order is complete. completionData holds user information.
Name

hintCode

Value

Only present for pending and failed orders. See below.

Name

completionData

Value

Only present for complete orders. See below.

hintCode for Pending Orders

The order is pending. RP should use the hintCode to provide the user with details and instructions and keep on calling collect until failed or complete.

hintCode Reason Action by RP

outstandingTransaction

on The order is pending. The client has not yet received the order. The hintCode will later change to noClient, started or userSign.

If RP tried to start the client automatically, the RP should inform the user that the app is starting. Please use message RFA13.

If RP did not try to start the client automatically, the RP should inform the user that she needs to start the app. Please use message RFA1.

Please see recommended user messages

noClient

The order is pending. The client has not yet received the order.

  • If RP tried to start the client automatically: This status indicates that the start failed or the users BankID was not available in the started client. RP should inform the user. Please use message RFA1.

  • If RP did not try to start the client automatically: This status indicates that the user not yet has started her client. RP should inform the user. Please use message RFA1.

Please see recommended user messages

started

The order is pending. A client has been started with the autostarttoken but a usable ID has not yet been found in the started client. When the client starts there may be a short delay until all ID:s are registered. The user may not have any usable ID:s at all, or has not yet inserted their smart card.

  • If RP does not require the autoStartToken to be used and the user provided her personal number the RP should inform the user of possible solutions. Please use message RFA14.

  • If RP require the autoStartToken to be used or the user did not provide her personal number the RP should inform the user of possible solutions. Please use message RFA15.

Please see recommended user messages

Note: started is not an error, RP should keep on polling using collect.

userSign

The order is pending. The client has received the order.

The RP should inform the user. Please use message RFA9.

Please see recommended user messages

We may introduce new hint codes without prior notice. RP must handle unknown hint codes in their implementations.

  

If an unknown hintCode is returned for a pending order, RP should inform the user. Please use message RFA21. RP should update their implementation to support the new hintCode as soon as possible.

Please see recommended user messages
hintCode

outstandingTransaction

Reason

on The order is pending. The client has not yet received the order. The hintCode will later change to noClient, started or userSign.

Action by RP

If RP tried to start the client automatically, the RP should inform the user that the app is starting. Please use message RFA13.

If RP did not try to start the client automatically, the RP should inform the user that she needs to start the app. Please use message RFA1.

Please see recommended user messages

hintCode

noClient

Reason

The order is pending. The client has not yet received the order.

Action by RP

  • If RP tried to start the client automatically: This status indicates that the start failed or the users BankID was not available in the started client. RP should inform the user. Please use message RFA1.

  • If RP did not try to start the client automatically: This status indicates that the user not yet has started her client. RP should inform the user. Please use message RFA1.

Please see recommended user messages

hintCode

started

Reason

The order is pending. A client has been started with the autostarttoken but a usable ID has not yet been found in the started client. When the client starts there may be a short delay until all ID:s are registered. The user may not have any usable ID:s at all, or has not yet inserted their smart card.

Action by RP

  • If RP does not require the autoStartToken to be used and the user provided her personal number the RP should inform the user of possible solutions. Please use message RFA14.

  • If RP require the autoStartToken to be used or the user did not provide her personal number the RP should inform the user of possible solutions. Please use message RFA15.

Please see recommended user messages

Note: started is not an error, RP should keep on polling using collect.

hintCode

userSign

Reason

The order is pending. The client has received the order.

Action by RP

The RP should inform the user. Please use message RFA9.

Please see recommended user messages

hintCode

We may introduce new hint codes without prior notice. RP must handle unknown hint codes in their implementations.

Reason
Action by RP

If an unknown hintCode is returned for a pending order, RP should inform the user. Please use message RFA21. RP should update their implementation to support the new hintCode as soon as possible.

Please see recommended user messages

Example response from collect for a pending order

HTTP/1.1 200 OK
Content-Type: application/json
{
  "orderRef":"131daac9-16c6-4618-beb0-365768f37288", 
  "status":"pending",
  "hintCode":"userSign"
}

hintCode for Failed Orders

This is a final state. The order failed. RP should use the hintCode to provide the user with details and instructions. The same orderRef must not be used for additional collect requests.

hintcode Reason Action by RP

expiredTransaction

The order has expired. The BankID security app/program did not start, the user did not finalize the signing or the RP called collect too late.

RP must inform the user. Please use message RFA8.

Please see recommended user messages

certificateErr

This error is returned if:

  1. The user has entered wrong security code too many times. The BankID cannot be used.
  2. The users BankID is revoked.
  3. The users BankID is invalid.

RP must inform the user. Please use message RFA16.

Please see recommended user messages

userCancel

The order was cancelled by the user.
userCancel may also be returned in some rare cases related to other user interactions.

RP must inform the user. Please use message RFA6.

Please see recommended user messages

cancelled

The order was cancelled. The system received a new order for the user.

RP must inform the user. Please use message RFA3.

Please see recommended user messages

startFailed

The user did not provide her ID, or the RP requires autoStartToken to be used, but the client did not start within a certain time limit. The reason may be:

  1. RP did not use autoStartToken when starting BankID security program/app. RP must correct this in their implementation.
  2. The client software was not installed or other problem with the user’s computer.

The RP must inform the user. Please use message RFA17.

Please see recommended user messages

We may introduce new hint Codes without prior notice. RP must handle unknown hint Codes in their implementations.

  

If an unknown hintCode is returned for a failed order, RP should inform the user. Please use message RFA22. RP should update their implementation to support the new hintCode as soon as possible.

Please see recommended user messages
hintcode

expiredTransaction

Reason

The order has expired. The BankID security app/program did not start, the user did not finalize the signing or the RP called collect too late.

Action by RP

RP must inform the user. Please use message RFA8.

Please see recommended user messages

hintcode

certificateErr

Reason

This error is returned if:

  1. The user has entered wrong security code too many times. The BankID cannot be used.
  2. The users BankID is revoked.
  3. The users BankID is invalid.
Action by RP

RP must inform the user. Please use message RFA16.

Please see recommended user messages

hintcode

userCancel

Reason

The order was cancelled by the user.
userCancel may also be returned in some rare cases related to other user interactions.

Action by RP

RP must inform the user. Please use message RFA6.

Please see recommended user messages

hintcode

cancelled

Reason

The order was cancelled. The system received a new order for the user.

Action by RP

RP must inform the user. Please use message RFA3.

Please see recommended user messages

hintcode

startFailed

Reason

The user did not provide her ID, or the RP requires autoStartToken to be used, but the client did not start within a certain time limit. The reason may be:

  1. RP did not use autoStartToken when starting BankID security program/app. RP must correct this in their implementation.
  2. The client software was not installed or other problem with the user’s computer.
Action by RP

The RP must inform the user. Please use message RFA17.

Please see recommended user messages

hintcode

We may introduce new hint Codes without prior notice. RP must handle unknown hint Codes in their implementations.

Reason
Action by RP

If an unknown hintCode is returned for a failed order, RP should inform the user. Please use message RFA22. RP should update their implementation to support the new hintCode as soon as possible.

Please see recommended user messages

Example response from collect for a failed request

HTTP/1.1 200 OK
Content-Type: application/json
{
  "orderRef":"131daac9-16c6-4618-beb0-365768f37288", 
  "status":"failed",
  "hintCode":"userCancel"
}

completionData for completed orders

This is a final state. The order was successful. The user has provided the security code and completed the order. The completionData includes the signature, user information and the OCSP response. RP should control the user information and continue their process. RP should keep the completion data for future references/compliance/audit.

Name Value

user

Information related to the user, holds the following children:

  • personalNumber: The personal number. String.
  • name: The given name and surname of the user. String.
  • givenName: The given name of the user. String.
  • surname: The surname of the user. String.

device

Information related to the device, holds the following child:

  • ipAddress: The IP address of the user agent as the BankID server discovers it. String.

cert

Information related to the user’s certificate (BankID), holds the following children:

  • notBefore: Start of validity of the users BankID. String, Unix ms.
  • notAfter: End of validity of the Users BankID. String, Unix ms.

Note: notBefore and notAfter are the number of milliseconds since the UNIX Epoch, a.k.a. "UNIX time" in milliseconds. It was chosen over ISO8601 for its simplicity and lack of error prone conversions to/from string representations on the server and client side.

signature

The signature. The content of the signature is described in BankID Signature Profile specification. String. Base64-encoded. XML signature.

ocspResponse

The OCSP response. String. Base64-encoded. The OCSP response is signed by a certificate that has the same issuer as the certificate being verified. The OSCP response has an extension for Nonce. The nonce is calculated as:

  • SHA-1 hash over the base 64 XML signature encoded as UTF-8.
  • 12 random bytes is added after the hash
  • The nonce is 32 bytes (20 + 12)
Name

user

Value

Information related to the user, holds the following children:

  • personalNumber: The personal number. String.
  • name: The given name and surname of the user. String.
  • givenName: The given name of the user. String.
  • surname: The surname of the user. String.
Name

device

Value

Information related to the device, holds the following child:

  • ipAddress: The IP address of the user agent as the BankID server discovers it. String.
Name

cert

Value

Information related to the user’s certificate (BankID), holds the following children:

  • notBefore: Start of validity of the users BankID. String, Unix ms.
  • notAfter: End of validity of the Users BankID. String, Unix ms.

Note: notBefore and notAfter are the number of milliseconds since the UNIX Epoch, a.k.a. "UNIX time" in milliseconds. It was chosen over ISO8601 for its simplicity and lack of error prone conversions to/from string representations on the server and client side.

Name

signature

Value

The signature. The content of the signature is described in BankID Signature Profile specification. String. Base64-encoded. XML signature.

Name

ocspResponse

Value

The OCSP response. String. Base64-encoded. The OCSP response is signed by a certificate that has the same issuer as the certificate being verified. The OSCP response has an extension for Nonce. The nonce is calculated as:

  • SHA-1 hash over the base 64 XML signature encoded as UTF-8.
  • 12 random bytes is added after the hash
  • The nonce is 32 bytes (20 + 12)

Example response from collect for a complete order

HTTP/1.1 200 OK
Content-Type: application/json
{
  "orderRef":"131daac9-16c6-4618-beb0-365768f37288", 
  "status":"complete",
  "completionData":{
    "user":{
      "personalNumber":"190000000000",
      "name":"Karl Karlsson",
      "givenName":"Karl",
      "surname":"Karlsson"
    },
    "device":{
      "ipAddress":"192.168.0.1"
    },
    "cert":{
      "notBefore":"1502983274000",
      "notAfter":"1563549674000"
    },
    "signature":"", 
    "ocspResponse":""
  } 
}
Identification and signing
Cancel
Företag
Privatpersoner
Utvecklare
Om oss