---
title: "Creating Handover URLs"
slug: "creating-handover-urls"
updated: 2024-10-10T10:20:29Z
published: 2024-10-10T10:20:29Z
canonical: "docs.onespan.com/creating-handover-urls"
---

> ## Documentation Index
> Fetch the complete documentation index at: https://docs.onespan.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Creating Handover URLs

[Java SDK](/v1/docs/creating-handover-urls#java-sdk) [.NET SDK](/v1/docs/creating-handover-urls#net-sdk) [REST API](/v1/docs/creating-handover-urls#rest-api)

## Java SDK

A Handover URL is a redirect link pre-set in the transaction settings, which allows you to determine where the Signer Experience will be relocated after a recipient interacts with a transaction. The URL will be triggered differently in certain ways. The most common scenario is when a signer has completed signing. The Handover URL is displayed as an exit button on the global actions bar and on the tool bar.

Handover URLs can also be used as a web hook to send real-time messages to your endpoints about the triggered event. Once the signer hit the Handover URL link, additional parameters will be attached to the link, including “package”, “signer” and “status”.

For example, if you specified the Handover URL as:

```plaintext
https://yourdomain/oss/handover
```

After the recipient with signer ID of Signer1 has declined the transaction (ID of “T840KlFsIeC--LqGu9O9Enp9T6I”), information associated to this event will be passed by parameters, and the actual link the recipient will hit looks like this:

```plaintext
https://yourdomain/oss/handover?package=T840KlFsIeC--LqGu9O9Enp9T6I%3D&signer=Signer1&status=PACKAGE_DECLINE
```

Handover URLs can be defined at the following levels:

- Package
- Account
- Language

### By Package

To define a Handover URL at the package level there are three values you need to specify in the package settings:

- Handover Link Href: Defines the redirect URL to which the signer will be sent.
- Handover Link Text: The text that will appear on the handover button.
- Handover Link Title / Tooltip: The text that will appear when hovering over the handover button.

If you need a comparison to the basic object creation procedure, or if this is the first time creating a transaction, see [](https://developer.esignlive.com/guides/quick-start/creating-and-sending-a-package-net/)[Creating and Sending a Transaction](/v1/docs/creating-and-sending-a-transaction#net-sdk).

The following code shows you how to edit the settings block when creating a package.

```java
.withSettings(DocumentPackageSettingsBuilder.newDocumentPackageSettings()
			            .withHandOverLinkHref("https://www.google.com")
	          .withHandOverLinkText("Exit to site")
	    .withHandOverLinkTooltip("You will redirected to Google homepage")
              )
```

### By Account

As the Handover URL is a package setting, it is possible to set default Handover URL at the account level. If your work flow requires you to redirect the Signer Experience to a general completion page, or to your organization’s website, contact our [Support Team](https://www.onespan.com/support) and supply them with the following:

- Handover Link Href: Defines the redirect URL to which the signer will be sent.
- Handover Link Text: The text that will appear on the handover button.
- Handover Link Title / Tooltip: The text that will appear when hovering over the handover button.

Once this is done any new package that you create will have these default values.

### By Language

Different Handover URLs can be specified for different languages. For example, if you have a multilingual site and want to navigate the signer to different language versions according to the signer's language. To do this, you can contact our [Support Team](https://www.onespan.com/support) and have different Handover URLs configured on your account.

You can also customize Handover URLs using SDKs. The following code sample demonstrates how to leverage the AccountConfigService class to specify the Handover URL for each Java Locale.

```java
AccountConfigService accountConfigService = eslClient.getAccountConfigService();
				Handover handoverAfterCreating = accountConfigService.createHandoverUrl(HandoverBuilder
				.newHandover(java.util.Locale.ENGLISH)
				.withHref("https://www.google.com ")
				.withText("Exit to site ")
				.withTitle("You will redirected to Google homepage ")
				.build()
			);
```

#### Finding an existing language configuration

If you want to know if there’s any existing configurations defined for a language, use the following code:

```java
Handover handoverExisting = accountConfigService.getHandoverUrl(java.util.Locale.ENGLISH);
```

#### Updating an existing language configuration

To update an existing language configuration, use the .updateHandoverUrl() function:

```java
Handover  handoverAfterUpdating = accountConfigService.updateHandoverUrl(HandoverBuilder
				.newHandover(java.util.Locale.ENGLISH)
				.withTitle(“The updated tooltip”)   
				.build()
				);;
```

#### Deleting an existing language configuration

To delete a Handover URL setting use the following code:

```java
accountConfigService.deleteHandoverUrl(java.util.Locale.ENGLISH);
```

## .NET SDK

A Handover URL is a redirect link pre-set in the transaction settings, which allows you to determine where the Signer Experience will be relocated after a recipient interacts with a transaction. The URL will be triggered differently in certain ways. The most common scenario is when a signer has completed signing. The Handover URL is displayed as an exit button on the global actions bar and on the tool bar.

Handover URLs can also be used as a web hook to send real-time messages to your endpoints about the triggered event. Once the signer hit the Handover URL link, additional parameters will be attached to the link, including “package”, “signer” and “status”.

For example, if you specified the Handover URL as:

```plaintext
https://yourdomain/oss/handover
```

After the recipient with signer ID of Signer1 has declined the transaction (ID of “T840KlFsIeC--LqGu9O9Enp9T6I”), information associated to this event will be passed by parameters, and the actual link the recipient will hit looks like:

```plaintext
https://yourdomain/oss/handover?package=T840KlFsIeC--LqGu9O9Enp9T6I%3D&signer=Signer1&status=PACKAGE_DECLINE
```

Handover URLs can be defined at the following levels:

- Package
- Account
- Language

### By Package

To define a Handover URL at the package level there are three values you need to specify in the package settings:

- Handover Link Href: Defines the redirect URL to which the signer will be sent.
- Handover Link Text: The text that will appear on the handover button.
- Handover Link Title / Tooltip: The text that will appear when hovering over the handover button.

If you need a comparison to the basic object creation procedure, or if this is the first time creating a transaction, see [](https://developer.esignlive.com/guides/quick-start/creating-and-sending-a-package-net/)[Creating and Sending a Transaction](/v1/docs/creating-and-sending-a-transaction#net-sdk).

The following code shows you how to edit the settings block when creating a package.

```csharp
.withSettings(DocumentPackageSettingsBuilder.newDocumentPackageSettings()
				.withHandOverLinkHref("https://www.google.com")
				.withHandOverLinkText("Exit to site")
			.withHandOverLinkTooltip("You will redirected to Google homepage")
              )
```

### By Account

As the Handover URL is a package setting, it is possible to set default Handover URL at the account level. If your work flow requires you to redirect the Signer Experience to a general completion page, or to your organization’s website, contact our [Support Team](https://www.onespan.com/support) and supply them with the following:

- Handover Link Href: Defines the redirect URL to which the signer will be sent.
- Handover Link Text: The text that will appear on the handover button.
- Handover Link Title / Tooltip: The text that will appear when hovering over the handover button.

### By Language

Different Handover URLs can be specified for different languages. For example, if you have a multilingual site and want to navigate the signer to different language versions according to the signer's language. To do this, you can contact our [Support Team](https://www.onespan.com/support) and have different Handover URLs configured on your account.

You can also customize Handover URLs using SDKs. The following code sample demonstrates how to leverage the AccountConfigService class to specify the Handover URL for each Java Locale.

```csharp
AccountConfigService accountConfigService = eslClient.getAccountConfigService();
				Handover handoverAfterCreating = accountConfigService.createHandoverUrl(HandoverBuilder
				.newHandover(java.util.Locale.ENGLISH)
				.withHref("https://www.google.com ")
				.withText("Exit to site ")
				.withTitle("You will redirected to Google homepage ")
				.build()
			);
```

#### Finding an existing language configuration

If you want to know if there’s any existing configurations defined for a language, use the following code:

```csharp
Handover handoverExisting = accountConfigService.GetHandoverUrl(“en”);
```

#### Updating an existing language configuration

To update an existing language configuration, use the .updateHandoverUrl() function:

```csharp
Handover  handoverAfterUpdating = accountConfigService.updateHandoverUrl(HandoverBuilder
				.newHandover(java.util.Locale.ENGLISH)
				.withTitle(“The updated tooltip”)   
				.build()
			);
```

#### Deleting an existing language configuration

To delete a Handover URL setting use the following code:

```csharp
accountConfigService.deleteHandoverUrl(java.util.Locale.ENGLISH);
```

## REST API

A Handover URL is a redirect link pre-set in the transaction settings, which allows you to determine where the Signer Experience will be relocated after a recipient interacts with a transaction. The URL will be triggered differently in certain ways. The most common scenario is when a signer has completed signing. The Handover URL is displayed as an exit button on the global actions bar and on the tool bar.

Handover URLs can also be used as a web hook to send real-time messages to your endpoints about the triggered event. Once the signer hit the Handover URL link, additional parameters will be attached to the link, including “package”, “signer” and “status”.

For example, if you specified the Handover URL as:

```plaintext
https://yourdomain/oss/handover
```

After the recipient with signer ID of Signer1 has declined the transaction (ID of “T840KlFsIeC--LqGu9O9Enp9T6I”), information associated to this event will be passed by parameters, and the actual link the recipient will hit looks like:

```plaintext
https://yourdomain/oss/handover?package=T840KlFsIeC--LqGu9O9Enp9T6I%3D&signer=Signer1&status=PACKAGE_DECLINE
```

Handover URLs can be defined at the following levels:

- Package
- Account
- Language

### By Package

To define a Handover URL at the package level there are three values you need to specify in the package settings:

- Handover Link Href: Defines the redirect URL to which the signer will be sent.
- Handover Link Text: The text that will appear on the handover button.
- Handover Link Title / Tooltip: The text that will appear when hovering over the handover button.

If you need a comparison to the basic object creation procedure, or if this is the first time creating a transaction, see [](https://developer.esignlive.com/guides/quick-start/creating-and-sending-a-package-net/)[Creating and Sending a Transaction](/v1/docs/creating-and-sending-a-transaction#net-sdk).

These attributes are hosted in the package JSON at “settings” > “ceremony” > “handOver”. The following codegives you an idea how you can build the “settings” node and include the handover URL information when creating a package:

```json
{
				"status": "DRAFT",
				"settings": {
				"ceremony": {
				  "handOver": {
				        "title": "You will be redirected to Google homepage",
			        	"href": "http://www.google.com",
				        "text": "Exit to site"
				}
				    }
			},
			"type": "PACKAGE",
			"name": "Customized Signer Experience"
	}
```

### By Account

As the Handover URL is a package setting, it is possible to set default Handover URL at the account level. If your work flow requires you to redirect the Signer Experience to a general completion page, or to your organization’s website, contact our [Support Team](https://www.onespan.com/support) and supply them with the following:

- Handover Link Href: Defines the redirect URL to which the signer will be sent.
- Handover Link Text: The text that will appear on the handover button.
- Handover Link Title / Tooltip: The text that will appear when hovering over the handover button.

### By Language

Different Handover URLs can be specified for different languages. For example, if you have a multilingual site and want to navigate the signer to different language versions according to the signer's language. To do this, you can contact our [Support Team](https://www.onespan.com/support) and have different Handover URLs configured on your account.

You can also customize Handover URLs using REST APIs.

To create a Handover URL setting, use the following API.

#### HTTP Request

```http
POST /api/accountConfig/handoverUrl/{language_code}
```

#### HTTP Headers

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

#### Request Payload

```json
{
            "title": "You will be redirected to Google homepage",
            "href": "http://www.google.com",
            "text": "Exit to site"
              
```

#### Finding an existing language configuration

If you want to know if there’s any existing configurations defined for a language, use the following code:

**HTTP Request**

```http
GET /api/accountConfig/handoverUrl/{language_code}
```

**HTTP Headers**

```http
Accept: application/json 
Authorization: Basic api_key
```

**Response Payload**

```json
{
              "title": "You will be redirected to Google homepage",
              "href": "http://www.google.com",
            "text": "Exit to site"
}  
```

#### Updating an existing language configuration

Once you’ve created a setting, you can use the API below to update any partial attributes:

**HTTP Request**

```http
PUT /api/accountConfig/handoverUrl/{language_code}
```

**HTTP Headers**

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

**Request Payload**

```json
{
   "title": "You will be redirected to Google homepage"
   }  
```

#### Deleting an existing language configuration

To delete a Handover URL setting use the following code:

**HTTP Request**

```http
DELETE /api/accountConfig/handoverUrl/{language_code}
```

**HTTP Headers**

```http
Authorization: Basic api_key
```