Skip to main content
Ready-to-LaunchCustom Builds
Start Building Now

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.

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.

FieldTypeDescription
fullNameFullNameFull name of the end user.
emailstringEmail address of the end user.
phonePhonePhone number of the end user.
jwtSubjectstringUnique string identifying the end user.
unitRolestringThe role of the end user. Can be either Admin or ReadOnly.
bankingPageURLstringOptional. 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:

ClaimDescription
subA unique identifier for the end-user
expThe expiration time of the token
issThe 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:

  1. Implement an endpoint on your server to receive and process webhook payloads
  2. 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
  3. 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:

EnvironmentIP Addresses
Sandbox54.81.62.38
35.169.213.205
3.234.105.75
Live3.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,
        "userIds": [
          "user_12345"
        ]
      },
      "relationships": {
        "account": {
          "data": {
            "id": "10004",
            "type": "account"
          }
        },
        "customer": {
          "data": {
            "id": "10000",
            "type": "customer"
          }
        }
      }
    }
  ]
}