Managing Transactions

10 Oct 2024
8 Minutes to read

Share
Dark
Light
PDF

Managing Transactions

Updated on 10 Oct 2024
8 Minutes to read

Share
Dark
Light
PDF

Article summary

Did you find this summary helpful?

Thank you for your feedback

Java SDK .NET SDK REST API APEX SDK

Java SDK

To download the full code sample see our Code Share site.

This topic describes how to retrieve, update, archive, and delete a transaction.

Retrieving Transactions

To retrieve a transaction, you will first need to create a PackageId object using the ID returned to you during the creation of the transaction. Then, retrieve the transaction using this PackageId in the OneSpan Sign client. The following code will do this:

 PackageId packageId = new PackageId("package_id_here");   DocumentPackage retrievedPkg = eslClient.getPackage(packageId);

You can also retrieve a list of transactions. The following code will do this:

 Page<DocumentPackage> resultPage = eslClient.getPackageService().getPackages( new PackageStatusConverter(PackageStatus.SENT).toAPIPackageStatus(), new PageRequest(1, 10));

The code example above will return the first ten transactions that are in a SENT status. You can, however, query other statuses, such as DRAFT, COMPLETED, DECLINED, EXPIRED, and ARCHIVED.

Updating a Transaction

To update a transaction, the transaction must be in a DRAFT status.

To update an existing transaction, create a transaction object with only the updates you want to make to the transaction. Then, call the UpdatePackage function with the PackageId of the existing transaction. The following code will do this:

 DocumentPackage packageToUpdate = PackageBuilder.newPackageNamed(NEW_PACKAGE_NAME)   .describedAs(NEW_DESCRIPTION)   .withEmailMessage(NEW_EMAIL_MESSAGE)   .expiresAt(LocalDateTime.now().toDate())   .withLanguage(Locale.FRENCH)   .withVisibility(NEW_VISIBILITY)   .withNotarized(NEW_NOTARIZED)   .autocomplete(false)   .withSettings(settingsToUpdate)   .build();   eslClient.updatePackage(packageId, packageToUpdate);

Deleting Transactions

If you want to permanently remove a transaction from your account, call the deletePackage function using the PackageId of the transaction you wish to delete.

Deleting a transaction cannot be undone.

The following code will do this:

 eslClient.getPackageService().deletePackage(packageId);

If you do not want to permanently delete this transaction, you can instead move it to your Trash folder. This way it will not be deleted and can be retrieved at a later date. The following code will do this:

 eslClient.getPackageService().trash(packageId);

Archiving Transactions

The Archive action moves the selected transactions from your Inbox to the Archived folder containing all your archived transactions. This action is available only for COMPLETED transactions in your Inbox.

To do this, call on the OneSpan Sign client with the PackageId of the transaction you wish to archive. The following code will do this:

 eslClient.getPackageService().archive(new PackageId("packageId"));

.NET SDK

To download the full code sample see our Code Share site.

This topic describes how to retrieve, update, archive, and delete a transaction.

Retrieving Transactions

 PackageId packageId = new PackageId("package_id_here");   DocumentPackage retrievedPkg = eslClient.GetPackage(packageId);

You can also retrieve a list of transactions. The following code will do this:

 Page<DocumentPackage> packages = eslClient.PackageService.GetPackages (DocumentPackageStatus.SENT, new PageRequest(1, 10));

The code example above will return the first ten transactions that are in a SENT status. You can, however, query other statuses, such as DRAFT, COMPLETED, DECLINED, EXPIRED, and ARCHIVED.

Updating a Transaction

 DocumentPackage packageToUpdate = PackageBuilder.NewPackageNamed(NEW_PACKAGE_NAME)   .WithEmailMessage(NEW_EMAIL_MESSAGE)   .ExpiresOn(NEW_EXPIRY_DATE)   .WithLanguage(NEW_LANGUAGE)   .WithVisibility(NEW_VISIBILITY)   .WithNotarized(NEW_NOTARIZED)   .WithoutAutomaticCompletion()   .WithSettings(settingsToUpdate)   .Build();   eslClient.UpdatePackage(packageId, packageToUpdate);

Deleting Transactions

If you want to permanently remove a transaction from your account, call the deletePackage function using the PackageId of the transaction you wish to delete.

Deleting a transaction cannot be undone.

The following code will do this:

 eslClient.PackageService.DeletePackage(packageId);

 eslClient.PackageService.Trash(packageId);

Archiving Transactions

To do this, call on the OneSpan Sign client with the PackageId of the transaction you wish to archive. The following code will do this:

 eslClient.PackageService.Archive(new PackageId("packageId"));

REST API

To download the full code sample see our Code Share site.

This topic describes how to retrieve, update, archive, and delete a transaction.

Retrieving Transactions

To retrieve a package (GET), update (PUT), or delete a package (DELETE), you will need to make your request to the following URL using the PackageId returned to you during the creation of the transaction. The following code will do this:

 {instance_url}/api/packages/{packageId}

You can also retrieve a list of transactions. The following code will do this:

HTTP Request

GET /api/packages?from=1&to=5&query=SENT

HTTP Headers

Accept: application/json   
Content-Type: application/json   
Authorization: Basic api_key

Response Payload

 {   "results": [   {...},   {...},   {...},   {...},   {...}   ],   "count": 30   }

For a complete description of each field, see the Request Payload table below.

The code example above will return the first five transactions that are in a SENT status, out of a total count of 30. You can, however, query other statuses, such as DRAFT, COMPLETED, DECLINED, EXPIRED, and ARCHIVED.

Updating a Transaction

To update an existing package that is in DRAFT status, simply create a payload with only the updates you want to make to the package and make your PUT request:

HTTP Request

PUT /api/packages/{packageId}

HTTP Headers

Accept: application/json   
Content-Type: application/json   
Authorization: Basic api_key

Request Payload

{
	"due": "2017-02-13T21:18:40Z",
	"emailMessage": "new email message",
	"notarized": true,
	"settings": { ...
	},
	"description": "",
	"autocomplete": false,
	"visibility": "ACCOUNT",
	"status": "DRAFT",
	"type": "PACKAGE",
	"roles": [{
		"reassign": false,
		"locked": false,
		"index": 0,
		"type": "SENDER",
		"signers": [{
			"title": null,
			"address": null,
			"phone": "",
			"firstName": "Haris",
			"lastName": "Haidary",
			"email": "signer1@example.com",
			"company": "Onespan",
			"language": "fr",
			"name": ""
		}],
		"name": "Owner"
	}],
	"language": "fr",
	"name": "new package name",
	"bulkSendable": false
}

Deleting Transactions

Deleting a transaction cannot be undone.

If you want to permanently remove a transaction from your account, simply make a DELETE request using the PackageId of the transaction you wish to delete.

If you do not want to permanently delete this transaction, you can instead move it to your Trash folder. This way it will not be deleted and can be retrieved at a later date. To do this, make a PUT request with the following payload:

HTTP Request

PUT /api/packages/{packageId}

HTTP Headers

Accept: application/json   
Content-Type: application/json   
Authorization: Basic api_key

Request Payload

 {   "trashed": true   }

Archiving Transactions

To archive a package, simply update the status of the package to ARCHIVED:

HTTP Request

PUT /api/packages/{packageId}

HTTP Headers

Accept: application/json   
Content-Type: application/json   
Authorization: Basic api_key

Request Payload

 {   "status": "ARCHIVED"   }

Request Payload Table

Property	Type	Editable	Required	Default	Sample Values
status	string	Yes	No	DRAFT	DRAFT / SENT / COMPLETED / ARCHIVED / DECLINED / EXPIRED
due	string	Yes	Yes	null	2017-02-13T21:18:40Z
emailMessage	string	Yes	Yes	null	new email message
notarized	boolean	Yes	Yes	false	true / false
description	string	Yes	Yes	null	Sample transaction from STU BANK
autoComplete	boolean	Yes	No	true	true / false
type	string	Yes	No	PACKAGE	PACKAGE / TEMPLATE / LAYOUT
name	string	Yes	Yes	n/a	Document Attributes Example
trashed	boolean	Yes	No	false	true / false
language	string	Yes	Yes	en	en / fr / es ...
visibility	string	Yes	No	ACCOUNT	ACCOUNT / SENDER
bulkSendable	boolean	Yes	No	false	false / true
roles
id	string	Yes	No	n/a	Client1
index	integer	Yes	No	0	0 / 1 / 2 ...
reassign	boolean	Yes	No	false	false / true
locked	boolean	Yes	No	false	false / true
name	string	Yes	No	n/a	Client1
type	string	Yes	No	SIGNER	SIGNER / SENDER
signers
email	string	Yes	Yes	n/a	preparer.email@example.com
firstName	string	Yes	Yes	n/a	John
lastName	string	Yes	Yes	n/a	Smith
phone	string	Yes	No	n/a	514-555-8888
id	string	Yes	No	n/a	Client1
company	string	Yes	No	n/a	Acme Inc.
address	string	Yes	No	n/a	123 Main St.
title	string	Yes	No	n/a	Managing Director
settings
ceremony
inPerson	boolean	Yes	No	false	false / true
declineButton	boolean	Yes	No	true	false / true
declineReasons	string	Yes	No	n/a	new decline reason #1
optOutReasons	string	Yes	No	n/a	new opt-out reason #1 Note: The opt-out option is no longer available in the Signer Experience.
disableDeclineOther	boolean	Yes	No	false	false / true
disableDownloadForUncompletedPackage	boolean	Yes	No	false	false / true
disableFirstInPersonAffidavit	boolean	Yes	No	false	false / true
disableInPersonAffidavit	boolean	Yes	No	false	false / true
disableOptOutOther	boolean	Yes	No	false	false / true Note: The opt-out option is no longer available in the Signer Experience.
disableSecondInPersonAffidavit	boolean	Yes	No	false	false / true
hideCaptureText	boolean	Yes	No	false	false / true
hideLanguageDropdown	boolean	Yes	No	false	false / true
hidePackageOwnerInPerson	boolean	Yes	No	false	false / true
hideWatermark	boolean	Yes	No	false	false / true
maxAuthFailsAllowed	integer	Yes	No	3	1 / 2 / 3 ...
optOutButton	boolean	Yes	No	false	false / true Note: The opt-out option is no longer available in the Signer Experience.
layout
iframe	boolean	Yes	No	false	false / true
navigator	boolean	Yes	No	false	false / true
header
feedback	boolean	Yes	No	false	false / true
breadcrumbs	boolean	Yes	No	false	false / true
globalNavigation	boolean	Yes	No	false	false / true
sessionBar	boolean	Yes	No	false	false / true
titleBar
progressBar	boolean	Yes	No	false	false / true
titleBar	boolean	Yes	No	false	false / true
globalActions
confirm	boolean	Yes	No	false	false / true
download	boolean	Yes	No	false	false / true
hideEvidenceSummary	boolean	Yes	No	false	false / true
saveAsLayout	boolean	Yes	No	false	false / true
brandingBar
logo
src	string	Yes	No	null	new logo image source
link	string	Yes	No	null	new logo image link
events
complete
dialog	boolean	Yes	No	false	true / false
redirect	string	Yes	No	null	https://www.google.ca
handOver
href	string	Yes	No	null	http://www.new.ca
title	string	Yes	No	null	new hand over link tool tip
text	string	Yes	No	null	new hand over link text

APEX SDK

To download the full code sample see our Code Share site.

This topic describes how to retrieve, update, archive, and delete a transaction.

Retrieving Transactions

 //retrieve a package   ESignLiveSDK sdk = new ESignLiveSDK();   ESignLiveAPIObjects.Package_x pkg = sdk.getPackage(packageId);

You can also retrieve a list of transactions. The following code will do this:

 public List<ESignLiveAPIObjects.Package_x> getPackages(Map<String,String> queryParameters)

You can pass a map of query parameters in order to narrow your search like this:

 List<ESignLiveAPIObjects.Package_x> pkgs = getPackages(new Map<String,String>{'from'=>'0','to'=>'9','status'=>'SENT'});

The code example above will return the first ten transactions that are in a SENT status. You can, however, query other statuses, such as DRAFT, COMPLETED, DECLINED, EXPIRED, and ARCHIVED.

Updating a Transaction

To update an existing transaction, create a transaction object with only the updates you want to make to the transaction. Then, call the updatePackage() function with the PackageId of the existing transaction and the updates Package_x object. The following code will do this:

 //update package   ESignLiveAPIObjects.Package_x pkg = sdk.getPackage(packageId); //or   ESignLiveAPIObjects.Package_x pkg = new ESignLiveAPIObjects.Package_x();   pkg.name = 'changed package name';   sdk.updatePackage(pkg, packageId);

Deleting Transactions

If you want to permanently remove a transaction from your account, call the deletePackage () function using the PackageId of the transaction you wish to delete.

Deleting a transaction cannot be undone.

The following code will do this:

 //delete package   sdk.deletePackage(packageId);

 //trash package   ESignLiveAPIObjects.Package_x pkg = sdk.getPackage(packageId);   pkg.trashed = true;   sdk.updatePackage(pkg, packageId);

Archiving Transactions

To do this, call the setStatus() function with the PackageId of the transaction you wish to archive. The following code will do this:

 //archive package   sdk.setStatus(packageId, ESignLiveAPIObjects.PackageStatus.ARCHIVED);   //you can only archive completed packages   sdk.setStatus(packageId, ESignLiveAPIObjects.PackageStatus.COMPLETED); //restore archive

Was this article helpful?

What's Next

Virtual Room

Table of contents

Java SDK
.NET SDK
REST API
APEX SDK