Transactions

Types of Transaction

A certified user can manage the following three types of transactions:

Transaction Type Description
Authentication auth Authentication transaction
Documents doc Document signing transaction
Message message Message only transaction

Transaction SubTypes

In addition to the transaction type, transactions also have a subType property. This can be used in conjunction with the TransactionType, to determine the exact type of the transaction.

Currently subTypes only exist for auth (authentication) and doc (document) transactions:

Transaction Type SubType Description
Authentication authWEB Web login transaction
authIDV Identity verification transaction
Document docPDF PDF document signing transaction
docXML XML document signing transaction
docMIXED Mixed PDF & XML document signing transaction

Documentation

Transaction Actions

Each transaction type has a sepcific set of actions that can be applied to it. These are detailed below:

Transaction Type Confirm Sign Reject Dismiss
Authentication ✔︎ ✔︎
Document ✔︎ (Level1-3) ✔︎
Message ✔︎

Requesting Transactions

The requestTransactions() can be used to request a paged and filtered list of transactions. The results can be filtered on Status (by specifying transactions with which statuses to return) and the Type of transaction to return.

Swift3

    SDK.getClient.requestTransactions(max: 100,
                                      offset: nil,
                                      status: [pending, .expired, .failed, .successful, .rejected],
                                        type: .auth,
                                documentType: nil,

        onSuccess: { (transactions) in 
            // Handle Transactions List
        }, onNoConnection: {
                // Handle no connection Error
        }, onInvalidToken: { (error) in
                // Handle invalid token error
        }, onClientError: { (error) in
                // Handle client error
    })

ObjC

    [biidCoreSDK.getClient requestTransactionsWithMax:100
                                   offset:0
                        transactionStatus:@[@(TransactionStatusAll)]
                          transactionType:TransactionTypeAuth
                             documentType:DocumentTypeAll
        onSuccess:^(NSArray<Transaction *> * _Nonnull transactions) {
            // Handle Transactions List
        }
        onNoConnection:^void() {
            // Handle no connection Error
        }
        onInvalidToken:^void(NSError * _Nonnull error) {
            // Handle invalid token error
        }
        onClientError:^void(NSError * _Nonnull error) {
            // Handle client error
        }
    ];

Documentation

Authentication requests

Confirm Authentication

An authentication request can be confirmed by first requesting the Transaction‘s details by it’s ID and then confirming it using confirmAuthentication(). On successful confirmation, the evidence generated is stored in the Back Office with the transaction.

Swift3

    SDK.getClient.requestAuthenticationTransaction(forTransactionID: transactionID,
        onSuccess: { (transaction) in

            SDK.getClient.confirmAuthentication(forTransaction: transaction,
                onSuccess: {
                        // Handle Authentication confirmation success
                }, onNoConnection: {
                        // Handle no connection Error
                }, onInvalidToken: { (error) in
                        // Handle invalid token error
                }, onTransactionNotPendingError: { (error) in
                        // Handle Transaction not pending error
                }, onClientError: { (error) in
                    // Handle client error
            })

        }, onNoConnection: {
                // Handle no connection Error
        }, onInvalidToken: { (error) in
                // Handle invalid token error
        }, onClientError: { (error) in
                // Handle client error
    })

ObjC

    [biidCoreSDK.getClient requestAuthenticationTransactionWithID:transactionID
        onSuccess:^(AuthenticationTransaction * _Nonnull transaction) {
            [biidCoreSDK.getClient confirmAuthenticationForTransaction:transaction
              onSuccess:^{
                    // Handle Authentication confirmation success              
                }
                onNoConnection:^void() {
                    // Handle no connection Error
                }
                onInvalidToken:^void(NSError * _Nonnull error) {
                    // Handle invalid token error
                }
                onTransactionNotPendingError:^void(NSError * _Nonnull error) {
                    // Handle Transaction not pending error
                }
                onClientError:^void(NSError * _Nonnull error) {
                    // Handle client error
                }
            ];
        }
        onNoConnection:^void() {
            // Handle no connection Error
        }
        onInvalidToken:^void(NSError * _Nonnull error) {
            // Handle invalid token error
        }
        onClientError:^void(NSError * _Nonnull error) {
            // Handle client error
        }
    ];

Documentation and Documentation

Auth Confirmation Flow

Reject Authentication

An authentication transaction can be rejected as follows:

Swift3

    SDK.getClient.rejectAuthenticationTransaction(forTransactionID: transactionID!,
        onSuccess: {
            // Handle transaction rejection success
        }, onNoConnection: {
                // Handle no connection Error
        }, onInvalidToken: { (error) in
            // Handle invalid token error
        }, onTransactionNotPendingError: { (error) in
                // Handle Transaction not pending error
        }, onClientError: { (error) in
                // Handle client error
    })

ObjC

    [biidCoreSDK.getClient rejectAuthenticationTransactionWithID:transactionID
        onSuccess:^{
            // Handle transaction rejection success
        }
        onNoConnection:^void() {
            // Handle no connection Error
        }
        onInvalidToken:^void(NSError * _Nonnull error) {
            // Handle invalid token error
        }
        onTransactionNotPendingError:^void(NSError * _Nonnull error) {
            // Handle Transaction not pending error
         }
        onClientError:^void(NSError * _Nonnull error) {
            // Handle client error
        }
    ];

Documentation

Auth Rejection Flow

Document signing requests

Retrieving document details

The details of a Document in a document transaction request by requesting the document’s ID as follows:

Swift3

    SDK.getClient.requestDocument(forDocumentID: documentID,
        onSuccess: { (document) in
                // Do something with the document such as get the document's content
        }, onNoConnection: {
                // Handle no connection Error
        }, onInvalidToken: { (error) in
                // Handle invalid token error
        }, onClientError: { (error) in
                // Handle client error
    })

ObjC

    [biidCoreSDK.getClient requestDocumentForDocumentID:documentID
        onSuccess:^(Document * _Nonnull document) {
            // Do something with the document such as get the document's content
        }
        onNoConnection:^void() {
            // Handle no connection Error
        }
        onInvalidToken:^void(NSError * _Nonnull error) {
            // Handle invalid token error
        }
        onClientError:^void(NSError * _Nonnull error) {
            // Handle client error
        }
    ];

Documentation

Document Image preview

To retrieve a preview image of a document, the document object should first be retrieved (as detailed above) and then passed in as a parameter to the following request:

Swift3

    SDK.getClient.requestDocumentPreview(forDocument: document,
       onSuccess: { (fileURL) in
                // Do something with the document (accessible via the fileURL)
        }, onNoConnection: {
                // Handle no connection Error
        }, onInvalidToken: { (error) in
                // Handle invalid token error
        }, onClientError: { (error) in
                // Handle client error
    })

ObjC

    SDK.getClient requestDocumentPreviewForDocument:document
        onSuccess:^(NSURL * _Nonnull fileURL) {
            // Do something with the document (accessible via the fileURL)
        }
        onNoConnection:^void() {
            // Handle no connection Error
        }
        onInvalidToken:^void(NSError * _Nonnull error) {
            // Handle invalid token error
        }
        onClientError:^void(NSError * _Nonnull error) {
            // Handle client error
        }
    ];

Notes:

  1. A preview is only generated for documents of type PDF.
  2. For XML documents, requesting a document preview will return a client error of failedToGetDocumentPreview.

Documentation

Document content

To download the content of a document to the device, the document object should first be retrieved (as detailed above) and then passed in as a parameter to the following request:

Swift3

    SDK.getClient.requestDocumentContent(forDocument: document,
       onSuccess: { (fileURL) in
                // Do something with the document (accessible via the fileURL)
        }, onNoConnection: {
                // Handle no connection Error
        }, onInvalidToken: { (error) in
                // Handle invalid token error
        }, onClientError: { (error) in
                // Handle client error
    })

ObjC

    SDK.getClient requestDocumentContentForDocument:document
        onSuccess:^(NSURL * _Nonnull fileURL) {
            // Do something with the document (accessible via the fileURL)
        }
        onNoConnection:^void() {
            // Handle no connection Error
        }
        onInvalidToken:^void(NSError * _Nonnull error) {
            // Handle invalid token error
        }
        onClientError:^void(NSError * _Nonnull error) {
            // Handle client error
        }
    ];

NB If successfully returned, the document will be download to the device and will be accessible via the returned file URL.

Documentation

Publicly accessible documents

If a document has been marked as isPublic on the server side, it is possible to retrieve the document content, for display or download, via it’s publicURL property.

For example to display a document in a WKWebView, the following code could be used:

    let url = URL(string: theDocument.publicURL)
    let request = URLRequest(url: url!)
    webView.load(request)

Signing a document (Level 1, Level 2, Level 3 accredited user)

A user accredited to Level 1, Level 2 or Level 3 can sign the documents in a transaction as follows:

Swift3

    SDK.getClient.requestDocumentsTransaction(forTransactionID: transactionID,
        onSuccess: { (transaction) in

            SDK.getClient.signDocuments(forTransaction: transaction,
                onSuccess: {
                        // Handle Document Signing success
                }, onNoConnection: {
                        // Handle no connection Error
                }, onInvalidToken: { (error) in
                        // Handle invalid token error
                }, onTransactionNotPendingError: { (error) in
                        // Handle Transaction not pending error
                }, onClientError: { (error) in
                    // Handle client error
            })

        }, onNoConnection: {
                // Handle no connection Error
        }, onInvalidToken: { (error) in
                // Handle invalid token error
        }, onClientError: { (error) in
                // Handle client error
    })

ObjC

    [biidCoreSDK.getClient requestDocumentsTransactionWithID:transactionID
        onSuccess:^(AuthenticationTransaction * _Nonnull transaction) {
            [biidCoreSDK.getClient signDocuments:transaction
              onSuccess:^{
                    // Handle Document Signing success              
                }
                onNoConnection:^void() {
                    // Handle no connection Error
                }
                onInvalidToken:^void(NSError * _Nonnull error) {
                    // Handle invalid token error
                }
                onTransactionNotPendingError:^void(NSError * _Nonnull error) {
                    // Handle Transaction not pending error
                }
                onClientError:^void(NSError * _Nonnull error) {
                    // Handle client error
                }
            ];
        }
        onNoConnection:^void() {
            // Handle no connection Error
        }
        onInvalidToken:^void(NSError * _Nonnull error) {
            // Handle invalid token error
        }
        onClientError:^void(NSError * _Nonnull error) {
            // Handle client error
        }
    ];

On successful signing, the signed evidence is stored with the transaction in the Back Office.

Documentation and Documentation

Doc Signing Flow [L1, L2, L3]

Reject Document

A document signing request can be rejected as follows:

Swift3

    SDK.getClient.rejectDocumentsTransaction(forTransactionID: transactionID!,
        onSuccess: {
            // Handle transaction rejection success
        }, onNoConnection: {
            // Handle no connection Error
        }, onInvalidToken: { (error) in
            // Handle invalid token error
        }, onTransactionNotPendingError: { (error) in
            // Handle Transaction not pending error
        }, onClientError: { (error) in
            // Handle client error
    })

ObjC

    [biidCoreSDK.getClient rejectDocumentsTransactionWithID:transactionID
        onSuccess:^{
            // Handle transaction rejection success
        }
        onNoConnection:^void() {
            // Handle no connection Error
        }
        onInvalidToken:^void(NSError * _Nonnull error) {
            // Handle invalid token error
        }
        onTransactionNotPendingError:^void(NSError * _Nonnull error) {
            // Handle Transaction not pending error
         }
        onClientError:^void(NSError * _Nonnull error) {
            // Handle client error
        }
    ];

Documentation

Doc Rejection Flow

Messages

Dismiss Message

A Message transaction is an information based transaction. It has only one action and that is Dismiss. Dismissing a Message Transaction, generates evidence providing proof that the message has been seen.

A message can be dismissed by first requesting the message Transaction’s details by it’s ID and then dismissing it using dismissMessage() :

Swift3

    SDK.getClient.requestMessageTransaction(forTransactionID: transactionID,
        onSuccess: { (transaction) in
            SDK.getClient.dismissMessage(forTransaction: transaction,
                onSuccess: {
                    // Handle Dismiss Message Success
                }, onNoConnection: {
                    // Handle no connection Error
                }, onInvalidToken: { (error) in
                    // Handle invalid token error
                }, onTransactionNotPendingError: { (error) in
                    // Handle Transaction not pending error
                }, onClientError: { (error) in
                    // Handle client error
            })          
        }, onNoConnection: {
                // Handle no connection Error
        }, onInvalidToken: { (error) in
                // Handle invalid token error
        }, onClientError: { (error) in
                // Handle client error
    })

ObjC

    [biidCoreSDK.getClient requestMessageTransactionWithID:transactionID
        onSuccess:^(MessageTransaction * _Nonnull transaction) {
            [biidCoreSDK.getClient dismissMessageForTransaction:transaction
                onSuccess:^{
                    // Handle Dismiss Message Success
                }
                onNoConnection:^void() {
                    // Handle no connection Error
                }
                onInvalidToken:^void(NSError * _Nonnull error) {
                    // Handle invalid token error
                }
                onTransactionNotPendingError:^void(NSError * _Nonnull error) {
                    // Handle Transaction not pending error
                }
                onClientError:^void(NSError * _Nonnull error) {
                    // Handle client error
                }
            ];      
        }
        onNoConnection:^void() {
            // Handle no connection Error
        }
        onInvalidToken:^void(NSError * _Nonnull error) {
            // Handle invalid token error
        }
        onClientError:^void(NSError * _Nonnull error) {
            // Handle client error
        }
    ];

Documentation and Documentation