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. |
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 |
pending: The order is being processed. hintCode describes the status of the order.
|
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.
- 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.
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. |
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. |
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 |
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
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:
|
RP must inform the user. Please use message RFA16. Please see recommended user messages |
userCancel |
The order was cancelled by the user. |
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:
|
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 |
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.
certificateErr
This error is returned if:
- The user has entered wrong security code too many times. The BankID cannot be used.
- The users BankID is revoked.
- 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.
cancelled
The order was cancelled. The system received a new order for the user.
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:
- RP did not use autoStartToken when starting BankID security program/app. RP must correct this in their implementation.
- 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
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:
|
device |
Information related to the device, holds the following child:
|
cert |
Information related to the user’s certificate (BankID), holds the following children:
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:
|
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)
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":""
}
}