# Transaction Signing with Mobile PIN

div
div
Client SDK
div
Mobile approve
div
SSO
div
Sub-journey
> Prompts the user to approve a financial transaction using an app-specific PIN code.


## About client-facing steps

A journey is a sequence of steps that are executed when it's invoked by a client application (known as the "client"). Some steps require involvement from the client, such as to collect user input. Other steps, like validating a token, are executed in the backend by the Mosaic journey engine alone.

When invoked, the journey begins executing the steps while the client waits for further instructions. When a journey reaches a client-facing step, the journey asks the client for the required input and then waits for the client to respond. The client presents their own UI if user interaction is required, and returns input to the journey. The journey then proceeds in a similar manner until it's completed.

## Description

This step enables users to approve financial transactions by signing them with their app-specific PIN code. The PIN-based credentials must be pre-registered using the [Register Mobile PIN](/guides/orchestration/journeys/register_mobile_pin) step.

Use cases include:

- Approving financial transactions (e.g., payments, money transfers).
- Authorizing sensitive actions that require explicit user consent.
- Strengthening security while preserving a seamless user experience.


The signing process starts when the client initiates the journey by sending `approvalData`, a flat JSON object with transaction details such as amount, recipient, and currency.

When the journey reaches the **Transaction Signing with Mobile PIN** step, the client displays the approval data and prompts the user for their PIN. The client uses the [Authentication SDK for iOS](https://transmitsecurity.github.io/authentication-ios-sdk-docs/documentation/tsauthenticationsdk/) or [Authentication SDK for Android](https://transmitsecurity.github.io/authentication-android-docs/) to approve the transaction, then sends the result to the journey using the [Orchestration SDK for iOS](https://transmitsecurity.github.io/identityOrchestration-ios-sdk-docs/documentation/identityorchestration/tsido/submitclientresponse(clientresponseoptionid:data:)) or [Orchestration SDK for Android](https://transmitsecurity.github.io/ido-android-api-reference/-identity%20-orchestration%20-s-d-k/com.transmit.idosdk/-t-s-ido/submit-client-response.html). The private key remains protected on the device.

On successful authentication:

- Mosaic validates the approval.
- Authentication tokens (ID or access tokens) are issued with `approvalData` embedded in their claims.
- The configured output variable stores the transaction-signing result, including `signing_artifacts` (approval data, challenge, signature, public key, and signing algorithm) and `authenticator_id`. See [Offline transaction signing verification](/guides/user/transaction_signing_offline_verification) for the full list of fields and how they support verification outside Mosaic.
- The journey advances to the next step.


On authentication failure (e.g., incorrect PIN, timeout):

- The journey either redirects to a failure branch or terminates, based on configuration.
- The client may provide fallback options, such as retrying or using an alternative authentication method.


To support transaction signing with mobile PIN, you'll need to:

- Implement PIN registration, as described in [Register Mobile PIN](/guides/orchestration/journeys/register_mobile_pin#example).
- Call the [Authentication SDK for iOS](https://transmitsecurity.github.io/authentication-ios-sdk-docs/documentation/tsauthenticationsdk/) or [Authentication SDK for Android](https://transmitsecurity.github.io/authentication-android-docs/) to sign the transaction with the user's PIN.
- Use the [Orchestration SDK for iOS](https://transmitsecurity.github.io/identityOrchestration-ios-sdk-docs/documentation/identityorchestration/tsido/submitclientresponse(clientresponseoptionid:data:)) or [Orchestration SDK for Android](https://transmitsecurity.github.io/ido-android-api-reference/-identity%20-orchestration%20-s-d-k/com.transmit.idosdk/-t-s-ido/submit-client-response.html) to submit the signed result to the journey.


Note
For Android, the Authentication SDK requires `compileSdk` 34 (or greater) and `minSdk` 23.

## Configuration

div
| Field | Description |
|  --- | --- |
| **Identifiers** | An identifier used to locate the user. Can be an external user ID, email, phone number, username, or a [custom identifier](/guides/user/manage_user_schema), if configured for B2C users in your tenant. |
| **Device** | Specifies the device to use for Mobile PIN transaction signing. Select **Derived from Journey Context** (default) to use the device identified earlier in the journey. Select **Set Manually** to provide the device ID for this step. |
| **Device ID** | Device ID to use when **Set Manually** is selected. You can provide an expression. |
| **Approval data** | A JSON object containing a flat list of up to 10-string properties used to derive the PIN challenge. Each value must be a string. Allowed characters: alphanumeric, spaces, and the special characters `.` , `_` and `-`. This object is dynamically generated based on transaction details, such as amount, currency, and transaction ID. |
| **Output variable** | Name of the variable that stores the Mobile PIN transaction-signing result, including `signing_artifacts` and `authenticator_id`. |
| **Error Output Variable** | Name of the variable that stores any errors returned by action. |
| **Failure Behavior** | Determines the behavior in case of failure, which either aborts the journey or proceeds to a failure branch of the control flow (default). |
| **Custom Branches** | Additional journey branches supported for this step. The client can select a branch by returning the branch ID. For each branch, you can define a schema for the information that the client is expected to return (used by the code generator and for autocompleting journey expressions) and a display name to label it in the editor. |
| **Branch Output Variable** | Name of the variable used to store the data returned by the client, which can be used in subsequent journey steps. |
| **Cancel Behavior** | Determines the behavior of client cancellation, which either aborts the journey (default) or proceeds to a cancel branch of the control flow. |


Journey event data
This step can be configured to record step input and output data, or a custom payload, which is then surfaced in journey events in Journey Analytics for diagnostic purposes. For details, see [Additional data reporting](/guides/orchestration/getting-started/event_reporting).

## Example

A user of a mobile banking application needs to approve a payment transaction of **$1,000 to "Merchant A"**. The app displays the transaction details—amount, recipient, and currency—to the user for confirmation, which the user digitally signs by **entering their app-specific PIN code**.

To do so, the client initiates the transaction signing journey by sending `approvalData` to Mosaic. The `approvalData` is a JSON object containing the transaction details. For example:

```json
{
  "amount": "1000",
  "currency": "USD",
  "recipient": "Merchant A",
  "transaction_id": "txn_12345"
}
```

When the journey reaches the **Transaction Signing with Mobile PIN** step, the client receives the approval data to display. After the user approves the transaction with their PIN, the journey continues according to its configured success or failure path. Configure an output variable if you need to retain the signing artifacts for later use.