/collect
Collects the result of a sign or auth order using orderRef as reference. RP should keep on calling collect every two seconds if status is pending. RP must abort if status indicates failed. The user identity is returned when complete.
Example request collect
POST /rp/v6.0/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. |
orderRef
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 |
|
hintCode |
Only present for pending and failed orders. See below. |
completionData |
Only present for complete orders. See below. |
orderRef
The orderRef in question.
status
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.
hintCode
Only present for pending and failed orders. See below.
completionData
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 |
Order is pending. The BankID app has not yet received the order. The hintCode will later change to noClient, started or userSign. |
If RP tried to launch the client automatically, the RP should inform the user that the app is launching. Message RFA13 should be used. If RP did not try to start the client automatically, the RP should prompt user to start the app. Message RFA1 should be used. |
noClient |
Order is pending. The client has not yet received the order. |
If RP tried to launch the client automatically: This status indicates that the launch failed, or that the user’s BankID was not available in the client. RP should inform the user. Message RFA1 should be used. If RP did not try to launch the client automatically: This status indicates that the user has not yet launched the client. RP should inform the user. Message RFA1 should be used. |
started |
Order is pending. A BankID client has launched with autostarttoken but a usable ID has not yet been found in the client. When the client launches there may be a short delay until all IDs are registered. The user may not have any usable IDs, or is yet to insert their smart card. |
The RP should inform the user of possible solutions. Message RFA15 should be used. Note: started is not an error, RP should keep on polling using collect. |
userMrtd |
Order is pending. A client has launched and received the order but additional steps for providing MRTD information is required to proceed with the order. |
The RP should inform the user using message RFA23. |
userCallConfirm |
Order is waiting for the user to confirm that they have received this order while in a call with the RP. |
|
userSign |
Order is pending. The BankID client has received the order. |
The RP should inform the user using message RFA9. |
Unknown hint code |
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. Message RFA21 should be used. RP should update their implementation to support the new hintCode as soon as possible. |
outstandingTransaction
Order is pending. The BankID app has not yet received the order. The hintCode will later change to noClient, started or userSign.
If RP tried to launch the client automatically, the RP should inform the user that the app is launching. Message RFA13 should be used.
If RP did not try to start the client automatically, the RP should prompt user to start the app. Message RFA1 should be used.
noClient
Order is pending. The client has not yet received the order.
If RP tried to launch the client automatically: This status indicates that the launch failed, or that the user’s BankID was not available in the client. RP should inform the user. Message RFA1 should be used.
If RP did not try to launch the client automatically: This status indicates that the user has not yet launched the client. RP should inform the user. Message RFA1 should be used.
started
Order is pending. A BankID client has launched with autostarttoken but a usable ID has not yet been found in the client.
When the client launches there may be a short delay until all IDs are registered.
The user may not have any usable IDs, or is yet to insert their smart card.
The RP should inform the user of possible solutions. Message RFA15 should be used.
Note: started is not an error, RP should keep on polling using collect.
userMrtd
Order is pending. A client has launched and received the order but additional steps for providing MRTD information is required to proceed with the order.
The RP should inform the user using message RFA23.
userCallConfirm
Order is waiting for the user to confirm that they have received this order while in a call with the RP.
userSign
Order is pending. The BankID client has received the order.
The RP should inform the user using message RFA9.
Unknown hint code
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. Message RFA21 should be used.
RP should update their implementation to support the new hintCode as soon as possible.
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"
}
completionData for completed orders
A final state when an order is successful. The user has provided the security code and completed the order. The completionData includes signature, user information and the OCSP response. RP should verify user information to proceed. RP should retain completion data for future reference, compliance and audit purposes.
Name | Value |
---|---|
user |
Information related to the user, holds the following:
|
device |
Information related to the device, holds the following:
|
bankIdIssueDate |
The date the BankID was issued to the user. The issue date of the ID expressed using ISO 8601 date format YYYY-MM-DD with a UTC time zone offset. |
stepUp |
Information about extra verifications that were part of the transaction. mrtd: Indicate if there was a check of the mrtd (machine readable travel document). Boolean. True if the mrtd check was performed. |
signature |
The signature as described in the 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:
|
user
Information related to the user, holds the following:
personalNumber: The personal identity 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:
ipAddress: The IP address of the user agent as the BankID server discovers it. When an order is started with autoStartToken the RP can check that this match the IP they observe to ensure session fixation String.
uhi: Unique hardware identifier for the users device.
bankIdIssueDate
The date the BankID was issued to the user. The issue date of the ID expressed using ISO 8601 date format YYYY-MM-DD with a UTC time zone offset.
stepUp
Information about extra verifications that were part of the transaction.
mrtd: Indicate if there was a check of the mrtd (machine readable travel document). Boolean. True if the mrtd check was performed.
signature
The signature as described in the 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).
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"
},
"bankIdIssueDate": "2020-02-01",
"signature": "<base64-encoded data>",
"ocspResponse": "<base64-encoded data>"
}
}
hintCode for failed orders
This is a final state when an order fails. 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 launch, the user did not finalize the signing or the RP called collect too late. |
The RP must inform the user using message RFA8. |
certificateErr |
This error is returned if:
|
The RP must inform the user using message RFA16. |
userCancel |
The order was cancelled by the user. userCancel may also be returned in some rare cases related to other user interactions. |
The RP must inform the user using message RFA6. |
cancelled |
The order was cancelled. The system received a new order for the user. |
The RP must inform the user using message RFA3. |
startFailed |
The user did not provide their ID or the client did not launch within a certain time limit. Potential causes are:
|
The RP must inform the user using message RFA17. |
userDeclinedCall |
The order was cancelled because the user indicated in the app that they are not in a call with the RP about the order. |
|
notSupportedByUserApp |
The order was picked up by a client that do not support the feature requested. The BankID client used by the user need to be updated to a later version that support the features required to complete the order. |
Ask the user to update to the latest BankID client. |
Unknown hint code |
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. Message RFA22 should be used. RP should update their implementation to support the new hintCode as soon as possible. |
expiredTransaction
The order has expired. The BankID security app/program did not launch, the user did not finalize the signing or the RP called collect too late.
The RP must inform the user using message RFA8.
certificateErr
This error is returned if:
The user has entered the wrong PIN code too many times. The BankID cannot be used.
The user’s BankID is blocked.
The user’s BankID is invalid.
The RP must inform the user using message RFA16.
userCancel
The order was cancelled by the user. userCancel may also be returned in some rare cases related to other user interactions.
The RP must inform the user using message RFA6.
cancelled
The order was cancelled. The system received a new order for the user.
The RP must inform the user using message RFA3.
startFailed
The user did not provide their ID or the client did not launch within a certain time limit. Potential causes are:
RP did not use autoStartToken when launching the BankID security app. RP must correct this in their implementation.
Client software was not installed or other problem with the user’s device.
The RP must inform the user using message RFA17.
userDeclinedCall
The order was cancelled because the user indicated in the app that they are not in a call with the RP about the order.
notSupportedByUserApp
The order was picked up by a client that do not support the feature requested. The BankID client used by the user need to be updated to a later version that support the features required to complete the order.
Ask the user to update to the latest BankID client.
Unknown hint code
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. Message RFA22 should be used. RP should update their implementation to support the new hintCode as soon as possible.
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"
}