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: nil, type: .auth, documentType: nil,
         onSuccess: {
             // Handle Transactions List
         }, onNoConnection: {
             // Handle no connection Error
         }, onInvalidUserStateError: { (error) in
             // Handle incorrect user state
         }, onInvalidToken: { (error) in
             // Handle invalid token error
         }, onUserLockedError: { (error) in
             // Handle locked user 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
         }
         onInvalidUserStateError:^void(NSError * _Nonnull error) {
             // Handle incorrect user state
         }
         onInvalidToken:^void(NSError * _Nonnull error) {
             // Handle invalid token error
         }
         onUserLockedError:^void(NSError * _Nonnull error) {
             // Handle locked user 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

             location = CLLocation(latitude: 51.509865, longitude: -0.118092)
             SDK.getClient.confirmAuthentication(forTransaction: transaction, withLocation: location,
                onSuccess: {
                    // Handle Authentication confirmation success
                }, onNoConnection: {
                    // Handle no connection Error
                }, onInvalidUserStateError: { (error) in
                    // Handle incorrect user state
                }, onInvalidToken: { (error) in
                    // Handle invalid token error
                }, onTransactionNotPendingError: { (error) in
                    // Handle Transaction not pending error
                }, onUserLockedError: { (error) in
                    // Handle locked user error
                }, onClientError: { (error) in
                    // Handle client error
            })  

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

ObjC

    [biidCoreSDK.getClient requestAuthenticationTransactionWithID:transactionID
        onSuccess:^(AuthenticationTransaction * _Nonnull transaction) {

            CLLocation *location = [[CLLocation alloc] initWithLatitude:51.509865 longitude:-0.118092];
            [biidCoreSDK.getClient confirmAuthenticationForTransaction:transaction  withLocation:location
                onSuccess:^{
                    // Handle Authentication confirmation success
                }
                onNoConnection:^void() {
                    // Handle no connection Error
                }
                onInvalidUserStateError:^void(NSError * _Nonnull error) {
                    // Handle incorrect user state
                }
                onInvalidToken:^void(NSError * _Nonnull error) {
                    // Handle invalid token error
                }
                onTransactionNotPendingError:^void(NSError * _Nonnull error) {
                    // Handle Transaction not pending error
                }
                onUserLockedError:^void(NSError * _Nonnull error) {
                    // Handle locked user error
                }
                onClientError:^void(NSError * _Nonnull error) {
                    // Handle client error
                }
            ];

        }
        onNoConnection:^void() {
         // Handle no connection Error
        }
        onInvalidUserStateError:^void(NSError * _Nonnull error) {
         // Handle incorrect user state
        }
        onInvalidToken:^void(NSError * _Nonnull error) {
         // Handle invalid token error
        }
        onUserLockedError:^void(NSError * _Nonnull error) {
         // Handle locked user 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.requestDocumentsTransaction(forTransactionID: transactionID
         onSuccess: { (transaction) in

             location = CLLocation(latitude: 51.509865, longitude: -0.118092) 
             SDK.getClient.rejectAuthenticationTransaction(forTransactionID: transactionID!, withLocation: location,
                 onSuccess: {
                     // Handle transaction rejection success
                 }, onNoConnection: {
                     // Handle no connection Error
                 }, onInvalidUserStateError: { (error) in
                     // Handle incorrect user state
                 }, onInvalidToken: { (error) in
                     // Handle invalid token error
                 }, onTransactionNotPendingError: { (error) in
                     // Handle Transaction not pending error
                 }, onUserLockedError: { (error) in
                     // Handle locked user error
                 }, onClientError: { (error) in
                     // Handle client error
             })

        }, onNoConnection: {
            // Handle no connection Error
        }, onInvalidUserStateError: { (error) in
            // Handle incorrect user state
        }, onInvalidToken: { (error) in
            // Handle invalid token error
        }, onUserLockedError: { (error) in
            // Handle locked user error
        }, onClientError: { (error) in
            // Handle client error
    })

ObjC

     [biidCoreSDK.getClient requestDocumentsTransactionWithID:transactionID
         onSuccess:^(AuthenticationTransaction * _Nonnull transaction) {

             CLLocation *location = [[CLLocation alloc] initWithLatitude:51.509865 longitude:-0.118092];
             [biidCoreSDK.getClient rejectAuthenticationTransactionWithID:transactionID withLocation:location
                 onSuccess:^{
                     // Handle transaction rejection success
                 }
                 onNoConnection:^void() {
                     // Handle no connection Error
                 }
                 onInvalidUserStateError:^void(NSError * _Nonnull error) {
                     // Handle incorrect user state
                 }
                 onInvalidToken:^void(NSError * _Nonnull error) {
                     // Handle invalid token error
                 }
                 onTransactionNotPendingError:^void(NSError * _Nonnull error) {
                     // Handle Transaction not pending error
                 }
                 onUserLockedError:^void(NSError * _Nonnull error) {
                     // Handle locked user error
                 }
                 onClientError:^void(NSError * _Nonnull error) {
                     // Handle client error
                 }
             ];

         }
         onNoConnection:^void() {
             // Handle no connection Error
         }
         onInvalidUserStateError:^void(NSError * _Nonnull error) {
             // Handle incorrect user state
         }
         onInvalidToken:^void(NSError * _Nonnull error) {
             // Handle invalid token error
         }
         onUserLockedError:^void(NSError * _Nonnull error) {
             // Handle locked user error
         }
         onClientError:^void(NSError * _Nonnull error) {
             // Handle client error
         }
     ];

Documentation

Auth Rejection Flow

Document signing requests

Document transactions can be retrieved in a similar way to the Authentication Transactions using the requestDocumentsTransaction() API call.

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
         }, onNoConnection: {
             // Handle no connection Error
         }, onInvalidUserStateError: { (error) in
             // Handle incorrect user state
         }, onInvalidToken: { (error) in
             // Handle invalid token error
         }, onUserLockedError: { (error) in
             // Handle locked user error
         }, onClientError: { (error) in
             // Handle client error
     })

ObjC

     [biidCoreSDK.getClient requestDocumentForDocumentID:documentID
         onSuccess:^(Document * _Nonnull document) {
             // Do something with the document
         }
         onNoConnection:^void() {
             // Handle no connection Error
         }
         onInvalidUserStateError:^void(NSError * _Nonnull error) {
             // Handle incorrect user state
         }
         onInvalidToken:^void(NSError * _Nonnull error) {
             // Handle invalid token error
         }
         onUserLockedError:^void(NSError * _Nonnull error) {
             // Handle locked user 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: { (url) in
             // Do something with the downloaded content
         }, onNoConnection: {
             // Handle no connection Error
         }, onInvalidUserStateError: { (error) in
             // Handle incorrect user state
         }, onInvalidToken: { (error) in
             // Handle invalid token error
         }, onUserLockedError: { (error) in
             // Handle locked user error
         }, onClientError: { (error) in
             // Handle client error
     })

ObjC

     [biidCoreSDK.getClient requestDocumentPreviewForDocument:document
         onSuccess:^(NSURL * _Nonnull url) {
             // Do something with the downloaded content
         }
         onNoConnection:^void() {
             // Handle no connection Error
         }
         onInvalidUserStateError:^void(NSError * _Nonnull error) {
             // Handle incorrect user state
         }
         onInvalidToken:^void(NSError * _Nonnull error) {
             // Handle invalid token error
         }
         onUserLockedError:^void(NSError * _Nonnull error) {
             // Handle locked user 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: { (url) in
             // Do something with the downloaded content
         }, onNoConnection: {
             // Handle no connection Error
         }, onInvalidUserStateError: { (error) in
             // Handle incorrect user state
         }, onInvalidToken: { (error) in
             // Handle invalid token error
         }, onUserLockedError: { (error) in
             // Handle locked user error
         }, onClientError: { (error) in
             // Handle client error
     })

ObjC

     [biidCoreSDK.getClient requestDocumentContentForDocument:document
         onSuccess:^(NSURL * _Nonnull url) {
             // Do something with the downloaded content
         }
         onNoConnection:^void() {
             // Handle no connection Error
         }
         onInvalidUserStateError:^void(NSError * _Nonnull error) {
             // Handle incorrect user state
         }
         onInvalidToken:^void(NSError * _Nonnull error) {
             // Handle invalid token error
         }
         onUserLockedError:^void(NSError * _Nonnull error) {
             // Handle locked user 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

            location = CLLocation(latitude: 51.509865, longitude: -0.118092) 
            SDK.getClient.signDocuments(forTransaction: transaction, withLocation: location,
                onSuccess: {
                    // Handle Document Signing success
                }, onNoConnection: {
                    // Handle no connection Error
                }, onInvalidUserStateError: { (error) in
                    // Handle incorrect user state
                }, onInvalidToken: { (error) in
                    // Handle invalid token error
                }, onTransactionNotPendingError: { (error) in
                    // Handle Transaction not pending error
                }, onUserLockedError: { (error) in
                    // Handle locked user error
                }, onClientError: { (error) in
                    // Handle client error
            })   

        }, onNoConnection: {
            // Handle no connection Error
        }, onInvalidUserStateError: { (error) in
            // Handle incorrect user state
        }, onInvalidToken: { (error) in
            // Handle invalid token error
        }, onUserLockedError: { (error) in
            // Handle locked user error
        }, onClientError: { (error) in
            // Handle client error
    })

ObjC

    [biidCoreSDK.getClient requestDocumentsTransactionWithID:transactionID
        onSuccess:^(AuthenticationTransaction * _Nonnull transaction) {

            CLLocation *location = [[CLLocation alloc] initWithLatitude:51.509865 longitude:-0.118092];
            [biidCoreSDK.getClient signDocuments:transaction withLocation:location
              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
       }
       onInvalidUserStateError:^void(NSError * _Nonnull error) {
           // Handle incorrect user state
       }
       onInvalidToken:^void(NSError * _Nonnull error) {
           // Handle invalid token error
       }
       onUserLockedError:^void(NSError * _Nonnull error) {
           // Handle locked user 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

    location = CLLocation(latitude: 51.509865, longitude: -0.118092) 
    SDK.getClient.rejectDocuments(forTransactionID: transactionID!, withLocation: location,
        onSuccess: {
            // Handle transaction rejection success
        }, onNoConnection: {
            // Handle no connection Error
        }, onInvalidUserStateError: { (error) in
            // Handle incorrect user state
        }, onInvalidToken: { (error) in
            // Handle invalid token error
        }, onTransactionNotPendingError: { (error) in
            // Handle Transaction not pending error
        }, onUserLockedError: { (error) in
            // Handle locked user error
        }, onClientError: { (error) in
            // Handle client error
    })

ObjC

      CLLocation *location = [[CLLocation alloc] initWithLatitude:51.509865 longitude:-0.118092];
     [biidCoreSDK.getClient rejectDocumentsTransactionWithID:transactionID  withLocation:location
         onSuccess:^{
             // Handle transaction rejection success
         }
         onNoConnection:^void() {
             // Handle no connection Error
         }
         onInvalidUserStateError:^void(NSError * _Nonnull error) {
             // Handle incorrect user state
         }
         onInvalidToken:^void(NSError * _Nonnull error) {
             // Handle invalid token error
         }
         onTransactionNotPendingError:^void(NSError * _Nonnull error) {
             // Handle Transaction not pending error
         }
         onUserLockedError:^void(NSError * _Nonnull error) {
             // Handle locked user 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

            location = CLLocation(latitude: 51.509865, longitude: -0.118092) 
            SDK.getClient.dismissMessage(forTransaction: transaction, withLocation: location,
                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
       }, onInvalidUserStateError: { (error) in
           // Handle incorrect user state
       }, onInvalidToken: { (error) in
           // Handle invalid token error
       }, onUserLockedError: { (error) in
          // Handle locked user error
       }, onClientError: { (error) in
          // Handle client error
   })```

> ObjC

```objective-c
     [biidCoreSDK.getClient requestMessageTransactionWithID:transactionID
        onSuccess:^(MessageTransaction * _Nonnull transaction) {

             CLLocation *location = [[CLLocation alloc] initWithLatitude:51.509865 longitude:-0.118092];
             [biidCoreSDK.getClient dismissMessageForTransaction:transaction withLocation:location
                 onSuccess:^{
                     // Handle Dismiss Message Success
                 }
                 onNoConnection:^void() {
                     // Handle no connection Error
                 }
                 onInvalidUserStateError:^void(NSError * _Nonnull error) {
                     // Handle incorrect user state
                 }
                 onInvalidToken:^void(NSError * _Nonnull error) {
                     // Handle invalid token error
                 }
                 onTransactionNotPendingError:^void(NSError * _Nonnull error) {
                     // Handle Transaction not pending error
                 }
                 onUserLockedError:^void(NSError * _Nonnull error) {
                     // Handle locked user error
                 }
                 onClientError:^void(NSError * _Nonnull error) {
                     // Handle client error
                 }
             ];

        }
       onNoConnection:^void() {
           // Handle no connection Error
       }
       onInvalidUserStateError:^void(NSError * _Nonnull error) {
           // Handle incorrect user state
       }
       onInvalidToken:^void(NSError * _Nonnull error) {
           // Handle invalid token error
       }
       onUserLockedError:^void(NSError * _Nonnull error) {
           // Handle locked user error
       }
       onClientError:^void(NSError * _Nonnull error) {
           // Handle client error
       }
     ];

Documentation and Documentation