Advanced Implementation

The following are optional implementation steps that can be taken to optimize the branding, streamline the end customer experience, and provide access to richer functionality.

Theming

To match your branding, you can customize colors, logos, fonts, etc. Refer to our theming guide.

The White-Label App can be styled by passing a theme object to the settings-json attribute.

You can also demo these changes using the branding page in your Sandbox Dashboard.

Pre filling end-user information

1-2 days

If you have access to end customer information that you can share in order to streamline their onboarding onto banking and can reduce the friction of submitting the application, we allow you to provide it and we will use it to pre-fill the end customer’s application form. To support that, you will have to expose an API endpoint that Unit will call when seeing an end user (identified by their JWT subject) for the first time.

Unit will make an HTTP request to this endpoint with a JWT token associated with this user in the Authorization header before initiating the end customer application process. The server will need to return the End User Configuration resource. The response must include the data, type: whiteLabelAppEndUserConfig and attributes keys.

Please contact Unit in order to configure the endpoint.

Request example:

curl -X GET 'https://yourdomain.com/unit/application-form-prefill' \
-H "Authorization: Bearer ${JWT Token}"

Inviting additional users to Banking

1-2 days

In order to allow more than one end user of yours access to the same banking experience (e.g. two employees of the same business, represented as two separate JWT subjects on your platform), The user that applies for banking, once approved, needs to be able to invite additional users.

Note this is only available for business customers.

Since Unit isn’t familiar with the relationship between users on your platform, we rely on you to tell us who the users are that another user may grant access to, by providing an API endpoint we can call, that returns a list of users, represented as JWTs.

Unit relies on you to manage and define user roles effectively. Below are the responsibilities and requirements for user management and role assignment within the Ready-to-Launch Banking App.

Role Assignment via JWT Token

Each user in Ready-to-Launch Banking has an assigned role, which your backend is responsible for managing. The end customer can create users in the White-Label App and assign roles to them. To update a user’s role, include the new role in a unitRole attribute in the JWT token. Unit validates the JWT token on a user login: if a role is provided in the token, Unit will update the user’s role in the White-Label App accordingly. If a role is not provided in the JWT token, Unit will retain the last role that was sent.

Allowed Roles

The only allowed roles are Admin and ReadOnly. If you include a role other than these in the JWT token, the request will fail.

Managing End Users

The White-Label App provides functionality for creating, removing, and listing users within the app. The customer can manage all types of users. Admin can only manage users who has ReadOnly permissions. To enable these capabilities, you will need to implement an API endpoint that returns a list of your app's existing end-users.

API Endpoint Requirements

Request: Unit will send an HTTP request to the API endpoint that you will implement, including a JWT token in the Authorization header.

curl -X GET 'https://yourdomain.com/unit/users' \
-H "Authorization: Bearer ${JWT Token}"

Response: The API must return a list of end-users associated with the customer resource created at Unit. Each end-user in the list should be represented as an object and include their unique JWT subject. By adhering to these guidelines, you will ensure consistent user role management within the White-Label App.

Field	Type	Description
`fullName`	FullName	Full name of the end user.
`email`	`string`	Email address of the end user.
`phone`	Phone	Phone number of the end user.
`jwtSubject`	`string`	Unique string identifying the end user.
`unitRole`	`string`	The role of the end user. Can be either `Admin` or `ReadOnly`.
`bankingPageURL`	`string`	Optional. URL to the banking page on the client’s website (For linking via email).

Example whiteLabelAppEndUser type:

[
  {
    "data": {
      "type": "whiteLabelAppEndUser",
      "attributes": {
        "fullName": {
          "first": "Peter",
          "last": "Parker"
        },
        "email": "peter.parker@parker.com",
        "phone": {
          "countryCode": "1",
          "number": "2345678888"
        },
        "jwtSubject": "test",
        "unitRole": "Admin"
      }
    }
  },
  {
    "data": {
      "type": "whiteLabelAppEndUser",
      "attributes": {
        "fullName": {
          "first": "April",
          "last": "Oneil"
        },
        "email": "april.oneil@parker.com",
        "phone": {
          "countryCode": "1",
          "number": "2345678899"
        },
        "jwtSubject": "test2",
        "unitRole": "ReadOnly"
      }
    }
  }
]

After the endpoint has been implemented on your side, please contact Unit in order to configure it.

Custom JWT Authentication

3-4 hours

Unit can rely on a custom implementation of JWT token that adheres to the specifications outlined in RFC 7519.

In this case you should provide Unit with a public key that will be used to validate the token.

The token must be signed using the RS256 algorithm and must include the following claims:

Claim	Description
`sub`	A unique identifier for the end-user
`exp`	The expiration time of the token
`iss`	The issuer of the token

JWT Authentication Troubleshooting:

If you receive an error, ensure the following:

You're using the Sandbox (ui.s.unit.sh) or Production (ui.unit.co) script matching your environment.
Decode your token. The iss matches the Issuer you configured in the Dashboard and the sub value is a string (stable user id). The token is still valid, with an exp in the future. The header includes alg: RS256 and a valid kid.
The Public Key was entered into the Unit Dashboard correctly, and is the correct one for the provided token. The kid in the JWT matches one in your uploaded Public Key or JWKs.
The cache has been cleared (localStorage keys unitCustomerToken and unitVerifiedCustomerToken).
The jwt-token value is present before the component initializes.

Webhook Events

2-3 hours

You may consume webhooks events to receive real-time notifications about your customers' activity on Ready to Launch Banking. Unit uses webhooks to notify your platform when an event occurs, such as when an application is denied, a customer is created, or a transaction is processed.

When one of these events occurs, an HTTP POST request is sent to your webhook's configured URL, allowing you to act upon it in real-time. This enables you to build responsive integrations, update your systems automatically, and provide better customer experiences.

Suggestion

Unit highly recommends that you make your webhook handlers Idempotent, to ensure events are only handled once on your end.

Setting Up Webhooks

To start receiving webhook events, you'll need to:

Implement an endpoint on your server to receive and process webhook payloads
Configure a webhook subscription using one of the methods below:
- Sandbox Environment: Create your webhook subscription via the Unit Dashboard → DEVELOPER menu → Webhooks → Create
- Production Environment: Contact your Unit solution engineer to help set up webhook subscriptions
Verify webhook signatures to ensure security and authenticity (see Securing your webhooks)

Unit sends POST requests to your webhook's URL from one of the following IP addresses:

Environment	IP Addresses
Sandbox	`54.81.62.38` `35.169.213.205` `3.234.105.75`
Live	`3.209.193.26` `54.156.65.95` `54.165.224.37`

Please note that these IP addresses are subject to change.

Suggestion

On production, webhooks that were unresponsive for 7 days will change status to Unavailable and will cease to receive events until they are re-enabled.

On sandbox, webhooks that were unresponsive for 2 days will be changed to status Unavailable.

Available Webhook Events for RTL Banking

Ready-to-Launch Banking clients can subscribe to the following webhook events:

application.denied

Occurs when a banking application is rejected. The userIds refers to the user IDs in your system.

Example application.denied payload:
{
  "data": [
    {
      "id": "28",
      "type": "application.denied",
      "attributes": {
        "createdAt": "2020-07-29T12:53:05.882Z",
        "userIds": [
          "user_12345"
        ]
      }
    }
  ]
}

customer.created

Occurs when a new customer record is established after application approval. The userIds array contains the user IDs from your system.

Example customer.created payload:
{
  "data": [
    {
      "id": "53",
      "type": "customer.created",
      "attributes": {
        "createdAt": "2020-07-29T12:53:05.882Z",
        "name": "Acme Corp",
        "userIds": [
          "user_12345"
        ]
      },
      "relationships": {
        "customer": {
          "data": {
            "id": "10000",
            "type": "businessCustomer"
          }
        }
      }
    }
  ]
}

account.created

Occurs when a new deposit account is successfully created for a customer.

Example account.created payload:
{
  "data": [
    {
      "id": "269",
      "type": "account.created",
      "attributes": {
        "createdAt": "2021-04-13T07:40:43.813Z",
        "accountNumber": "1000000001",
        "routingNumber": "812345678"
      },
      "relationships": {
        "account": {
          "data": {
            "id": "10004",
            "type": "account"
          }
        },
        "customer": {
          "data": {
            "id": "10000",
            "type": "customer"
          }
        }
      }
    }
  ]
}

account.frozen

Occurs when account access is restricted.

Example account.frozen payload:
{
  "data": [
    {
      "id": "2354",
      "type": "account.frozen",
      "attributes": {
        "createdAt": "2021-12-08T07:43:13.813Z",
        "accountNumber": "1000000001",
        "routingNumber": "812345678"
      },
      "relationships": {
        "account": {
          "data": {
            "id": "10004",
            "type": "account"
          }
        },
        "customer": {
          "data": {
            "id": "10000",
            "type": "customer"
          }
        }
      }
    }
  ]
}

account.unfrozen

Occurs when account access is restored.

Example account.unfrozen payload:
{
  "data": [
    {
      "id": "2355",
      "type": "account.unfrozen",
      "attributes": {
        "createdAt": "2021-12-08T07:43:13.813Z",
        "accountNumber": "1000000001",
        "routingNumber": "812345678"
      },
      "relationships": {
        "account": {
          "data": {
            "id": "10004",
            "type": "account"
          }
        },
        "customer": {
          "data": {
            "id": "10000",
            "type": "customer"
          }
        }
      }
    }
  ]
}

account.closed

Occurs when an account is closed by the customer or Unit.

Example account.closed payload:
{
  "data": [
    {
      "id": "270",
      "type": "account.closed",
      "attributes": {
        "createdAt": "2021-04-13T07:40:43.813Z",
        "accountNumber": "1000000001",
        "routingNumber": "812345678"
      },
      "relationships": {
        "account": {
          "data": {
            "id": "10004",
            "type": "account"
          }
        },
        "customer": {
          "data": {
            "id": "10000",
            "type": "customer"
          }
        }
      }
    }
  ]
}

account.reopened

Occurs when a previously closed account is reopened.

Example account.reopened payload:
{
  "data": [
    {
      "id": "271",
      "type": "account.reopened",
      "attributes": {
        "createdAt": "2021-04-13T07:40:43.813Z",
        "accountNumber": "1000000001",
        "routingNumber": "812345678"
      },
      "relationships": {
        "account": {
          "data": {
            "id": "10004",
            "type": "account"
          }
        },
        "customer": {
          "data": {
            "id": "10000",
            "type": "customer"
          }
        }
      }
    }
  ]
}

Suggestion

Enhanced Information Security documentation is required to access transaction webhooks. Contact your Customer Success Manager for more information about accessing transaction.

transaction.created

Occurs for all account transactions (deposits, withdrawals, transfers). The amount and balance are in cents.

Example transaction.created payload:
{
  "data": [
    {
      "id": "12345",
      "type": "transaction.created",
      "attributes": {
        "createdAt": "2021-06-02T10:15:22.123Z",
        "amount": 50000,
        "direction": "Credit",
        "type": "ACH",
        "balance": 150000
      },
      "relationships": {
        "account": {
          "data": {
            "id": "10004",
            "type": "account"
          }
        },
        "customer": {
          "data": {
            "id": "10000",
            "type": "customer"
          }
        }
      }
    }
  ]
}

API Calls

Ready-to-Launch Banking provides several API endpoints to help you manage accounts, transactions, and payments.

Note

To be able to use the api, you'll first need to Create an API token for Ready-to-Launch APIs by contacting your Unit solution engineer to help set up an API token for both Sandbox and Production environments.

Here are the available endpoints:

Get Account

Get a specific account by its ID.

Verb	`GET`
URL	`https://api.s.unit.sh/ready-to-launch/accounts/:accountId`
Required Scope	`accounts`
Timeout (Seconds)	`5`

curl -X GET 'https://api.s.unit.sh/ready-to-launch/accounts/42' \
-H "Authorization: Bearer ${TOKEN}"

Response

Returns account details including routing number, account number, status, and current balance (in cents).

Response is a JSON:API document.

200 OK

Field	Type	Description
id	string	Identifier of the account resource.
type	string	Type of the account resource. Always `account`.
attributes	JSON Object	JSON object representing the account data.

Attributes

Field	Type	Description
id	string	The unique identifier of the account.
routingNumber	string	The routing number of the account.
accountNumber	string	The account number.
status	string	The status of the account (`Open`, `Frozen`, or `Closed`).
balance	integer	The current balance in cents.
userIds	array	List of user IDs associated with this account.

Response
{
  "data": {
    "type": "account",
    "id": "10004",
    "attributes": {
      "routingNumber": "812345678",
      "accountNumber": "1000000001",
      "status": "Open",
      "balance": 150000,
      "userIds": [
        "user_12345",
        "user_67890"
      ]
    }
  }
}

List Accounts

List deposit accounts.

Verb	`GET`
URL	`https://api.s.unit.sh/ready-to-launch/accounts`
Required Scope	`accounts`
Timeout (Seconds)	`5`

Query Parameters

Name	Type	Default	Description
filter[customerId]	string	(empty)	Filter accounts by customer ID. Required if userId not provided.
filter[userId]	string	(empty)	Filter accounts by user ID. Required if customerId not provided.
page[limit]	integer	100	Optional. Maximum number of resources to return. Maximum is 10000 resources.
page[offset]	integer	0	Optional. Number of resources to skip. See Pagination.

Note

At least one of filter[customerId] or filter[userId] must be provided.

curl -X GET 'https://api.s.unit.sh/ready-to-launch/accounts?filter[customerId]=10000' \
-H "Authorization: Bearer ${TOKEN}"

Response

Returns a paginated list of deposit accounts with their details.

Response is a JSON:API document.

200 OK

Field	Type	Description
data	Array of accounts	Array of account resources.

Response
{
  "data": [
    {
      "type": "account",
      "id": "10020",
      "attributes": {
        "routingNumber": "406735154",
        "accountNumber": "864800000014",
        "status": "Open",
        "balance": 6000,
        "userIds": [
          "user_12345"
        ]
      }
    }
  ],
  "meta": {
    "pagination": {
      "total": 1,
      "limit": 100,
      "offset": 0
    }
  }
}

List Customers

Get a list of customers.

Verb	`GET`
URL	`https://api.s.unit.sh/ready-to-launch/customers`
Required Scope	`customers`
Timeout (Seconds)	`5`

Query Parameters

Name	Type	Default	Description
filter[customerId]	string	(empty)	Optional. Filter customers by customer ID.
filter[userId]	string	(empty)	Optional. Filter customers by user ID.

curl -X GET 'https://api.s.unit.sh/ready-to-launch/customers' \
-H "Authorization: Bearer ${TOKEN}"

Response

Returns a list of customers with their details.

Response is a JSON:API document.

200 OK

Field	Type	Description
data	Array of customers	Array of customer resources.

Attributes

Field	Type	Description
userIds	array	List of user IDs associated with this customer.

Response
{
  "data": [
    {
      "type": "customer",
      "id": "10014",
      "attributes": {
        "userIds": [
          "user_12345",
          "user_67890"
        ]
      }
    },
    {
      "type": "customer",
      "id": "10016",
      "attributes": {
        "userIds": [
          "user_11111"
        ]
      }
    }
  ]
}

Get Transaction

Get a transaction by transaction id and account id.

Verb	`GET`
URL	`https://api.s.unit.sh/ready-to-launch/accounts/:accountId/transactions/:transactionId`
Required Scope	`transactions`
Timeout (Seconds)	`5`

curl -X GET 'https://api.s.unit.sh/ready-to-launch/accounts/12345/transactions/12345' \
-H "Authorization: Bearer ${TOKEN}"

Response

Returns the transaction details. Amounts and balances are in cents.

Response is a JSON:API document.

200 OK

Field	Type	Description
id	string	Identifier of the transaction resource.
type	string	Type of the transaction resource. The value is always `transaction`.
attributes	JSON Object	JSON object representing the transaction data.
relationships	JSON:API Relationships	Describes relationships between the transaction resource and other resources.

Attributes

Field	Type	Description
createdAt	string	The date the transaction was created. Common to all transaction types.
direction	string	The direction in which the funds flow. Common to all transaction types.
amount	integer	The amount (cents) of the transaction. Common to all transaction types.
balance	integer	The account balance (cents) after the transaction. Common to all transaction types.
transactionType	string	The type of the transaction.
userIds	array	List of user IDs associated with this transaction.

Relationships

Name	Type	Description
account	JSON:API Relationship	The Deposit Account of the customer.
customer	Optional, JSON:API Relationship	The Customer the deposit account belongs to.
customers	Optional, Array of JSON:API Relationship	The list of Customers the deposit account belongs to.

Response
{
  "data": {
    "type": "transaction",
    "id": "12345",
    "attributes": {
      "amount": 50000,
      "direction": "Credit",
      "transactionType": "ACH",
      "createdAt": "2021-06-02T10:15:22.123Z",
      "balance": 150000,
      "userIds": [
        "user_12345"
      ]
    },
    "relationships": {
      "account": {
        "data": {
          "type": "account",
          "id": "10004"
        }
      },
      "customer": {
        "data": {
          "type": "customer",
          "id": "10000"
        }
      },
      "customers": {
        "data": [
          {
            "type": "customer",
            "id": "10000"
          }
        ]
      }
    }
  }
}

List Transactions

List transactions with optional filtering and pagination.

Verb	`GET`
URL	`https://api.s.unit.sh/ready-to-launch/transactions/`
Required Scope	`transactions`
Timeout (Seconds)	`5`

Query Parameters

Name	Type	Default	Description
filter[userId]	string	(empty)	Filter transactions by user ID. Required if customerId not provided.
filter[customerId]	string	(empty)	Filter transactions by customer ID. Required if userId not provided.
filter[since]	string	(empty)	Optional. Start date for filtering (ISO 8601).
filter[until]	string	(empty)	Optional. End date for filtering (ISO 8601).
page[limit]	integer	100	Optional. Maximum number of resources to return.
page[offset]	integer	0	Optional. Number of resources to skip.

Note

At least one of filter[customerId] or filter[userId] must be provided.

curl -X GET 'https://api.s.unit.sh/ready-to-launch/transactions' \
-H "Authorization: Bearer ${TOKEN}"

Response

Returns a paginated list of transactions with their details. Amounts and balances are in cents.

Response is a JSON:API document.

200 OK

Field	Type	Description
data	Array of transactions	Array of transaction resources.

Response
{
  "data": [
    {
      "type": "transaction",
      "id": "12345",
      "attributes": {
        "amount": 50000,
        "direction": "Credit",
        "transactionType": "ACH",
        "createdAt": "2021-06-02T10:15:22.123Z",
        "balance": 150000,
        "userIds": [
          "user_12345"
        ]
      },
      "relationships": {
        "account": {
          "data": {
            "type": "account",
            "id": "10004"
          }
        },
        "customer": {
          "data": {
            "type": "customer",
            "id": "10000"
          }
        },
        "customers": {
          "data": [
            {
              "type": "customer",
              "id": "10000"
            }
          ]
        }
      }
    }
  ],
  "meta": {
    "pagination": {
      "total": 1,
      "limit": 10,
      "offset": 0
    }
  }
}

Create Book Payment

Create a new book payment between accounts.

Verb	`POST`
URL	`https://api.s.unit.sh/ready-to-launch/book-payments`
Required Scope	`payments-write`
Data Type	`bookPayment`
Timeout (Seconds)	`5`

Attributes

Name	Type	Description
amount	integer	The amount (in cents).
description	string	Payment description (maximum of 80 characters), this will show up on statement of the counterparty.
tags	object	Optional. See Tags. Tags that will be copied to any transaction that this payment creates (see Tag Inheritance).
idempotencyKey	string	Optional. See Idempotency.

Relationships

Name	Type	Description
account	JSON:API Relationship	The Deposit Account originating the payment.
operationalAccount	JSON:API Relationship	The Organization's Operational Account the payment to be made to.

curl -X POST 'https://api.s.unit.sh/ready-to-launch/book-payments'
-H 'Content-Type: application/vnd.api+json'
-H 'Authorization: Bearer ${TOKEN}'
--data-raw '{
  "data": {
    "type": "bookPayment",
    "attributes": {
      "amount": 1000,
      "description": "test payment",
      "tags": {
        "test": "test"
      },
      "idempotencyKey": "unique-idempotency-key"
    },
    "relationships": {
      "account": {
        "data": {
          "type": "account",
          "id": "10013"
        }
      },
      "operationalAccount": {
        "data": {
          "type": "account",
          "id": "10020"
        }
      }
    }
  }
}'

Response

Returns details of the created book payment including status and associated resources.

Response is a JSON:API document.

200 OK

Field	Type	Description
id	string	Identifier of the book payment resource.
type	string	Type of the book payment resource. The value is always `bookPayment`.
attributes	JSON Object	JSON object representing the book payment data.
relationships	JSON:API Relationships	Describes relationships between the book payment resource and other resources.

Attributes

Name	Type	Description
createdAt	string	The date and time the payment was created.
status	string	The status of the payment.
amount	integer	Payment amount in cents.
description	string	Description of the payment.
direction	string	The direction in which the funds flow (always `Credit`).

Relationships

Name	Type	Description
account	JSON:API Relationship	The Deposit Account creating the payment.
counterpartyAccount	JSON:API Relationship	The Deposit Account that is the counterparty (receiving) account for the payment.
customer	Optional, JSON:API Relationship	The Customer the deposit account belongs to.
customers	Optional, Array of JSON:API Relationship	The list of Customers the deposit account belongs to.
transaction	JSON:API Relationship	The Book Transaction generated by this payment.

Response
{
  "data": {
    "type": "bookPayment",
    "id": "12345",
    "attributes": {
      "createdAt": "2023-10-20T10:15:22.123Z",
      "amount": 50000,
      "direction": "Credit",
      "description": "Payment transfer",
      "status": "Sent",
      "tags": {},
      "userIds": [
        "user_12345"
      ]
    },
    "relationships": {
      "account": {
        "data": {
          "type": "account",
          "id": "10004"
        }
      },
      "counterpartyAccount": {
        "data": {
          "type": "account",
          "id": "10005"
        }
      },
      "customer": {
        "data": {
          "type": "customer",
          "id": "10000"
        }
      },
      "customers": {
        "data": [
          {
            "type": "customer",
            "id": "10000"
          }
        ]
      },
      "transaction": {
        "data": {
          "type": "transaction",
          "id": "12345"
        }
      }
    }
  }
}

Theming​

Pre filling end-user information​

Inviting additional users to Banking​

Role Assignment via JWT Token​​

Allowed Roles​​

Managing End Users​​

API Endpoint Requirements​​

Custom JWT Authentication​

JWT Authentication Troubleshooting:​

Webhook Events​

Setting Up Webhooks​

Available Webhook Events for RTL Banking​

application.denied​

customer.created​

account.created​

account.frozen​

account.unfrozen​

account.closed​

account.reopened​

transaction.created​

API Calls​

Get Account​

Response​

200 OK​

Attributes​

List Accounts​

Query Parameters​

Response​

200 OK​

List Customers​

Query Parameters​

Response​

200 OK​

Attributes​

Get Transaction​

Response​

200 OK​

Attributes​

Relationships​

List Transactions​

Query Parameters​

Response​

200 OK​

Create Book Payment​

Attributes​

Relationships​

Response​

200 OK​

Attributes​

Relationships​

Theming

Pre filling end-user information

Inviting additional users to Banking

Role Assignment via JWT Token

Allowed Roles

Managing End Users

API Endpoint Requirements

Custom JWT Authentication

JWT Authentication Troubleshooting:

Webhook Events

Setting Up Webhooks

Available Webhook Events for RTL Banking

application.denied

customer.created

account.created

account.frozen

account.unfrozen

account.closed

account.reopened

transaction.created

API Calls

Get Account

Response

200 OK

Attributes

List Accounts

Query Parameters

Response

200 OK

List Customers

Query Parameters

Response

200 OK

Attributes

Get Transaction

Response

200 OK

Attributes

Relationships

List Transactions

Query Parameters

Response

200 OK

Create Book Payment

Attributes

Relationships

Response

200 OK

Attributes

Relationships