The full BankID Java Server API javadoc is located in the BIDJSERVER_VX_X_X /javadoc directory on the distribution cd. The VX_X_X here symbols the current version number.

BIDFactory

registerBankIDContext

Syntax

public void registerBankIDContext(
    MerchantConfig merchantConfig) throws BIDException

Purpose

This method allows merchant applications to register a merchant context without needing a BankID configuration file.

Parameter	Type	Description
merchantConfig	MerchantConfig	The merchant configuration instance.

This method returns a "no.bbs.server.vos.MerchantConfig" instance. The MerchantConfig instance holds the following information about the input merchant name:

merchant keystore
granted certificate policies for the merchant
merchant name
webaddresses
proxy settings

loadBankIDContext

Syntax

public void loadBankIDContext(    
	String configurationDirectoryPath,
	String merchantName,
    String passphrase) throws BIDException

Purpose

This method allows the merchant application to load a merchant context from a configuration file called <merchantName>.props. This configuration file must be present in the calling applications classpath if the input parameter "configurationDirectoryPath" is null.

Parameter	Type	Description
configurationDirectoryPath	String	The fully qualified path to the directory where <merchantname>.props and merchantname.bid are located. This value may also be null. If this paramter value is null then the merchant configuration file must be located in BankID Server's runtime classpath.
merchantName	String	The merchant name. This is also the name of the merchant's props-file that must be located in the merchant applications classpath or in the configurationDirectoryPath. This name must uniquely identify a merchant.
passphrase	String	The merchant keystore password

getFacade

Syntax

public BIDFacade getFacade(
    String merchantName) throws BIDException

Purpose

This method returns a "no.bbs.server.implementation.BIDFacade" instance. This instance exposes the BankID Java Server API methods.

Parameter	Type	Description
merchantName	String	The merchant name.

BIDFacade

initTransaction

Syntax

public String initTransaction(
    String operation,
    String encKey,
    String encData,
    String encAuth,
    String sid,
    BIDSessionData sessionData) throws BIDException

Purpose

This method handles the initialization of the BankID communication. The behaviour depends on the operation. The method returns the formatted response string to return to the BankID client.
Configuration of other CMS (PKCS#7) and OCSP Response formats than the original default BankID formats, must be done prior to calling this method. This is done by setting two variables in the session data. The main usage scenario is signing of PDFs, and creation of PDF signatures (PAdES). It should be noted that it will not be possible to create SEID SDOs when other formats than the original default BankID formats are used.
For "initSign", all documents not having serialsigningkind serialEndUserOnly will be signed using the merchant BankID certificate in this step.
Configuration of serial signing properties as for instance turnkey or self assembling merchant settings must be done by setting the SerialSigningProperties in the sessionData. turnkey require initTransaction, selfassembler requires initTransactionSelfAssember instead.
The BIDSessionData object is updated and must be stored for later use.

More information about BIDSessionData can be found on the release CD under the BankID Java Server javadoc directory.

Parameter	Type	Description
operation	String	The operation parameter received from the client
encKey	String	The base 64 encoded baseKey received from the client to derive the sessionKey
encData	String	The base 64 encoded encrypted data received from the client
encAuth	String	A base64 encoded message authentication code of all other parameters
sid	String	The sessionID parameter received from client
sessionData	BIDSessionData	The BIDSessionData object to hold the necessarry data

initTransactionSelfAssembler

Syntax

public String initTransactionSelfAssembler(
    String operation,
    String encKey,
    String encData,
    String encAuth,
    String sid,
    BIDSessionData sessionData,
	SealAndMetadataIncrementBuilder sealAndMetadataIncrementBuilder) throws BIDException

Purpose

This method has the same purpose as the initTransaction, but is used for operation="initSign" when the merchant wants to build PAdESes in a selfAssembling mode. The initTransaction method is used for operation="initSign" for turnkey mode.
The method returns the formatted response string to return to the BankID client.
Configuration of serial signing properties as for instance turnkey or self assembling merchant settings must be done by setting the SerialSigningProperties in the sessionData. turnkey require initTransaction, selfassembler requires initTransactionSelfAssember instead.
For each document with serialsigningkind "serial", the merchantsupplied sealAndMetadataIncrementBuilder
will be called. These documents will also be signed using the merchant BankID certificate in this step.
The BIDSessionData's CMS and OCSP format should be set to PKCS7_ISO320001 and OCSP_RFC6960_COMPATIBLE.
All documents should be PDF's, and all should be serial signed.
The BIDSessionData object is updated and must be stored for later use.

More information about BIDSessionData can be found on the release CD under the BankID Java Server javadoc directory.

Parameter	Type	Description
operation	String	The operation parameter received from the client
encKey	String	The base 64 encoded baseKey received from the client to derive the sessionKey
encData	String	The base 64 encoded encrypted data received from the client
encAuth	String	A base64 encoded message authentication code of all other parameters
sid	String	The sessionID parameter received from client
sessionData	BIDSessionData	The BIDSessionData object to hold the necessarry data
sealAndMetadataIncrementBuilder	SealAndMetadataIncrementBuilder	The callbackfunction used to add merchantseal to the PDFs.

initSignSignMerchantSeals

Syntax

public String initSignSignMerchantSeals(
    String operation,
    String encKey,
    String encData,
    String encAuth,
    String sid,
    BIDSessionData sessionData) throws BIDException

Purpose

This method is used for serial signing in the turnkey mode. The operation must be "initSignSignMerchantSeals". The method returns the formatted response string to return to the BankID client.
The BankID client has added the visual seals and metadata for the merchant to the PAdESes, this increment will be added to the BIDSessionData.
Parameters will be decrypted, and the documents with serialsigning kind "serial" will be signed using the merchant BankID certificate. No additional action needed by the merchant.
The BIDSessionData object is updated and must be stored for later use.

More information about BIDSessionData can be found on the release CD under the BankID Java Server javadoc directory.

Parameter	Type	Description
operation	String	The operation parameter received from the client
encKey	String	The base 64 encoded baseKey received from the client to derive the sessionKey
encData	String	The base 64 encoded encrypted data received from the client
encAuth	String	A base64 encoded message authentication code of all other parameters
sid	String	The sessionID parameter received from client
sessionData	BIDSessionData	The BIDSessionData object to hold the necessarry data

initSignBuildEndUserSeal

Syntax

public String initSignBuildEndUserSeal(
    String operation,
    String encKey,
    String encData,
    String encAuth,
    String sid,
    BIDSessionData sessionData,
	SealAndMetadataIncrementBuilder sealAndMetadataIncrementBuilder) throws BIDException

Purpose

This method is used for serial signing in the self assembling merchant case. The operation must be "initSignBuildEndUserSeal". The method returns the formatted response string to return to the BankID client.
In a multidocument scenario, this method is be called once for each PAdES.
Parameters will be decrypted, and for the merchantsupplied callback function will be called.
The merchant callback function shall respond by adding the endUser visual seal to the given document.
The BIDSessionData object is updated and must be stored for later use.

More information about BIDSessionData can be found on the release CD under the BankID Java Server javadoc directory.

Parameter	Type	Description
operation	String	The operation parameter received from the client
encKey	String	The base 64 encoded baseKey received from the client to derive the sessionKey
encData	String	The base 64 encoded encrypted data received from the client
encAuth	String	A base64 encoded message authentication code of all other parameters
sid	String	The sessionID parameter received from client
sessionData	BIDSessionData	The BIDSessionData object to hold the necessarry data
sealAndMetadataIncrementBuilder	SealAndMetadataIncrementBuilder	The callbackfunction used to add endUserseal to one PDF.

verifyTransactionRequest

Syntax

public void verifyTransactionRequest( 
	String operation, 
	String encKey, 
	String encData, 
	String encAuth, 
	String sid, 
	BIDSessionData sessionData) throws BIDException

Purpose

This method handles the verification of data received from the client in the verifyAuth and verifySign operations. It also handles the cases where the client sends a handleError operation, except if the session is configured for self-assembled validation, in which case verifyTransactionRequestSelfAssembler must be used for handleError.
The BIDSessionData object used in initTransaction(…) must be used as input to this method.
The BIDSessionData object is updated.
For "verifySign" and serial signing, this object should be saved for later use since the webclient sends the terminating callback "verifySignAddDSS".

More information about BIDSessionData can be found on the release CD under the BankID Java Server javadoc directory.

Parameter	Type	Description
operation	String	The operation parameter received from the client
encKey	String	The base 64 encoded baseKey received from the client to derive the sessionKey
encData	String	The base 64 encoded encrypted data received from the client
encAuth	String	A base64 encoded message authentication code of all other parameters
sid	String	The sessionID received from the client
sessionData	BIDSessionData	The BIDSessionData object to hold the necessarry data

verifyTransactionRequestSelfAssembler

Syntax

public void verifyTransactionRequestSelfAssembler( 
	String operation, 
	String encKey, 
	String encData, 
	String encAuth, 
	String sid, 
	BIDSessionData sessionData,
	ValidationIncrementBuilder validationIncrementBuilder) throws BIDException

Purpose

This method handles the verification of data received from the client in the verifySign operation for serial signing flows where the merchant itself handles the building and packing of the PAdES validation information. It must also be used for handleError operations if the session is configured for self-assembled validation data.
The BIDSessionData object used in initTransaction(…) must be used as input to this method.
The withSelfAssembledValidation function must have been called on the SerialSigningProperties in BIDSessionData sometime prior to this call.
Each document in the BIDSessionData is updated with certificate validation data by calling the merchantsupplied validationIncrementBuilder,
the complete PAdESes may be extracted using DocumentToSign::getSignedDocumentBytesIncludingIncrementalUpdates from BIDSessionData
Calling this method will prevent the BankID Webclient from sending further callbacks, so in this flow, this is the last callback to handle.

More information about BIDSessionData can be found on the release CD under the BankID Java Server javadoc directory.

Parameter	Type	Description
operation	String	The operation parameter received from the client
encKey	String	The base 64 encoded baseKey received from the client to derive the sessionKey
encData	String	The base 64 encoded encrypted data received from the client
encAuth	String	A base64 encoded message authentication code of all other parameters
sid	String	The sessionID received from the client
sessionData	BIDSessionData	The BIDSessionData object to hold the necessarry data
validationIncrementBuilder	ValidationIncrementBuilder	The callback function that BankID server will call with validation data (ocsps/certificates) when a given document's incremental update is needed.

verifyTransactionResponse

Syntax

public String verifyTransactionResponse(
    BIDSessionData sessionData) throws BIDException

Purpose

This method produces the encrypted response that is returned to the client for the operations verifySign, verifyAuth and handleError.
The BIDSessionData object used in verifyTransactionRequest or verifyTransactionRequestSelfAssembler must be used as input to this method.

More information about BIDSessionData can be found on the release CD under the BankID Java Server javadoc directory.

Parameter	Type	Description
sessionData	BIDSessionData	The BIDSessionData object to hold the necessarry data

verifySignAddDSS

Syntax

public String verifySignAddDSS(String operation, 
	String encKey, 
	String encData, 
	String encAuth, 
	String sid, 
	BIDSessionData sessionData) throws BIDException

Purpose

This method produces the encrypted response that is returned to the client for the operation "verifySignAddDSS". Used for serial signing only.
The PAdES verification data pr. document is received from the WebClient, decrypted and added to documents in BIDSessionData.
The BIDSessionData object used in verifyTransactionRequest must be used as input to this method.
This is the last callback from Webclient, so no need to save the BIDSessionData
Each document in the BIDSessionData is updated with certificate validation data, the complete PAdESes for each may be extracted using DocumentToSign::getSignedDocumentBytesIncludingIncrementalUpdates()

More information about BIDSessionData can be found on the release CD under the BankID Java Server javadoc directory.

Parameter	Type	Description
sessionData	BIDSessionData	The BIDSessionData object to hold the necessarry data

initSession

Syntax

public InitSessionInfo initSession(
    InitSessionInfo initSessionInfo) throws BIDException

Purpose

This method initiates the process of starting the BankID Web-client. The input InitSessionInfo instance must contain the following parameters:

merchantURL (setMerchantURL)
useragent (setUserAgent)
action (setAction)
localeId (setLocaleId)
sid (setSid)
suppressBroadcast(setSuppressBroadcast)
nextUrl (setNextUrl)
merchantFEDomain (setMerchantFEDomain)
certType (setCertType)
timeout (setTimeout)
withCredentials(setWithCredentials)
merchantFEAncestors (setMerchantFEAncestors) (if clientVersion 2.1)
clientSessionTimeout (setClientSessionTimeout) (if clientVersion 2.1)
clientVersion (setClientVersion)

Additionally, if the session being initialized is a signing session, the following parameters must also be set on the initSessionInfo object:

showUnderstanding (setShowUnderstanding) sign only
showConfirmation (setShowConfirmation) sign only
docDisplayMode (setDocDisplayMode) sign only
extPDFDomain (setExtPDFDomain) sign only, (if clientVersion 2.0)

If another Client Proxy than the default is used, the url to the client proxy must be given. If the custom client proxy is not registered in the BankID COI database with a public key, the hex encoded modulus of the public key must be specified as well. This is done by populating the parameters in the list below:

clientProxyURL (setClientProxyURL) (if clientVersion 2.1)
clientProxyPublicKey (setClientProxyPublicKey) (if clientVersion 2.1)

The returned "no.bbs.server.vos.InitSessionInfo" contains the traceID received from BankID COI, and a helperURI and a clientID which are used together to retrieve the BankID Web-client. For additional information take a look at the BankID Java Server javadoc located on the BankID release CD, or see the implementation guides [IMPLW] and [IMPL].

Parameter	Type	Description
initSessionInfo	InitSessionInfo	The instance holding the values for the initSession request along with already set client environment configurations. We recommend all applications to log the messages returned from this method if any.

generateMerchantReference

Syntax

public String generateMerchantReference(
    String locale) throws BIDException
  
// OR
  
@Deprecated public String generateMerchantReference() throws BIDException

Purpose

This method generates the reference to show to the user during mobile authentication. This reference will also be visible on the mobile phone of the user when it is added to the MobileInfo object during the requestMobileAction(mobileInfo) call.
The merchant reference generated is a combination of two words derivided from two dictionaries provided by the FOI. BankID Server will cache these dictionaries for 24 hours.
A call to the method without the "locale" parameter is deprecated, but will for a period use the default locale; no_NO.

requestMobileAction

Syntax

public TransactionAndStatus requestMobileAction(
    MobileInfo mobileInfo)throws BIDException

Purpose

This method can be used by the merchant to perform a BankID operation using a mobile phone.
MobileInfo instance MUST contain the following parameters:

phoneNumber
phoneAlias
URL
action
merchantReference (if action is "auth")

For more details please refer to the BankID Java Server javadoc located on the BankID release CD.

Parameter	Type	Description
mobileInfo	MobileInfo	Object containing the needed data. Described closer in section 4.3 in [IMPL] .

requestMobileStatus

Syntax

public String requestMobileStatus(
        String transactionReference) throws BIDException

Purpose

Method to get the status from an earlier initialized mobile phone signing process. Note that this method can only be called during asynchronous communication.

Parameter	Type	Description
transactionReference	String	The transaction reference received from the previous successful requestMobileAction() call

pushSMS

Syntax

public String pushSMS(
    String transactionReference,
    String text) throws BIDException

Purpose

This method is used for sending an SMS to the end user after a successful transaction.

Parameter	Type	Description
transactionReference	String	The transaction reference received from the previous successful requestMobileAction() call
text	String	The text to be displayed on the phone. Maximum 120 characters and ISO-8859-1 encoded.

getTransactionInfo

Syntax

public HashMap<String, String> getTransactionInfo(
    String key,
    List<String> oidList,
    long timeoutInMs) throws BIDException

Purpose

The getTransactionInfo function can be used to request information about a transaction identified by "key". The "oidList" parameter specifies the type of information, and the "timeoutInMs" is used to kill the request if the service is slow to perform or no transaction data is available yet.
Depending on the merchant's access rights the returned HashMap will contain the requested OIDs and its values.

Parameter	Type	Description
key	String	The uniq identifier for the data to retrieve.
oidList	List	The list of "OIDs" the merchant is asking for. Each OID represents a type of data.
timeoutInMs	long	Timeout in milliseconds

getVersionInfo

This method returns information about the BankID Java Server and the runtime environment.

Syntax

public static String getVersionInfo()

Purpose

The getVersionInfo method is used to retrieve some information about the BankID Java Server and the runtime environment. The method returns a java.lang.String on the following format:
[<key>=<value>][<key>=<value>] … [<key>=<value>]
The following information is returned, if available:

bankIdServerType
bankIdServerVersion
platform
arch
bouncyCastleVersion
javaCompileVersion
javaVersion

getRawTransactionInfo

The BIDSessionData class is extended with a method for getting a map of transaction data from the BankID Web-client.
Syntax

public Map<String, String> getRawTransactionInfo()

Purpose

This method returns a map containing all information from the client regarding the BankID transaction. The map is available after verifyTransactionRequest is called in the verifySign or handleError callback. If the map is empty or does not exist, null is returned.

getRawTransactionInfoItem

Syntax

public String getRawTransactionInfoItem(
    String key)

Purpose

This is an alternative method to the getRawTransactionInfo. Instead of first getting the whole map and then get a single value, this method lets you get the single value right away.
If the supplied key does not exists in the map, null is returned.

Parameter	Type	Description
key	String	The rawTransactionInfoItem key of the wanted value.

Browser not supported