Signing

Enterprise Signing

Some flows require the end user to sign using BankID. The Signing API provides support for requesting signatures using BankID.

Please note that the sandbox environment is exclusively based on mocked data and responses to test the integration, so real signatures are not supported.

Test the API

API usage

The end user who is part of a signing will be called a participant and the flows that require signing will provide the id for the participant in the response payload which will be used in /start, /start/phone, /collect or /cancel.

Initiating a signing request

To initiate a signing, the client calls the /start or the /start/phone endpoint.

The /start endpoint returns a static autostart_token and an dynamic qr_string that both can be used to launch the BankID app on the user's device.

To launch the BankID app on the same device, the autostart_token can be used to open the BankID app directly using a scheme URL, for example bankid://autostarttoken=475979bc-4373-4d6f-91ca-0909dc1fd816&redirect=null.

To launch the BankID app on a different device, the data in qr_string can be used to generate a QR code that the user can scan with the BankID app.

The client should call /collect to get the status of the BankID signing but also to get a new qr_string.

A new QR code needs to be generated from a new qr_string, between once and twice every 2 seconds to avoid a stale QR code to be shown.

If the user is calling in by phone or being called by the Relying Party (RP), the /start/phone endpoint should be used. When initiating the signing via the phone flow, the BankID app is auto launched as soon as the user opens up the BankID and no autostart token or QR code is needed to launch the BankID app.

For more information about how the BankID integration works, see the official documentation from BankID.

Collecting status

The API provides a /collect endpoint that gives back the status for the signing and a more detailed hintCode.

In addition to the statuses provided by the BankID API, the Signing API provides a INITATED and COLLECT_ERROR status. See the table below for more information about the statuses and the hint codes returned by the Signing API.

Status	Description	Hint codes	Mapped to BankID status
`INITIATED`	Signing has been initiated towards BankID	`n/a`	`NO`
`PENDING`	Signing is pending. The `hint_code` describes more details about the status.	`OUTSTANDING_TRANSACTION`, `NO_CLIENT`, `STARTED`, `USER_SIGN`, `USER_MRTD`, `USER_CALL_CONFIRM`, `UNKNOWN`	`YES`
`COMPLETE`	Signing has been completed successfully.	`n/a`	`YES`
`FAILED`	Signing has failed. The `hint_code` describes more details about the status.	`EXPIRED_TRANSACTION`, `CERTIFICATE_ERR`, `USER_CANCEL`, `CANCELLED`, `START_FAILED`, `USER_DECLINED_CALL`, `NOT_SUPPORTED _BY_USER_APP`, `UNKNOWN`	`YES`
`COLLECT_ERROR`	An unexpected error occurred and clients should stop polling for collect. A new signing should be initiated.	`n/a`	`NO`

See the BankID documentation here for more detailed information about hint codes.

Cancellations and retries

Signing requests can be cancelled by calling /cancel. A new signing for the same participant can be initiated again using /start and /start/phone

It is also possible to retry a signing request without explicitly calling cancel first. In this scenario there are some caveats:

Two consecutive calls to /start from the same IP address will cause a 409 Conflict. After the 409 it can however be called again successfully without cancelling first.
Two consecutive calls to /start from different IP addresses will cause a 409 Conflict and that personal number will be blocked for approximately 3 minutes. Cancel will not work meanwhile.
Two consecutive calls to /start/phone will cause 409 Conflict and that personal number will be blocked for approximately one minute. Cancel will not work meanwhile.

Caveats

Triggering 2 consecutive calls to /start from different IP addresses for the same personal number within 3 minutes will result in 409 with the following response:

{
   "type": "about:blank",
   "title": "Conflict",
   "status": 409,
   "instance": "/signing/start",
   "reason": {
     "code": "RFA4_SIGNING_IN_PROGRESS",
     "message": "An identification or signing for this personal number is already started. Please try again"
   }
}

There are more cases that could result in RFA4_SIGNING_IN_PROGRESS which are as follows:

When the end user triggered a signing with some other bank and tries to initiate signing with SBAB
When /start is called back to back without calling /cancel in between. /start will be successful on the third invocation
When /start/phone is invoked back to back without invoking /cancel in between. Consecutive invocations of /start/phone will return RFA4_SIGNING_IN_PROGRESS until a minute is passed.
When /start/phone is followed by /start or vice-versa

This is to avoid any fraud signings happening from different IPs. Classic case is an attacker using VPN. Please be aware this will temporarily block the end user's BankId and the user need to wait sometime (Approximately 1 minute) until he could use the BankId again

Error handling

The Signing API uses standard HTTP status codes and error responses. The error responses follow the problem detail specification.

Below is an example such of an error response:

{
  "title": "Conflict",
  "status": 409,
  "instance": "/signing/start",
  "reason":
    {
      "code": "RFA4_SIGNING_IN_PROGRESS",
      "message": "An identification or signing for this personal number is already started. Please try again"
    }
}

A more detailed description of the error codes and reason codes can also be found in the API documentation.