Signing of Loan Application and Pre-Approvals

Loan applications require the main applicant to sign using BankID before the application is sent into SBABs credit handling system.

For Pre approvals all applicants have to sign before the pre approval is sent to the credithandling system. Note that sandbox doesn't support pre approval flow as of now.

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

— öppnas i ny flik

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.

The signing API that is used for signing of loan applications and pre approvals has the following endpoints:

Signing API flow

1. Initiate signing for an applicant using any one of the following 3 methods

A. BankID app on the same device using autostart_token.

1. Use POST https://api.sbab.se/partner/signing/1.0/start to start signing for an applicant.
   Use the signing_process.participants[n].id value from the status response for participant_id.
   Request body StartSigningRequest:

This will return the autostart_token and qr_string which should be used to start signing.
Response body StartSigningResponse:

2. The BankID app should be launched using this url format. bankid://autostarttoken=<autostart_token>&redirect=null Ex. bankid://autostarttoken=41d9be69-7686-4ac4-94b4-7e78cc6f598b&redirect=null
3. The user can sign using the BankID app.

OR

B. BankID app on another device using the qr_string.

1. Use POST https://api.sbab.se/partner/signing/1.0/start to start signing for an applicant.
   Use the signing_process.participants[n].id value from the status response for participant_id.
   Request body StartSigningRequest:

This will return the autostart_token and qr_string which should be used to start signing.
Response body StartSigningResponse:

2. The QR code should be displayed to the user to scan using the BankID app on another device.
   

OR

C. On a phone call with the customer using start/phone endpoint.

1. Use POST https://api.sbab.se/partner/signing/1.0/start/phone if you are in a call with the client.
   Use the signing_process.participants[n].id value from the MortgagesStatusDataV2 response for participant_id.
   Use call_initiator as RP if you are initiating the call. If the customer initiates the call, use call_initiator as USER.
   Request body StartPhoneSigningRequest:

Response status code: 204

2. This will automatically launch the BankID app on the user's device.
3. The user will get a notification to confirm that they are currently in a call with the partner.
4. Once the user confirms, they can sign through the BankID app.

2. Use the signing/collect endpoint to obtain the status of the signing or get a new qr_string

This endpoint should be used to display information about the signing for the user.

1. Use POST https://api.sbab.se/partner/signing/1.0/collect to get the status of the signing or get a new qr_string.
   Use the signing_process.participants[n].id value from the status response for participant_id.
   Request body CollectSigningRequest:

Response body CollectSigningResponse before status COMPLETE:

2. Display the QR code to the user to scan using the BankID app.
3. OR use the status and hint_code to check the status of the signing.
   
4. When the status is COMPLETE, the signing has been successfully completed and the system time when this was registered is also shown:

Response body CollectSigningResponse when status is COMPLETE:

See the BankID documentation here— öppnas i ny flik for more detailed information about hint codes.

signing/cancel endpoint

Use POST https://api.sbab.se/partner/signing/1.0/cancel to cancel the signing.
Use the signing_process.participants[n].id value from the status response for participant_id.
Request body CancelSigningRequest:

Response status code: 204

Retries

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:

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— öppnas i ny flik.

Below is an example such of an error response:

A more detailed description of the error codes and reason codes can also be found in the API documentation— öppnas i ny flik.