Signing
Start sign
The POST /v3/bankid-no/sign endpoint is used to sign a text using BankID (NO).
POST /v3/bankid-no/sign
Authorization: Basic ${ base64(accountId + ':' + secretKey) }
{
"text": "Text to be signed",
"refId": "12398698",
"redirectUrl": "https://..."
}
| Parameter | Required | Description |
|---|---|---|
| text | Yes | Text that will be visible in the end user's BankID application during signing. |
| refId | No | Reference ID which will be included in a Collect and in the redirect. |
| redirectUrl | No | Custom redirect URL, must be whitelisted. |
Response:
IDkollen will respond with HTTP status 201 for successful request, or 4xx/5xx on errors. For more information about errors, please see the Errors section.
{
"id": "1668b9da-bff1-4dfc-ad48-60507b5a8d12",
"refId": "12398698",
"status": "PENDING",
"url": "https://..."
}
| Property | Description |
|---|---|
| id | Authentication id, used to cancel or get the status of this sign request. |
| refId | The refId given in the request, if any. |
| url | The URL where the end user can sign. |
Code redirect:
Once the end user has signed, they will be redirected to the redirect URL provided to IDkollen by you, including the very same "id" as a request parameter that can be used in the Collect step. If the parameter "refId" was used in the request, it will also be included as a request parameter.
https://your.redirect.url/?id=1668b9da-bff1-4dfc-ad48-60507b5a8d12&refId=12398698
A whole domain may also be whitelisted and sent with each request, but must for security reasons be whitelisted first. Multiple domains may be whitelisted. Please provide your whitelisted URLs by emailing us at support@idkollen.se.
Fetch result
The GET /v3/bankid-no/sign/{{id}} endpoint is used to check the status of a sign request.
NOTE: This endpoint is rate limited to one request per second.
GET /v3/bankid-no/sign/{{id}}
Authorization: Basic ${ base64(accountId + ':' + secretKey) }
This endpoint will respond with a HTTP status of 404 if the sign session has expired.
The status of a sign can be either one of: PENDING, COMPLETED or FAILED.
Pending
{
"id": "1668b9da-bff1-4dfc-ad48-60507b5a8d12",
"refId": "12398698",
"status": "PENDING"
}
| Parameter | Description |
|---|---|
| refId | The refId given in the request, if any. |
Completed
{
"id": "1668b9da-bff1-4dfc-ad48-60507b5a8d12",
"refId": "12398698",
"status": "COMPLETED",
"ssn": "YYYYMMDDXXXX",
"name": "Firstname Lastname",
"givenName": "Firstname",
"surname": "Lastname",
"birthDate": "1908-09-29",
"signResult": {
"endUser": "MIAGC...",
"merchant": "MIAGC...",
"hash": "4oK3g..."
}
}
| Parameter | Description |
|---|---|
| refId | The refId given in the request, if any. |
| ssn | A Norwegian personal identification number to be used to complete the transaction. May be null if requestSsn was unset. |
| name | The full name of the signing user. |
| givenName | The given name of the signing user. |
| surname | The surname of the signing user. |
| birthDate | The birth date of the signing user. |
| signResult | Present for signs, containing signatures of the merchant and end user, as well as the hash of the signed text. |
Failed
{
"id": "1668b9da-bff1-4dfc-ad48-60507b5a8d12",
"refId": "12398698",
"status": "FAILED",
"error": "INVALID_ID"
}
| Parameter | Description |
|---|---|
| refId | The refId given in the request, if any. |
| error | An error code describing the reason for why the sign failed. |
The error may be one of the following values:
| Code | Description |
|---|---|
| AUTH_FAILED | A generic code for any kind of failure. |
| CANCELLED | The authentication was cancelled either by the user or the partner. |
| INVALID_ID | The ID has expired or is otherwise invalid. |
| INTERNAL_ERROR | An internal error occurred causing the authentication to fail. |
| SESSION_TIMEOUT | The authentication expired or timed out. |
| UNSUPPORTED_CLIENT | The client used for the authentication is not supported. |
New error codes may be added in the future without prior notice. The partner should therefore handle unknown error codes in their implementations.
Cancel signing
The DELETE /v3/bankid-no/sign/{{id}} endpoint is used to cancel an ongoing BankID (NO) signing.
DELETE /v3/bankid-no/sign/{{id}}
Authorization: Basic ${ base64(accountId + ':' + secretKey) }
IDkollen will respond with HTTP status 204 for successful request, or 4xx/5xx on errors. For more information about errors, please see the Errors section.