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.
Pre filling end-user information
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.
To enable Bill Pay for your end customers, include the BillPay product in the requestedProducts array in the End User Configuration resource.
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}"
Programmatically create bills
If your business has knowledge of bills that your customers have paid or need to pay, you can choose to programmatically create these bills using the Bill API. You have the flexibility to submit either the file of the bill or provide the bill details as a raw JSON.
When using Ready-to-Launch, any bills you create this way will be saved as Draft. The end-customer can view the draft bill in the app, make any necessary edits, and then submit it to generate the final bill.
Upload Bill File
Uploads bill file. Supported file types are pdf, jpeg or png. Maximum image size is 1.5mb.
Unit will extract the bill details from the file via Optical Character Recognition (OCR) and create a draft bill.
| Verb | POST |
| URL | https://api.s.unit.sh/billpay/bills |
| Required Scope | billpay-bills-write |
| Timeout (Seconds) | 5 |
Headers
| Index | Value |
|---|---|
| Content-Type | One of image/png, image/jpeg, or application/pdf. |
curl \
--request PUT 'https://api.s.unit.sh/billpay/bills' \
--header 'Content-Type: multipart/form-data' \
--header 'Authorization: ${TOKEN}' \
--form 'file=@"bill.pdf"'
Submit bill details
| Verb | POST |
| URL | https://api.s.unit.sh/billpay/bills |
| Required Scope | billpay-bills-write |
| Data Type | bill |
| Timeout (Seconds) | 5 |
Attributes
Line Items
Relationships
curl -X POST 'https://api.s.unit.sh/billpay/bills'
-H 'Content-Type: application/vnd.api+json'
-H 'Authorization: Bearer ${TOKEN}'
--data-raw '{
"data": {
"type": "bill",
"attributes": {
"invoiceNumber": "1234",
"dueDate": "2025-05-10",
"date": "2025-05-10",
"tax": 1000,
"idempotencyKey": "3a1a33be-4e12-4603-9ed0-820922389fb9",
"lineItems": [
{
"totalAmount": 10000,
"description": "Love Potions",
"tax": 1000,
"quantity": 1,
"unitPrice": 1000000
}
],
"tags": {
"external_id": "uuid"
}
}
},
"relationships": {
"customer": {
"data": {
"type": "customer",
"id": "10001"
}
},
"vendor": {
"data": {
"type": "billPayVendor",
"id": "10001"
}
}
}
}'
Response
Response is a JSON:API document.
201 Created
Attributes
Relationships
{
"data": {
"type": "bill",
"id": "10001",
"attributes": {
"invoiceNumber": "1234",
"amount": 10000,
"dueDate": "2025-05-10",
"date": "2025-05-10",
"tax": 1000,
"tags": {
"external_id": "uuid"
},
"status": "Draft",
"lineItems": [
{
"totalAmount": 10000,
"description": "Invoice Line Item 1",
"tax": 1000,
"quantity": 1,
"unitPrice": 10000
}
]
}
},
"relationships": {
"customer": {
"data": {
"type": "customer",
"id": "10001"
}
},
"vendor": {
"data": {
"type": "billPayVendor",
"id": "10001"
}
}
}
}
Creating Vendors
A vendor is an individual or business entity that supplies goods or services to an end user in exchange for payment. Each customer maintains a list of vendors they transact with, and every bill must be linked to a vendor before it can be paid.
Our OCR model can automatically extract the vendor name from a bill image and match it to an existing vendor in the system. If you already have a list of vendors your customers work with, you can proactively create a vendor directory to reduce end user manual effort.
Create vendor
| Verb | POST |
| URL | https://api.s.unit.sh/billpay/vendors |
| Required Scope | billpay-vendors-write |
| Data Type | vendor |
| Timeout (Seconds) | 5 |
Attributes
Relationships
curl -X POST 'https://api.s.unit.sh/billpay/vendors'
-H 'Content-Type: application/vnd.api+json'
-H 'Authorization: Bearer ${TOKEN}'
--data-raw '{
"data": {
"type": "vendor",
"attributes": {
"idempotencyKey": "3a1a33be-4e12-4603-9ed0-820922389fb9",
"legalName": "Weasleys' Wizard Wheezes",
"address": {
"street": "93 Diagon Alley ",
"city": "Anytown",
"state": "CA",
"zip": "12345"
},
"email": "info@weasleys.com",
"phone": {
"countryCode": "1",
"number": "5555555555"
},
"website": "https://www.weasleys.com",
"logoUrl": "https://www.weasleys.com/logo.png",
"paymentMethods": {
"ach": {
"name": "Weasleys' Wizard Wheezes",
"accountNumber": "1234567890",
"routingNumber": "1234567890"
},
"wire": {
"name": "Weasleys' Wizard Wheezes",
"accountNumber": "1234567890",
"routingNumber": "1234567890",
"address": {
"street": "93 Diagon Alley ",
"city": "Anytown",
"state": "CA",
"zip": "12345"
}
},
"check": {
"name": "Weasleys' Wizard Wheezes",
"address": {
"street": "93 Diagon Alley ",
"city": "Anytown",
"state": "CA",
"zip": "12345"
}
},
"preferred": "ach"
},
"tags": {
"external_id": "uuid"
}
}
},
"relationships": {
"customer": {
"data": {
"type": "customer",
"id": "10001"
}
}
}
}'
Response
Response is a JSON:API document.
201 Created
Attributes
Relationships
{
"data": {
"type": "vendor",
"id": "10001",
"attributes": {
"legalName": "Weasleys' Wizard Wheezes",
"address": {
"street": "93 Diagon Alley ",
"city": "Anytown",
"state": "CA",
"zip": "12345"
},
"email": "info@weasleys.com",
"phone": {
"countryCode": "1",
"number": "5555555555"
},
"website": "https://www.weasleys.com",
"logoUrl": "https://www.weasleys.com/logo.png",
"paymentMethods": {
"ach": {
"name": "Weasleys' Wizard Wheezes",
"accountNumber": "1234567890",
"routingNumber": "1234567890"
},
"wire": {
"name": "Weasleys' Wizard Wheezes",
"accountNumber": "1234567890",
"routingNumber": "1234567890",
"address": {
"street": "93 Diagon Alley ",
"city": "Anytown",
"state": "CA",
"zip": "12345"
}
},
"check": {
"name": "Weasleys' Wizard Wheezes",
"address": {
"street": "93 Diagon Alley ",
"city": "Anytown",
"state": "CA",
"zip": "12345"
}
},
"preferred": "ach"
},
"tags": {
"external_id": "uuid"
}
}
},
"relationships": {
"customer": {
"data": {
"type": "customer",
"id": "10001"
}
}
}
}
Create Transaction Categories
Categories are immutable and can be associated with line items on bills. They are meant to help customers categorize expenses according to their existing Chart of Accounts. Categorized expenses help customers with their accounting and internal reporting. Categories can have subcategories.
Once a category is created it cannot be deleted, only archived.
Create category
| Verb | POST |
| URL | https://api.s.unit.sh/billpay/categories |
| Required Scope | billpay-categories-write |
| Data Type | category |
| Timeout (Seconds) | 5 |
Attributes
Subcategories
Relationships
curl -X POST 'https://api.s.unit.sh/billpay/categories'
-H 'Content-Type: application/vnd.api+json'
-H 'Authorization: Bearer ${TOKEN}'
--data-raw '{
"data": {
"type": "category",
"attributes": {
"idempotencyKey": "create-marketing-category-2024-01-15-abc123",
"name": "Marketing",
"erpId": "ERP-MKT-001",
"tags": {
"department": "marketing",
"budgetCode": "MKT-2024"
},
"subcategories": [
{
"name": "Internet Advertising",
"erpId": "ERP-MKT-INT-ADV-001",
"tags": {
"channel": "digital",
"subType": "online"
}
}
]
},
"relationships": {
"org": {
"data": {
"type": "org",
"id": "12345"
}
},
"customer": {
"data": {
"type": "customer",
"id": "10001"
}
}
}
}
}'
Linking Accounts
Control which Unit deposit accounts your customers can use to fund their bill payments. By default, all active accounts are automatically linked upon onboarding to ensure funds are available immediately.
Create Linked Account
Links a Unit deposit account to Bill Pay for a specific customer.
| Verb | POST |
| URL | https://api.s.unit.sh/billpay/linked-accounts |
| Required Scope | billpay-linked-accounts-write |
| Data Type | billpayLinkedAccount |
| Timeout (Seconds) | 5 |
Attributes
Relationships
curl -X POST 'https://api.s.unit.sh/billpay/linked-accounts'
-H 'Content-Type: application/vnd.api+json'
-H 'Authorization: Bearer ${TOKEN}'
--data-raw '{
"data": {
"type": "unitLinkedAccount",
"attributes": {
"idempotencyKey": "unique-key-123",
"tags": {}
},
"relationships": {
"account": {
"data": {
"type": "depositAccount",
"id": "12345"
}
},
"customer": {
"data": {
"type": "customer",
"id": "10006"
}
}
}
}
}'
Response
Response is a JSON:API document.
201 Created
Attributes
Relationships
{
"data": {
"type": "billpayLinkedAccount",
"id": "15",
"attributes": {
"name": "Primary Business Account",
"createdAt": "2024-02-07T15:24:51.179Z",
"updatedAt": "2024-02-07T15:24:51.179Z",
"tags": {}
},
"relationships": {
"customer": {
"data": {
"type": "customer",
"id": "10006"
}
},
"account": {
"data": {
"type": "depositAccount",
"id": "12345"
}
},
"org": {
"data": {
"type": "org",
"id": "1"
}
}
}
}
}
Get Linked Account
Get a linked account resource by id.
| Verb | GET |
| URL | https://api.s.unit.sh/billpay/linked-accounts/{id} |
| Required Scope | billpay-linked-accounts |
| Timeout (Seconds) | 5 |
Response
Response is a JSON:API document.
200 OK
The response includes the linked Unit deposit account in the account relationship.
curl -X GET 'https://api.s.unit.sh/billpay/linked-accounts/15' \
-H "Authorization: Bearer ${TOKEN}"
Archive Linked Account
Archives a linked account, deactivating it for Bill Pay. Archived accounts will not be shown as an option in the UI and bills scheduled for payment using this account will not be paid.
| Verb | POST |
| URL | https://api.s.unit.sh/billpay/linked-accounts/{id}/archive |
| Required Scope | billpay-linked-accounts-write |
| Data Type | billpayLinkedAccount |
| Timeout (Seconds) | 5 |
Attributes
curl -X POST 'https://api.s.unit.sh/billpay/linked-accounts/{id}/archive'
-H 'Content-Type: application/vnd.api+json'
-H 'Authorization: Bearer ${TOKEN}'
--data-raw '{
"data": {
"type": "linkedAccount",
"attributes": {
"idempotencyKey": "unique-key-456"
}
}
}'
Response
Response is a JSON:API document.
200 OK
Returns the archived linked account resource.
List Linked Accounts
List linked accounts. Filtering and paging can be applied.
| Verb | GET |
| URL | https://api.s.unit.sh/billpay/linked-accounts |
| Required Scope | billpay-linked-accounts |
| Timeout (Seconds) | 5 |
Query Parameters
| Name | Type | Default | Description |
|---|---|---|---|
| page[limit] | integer | 100 | Optional. Maximum number of resources that will be returned. Maximum is 1000 resources. See Pagination. |
| page[offset] | integer | 0 | Optional. Number of resources to skip. See Pagination. |
| filter[ids] | string[] | (empty) | Optional. Filters the results by the specified linked account ids. |
| filter[customerId] | integer | (empty) | Optional. Filters the results by the specified customer id. |
| filter[orgId] | integer | (empty) | Optional. Filters the results by the specified organization id. |
| filter[tags] | Tags (JSON) | (empty) | Optional. Filter linked accounts by Tags. |
| filter[status] | string | (empty) | Optional. Filters by status. One of Active or Archived. |
curl -X GET 'https://api.s.unit.sh/billpay/linked-accounts?filter[customerId]=10006' \
-H "Authorization: Bearer ${TOKEN}"
Response
Response is a JSON:API document.
200 OK
account relationship.{
"data": [
{
"type": "billpayLinkedAccount",
"id": "15",
"attributes": {
"name": "Primary Business Account",
"createdAt": "2024-02-07T15:24:51.179Z",
"updatedAt": "2024-02-07T15:24:51.179Z",
"tags": {}
},
"relationships": {
"customer": {
"data": {
"type": "customer",
"id": "10006"
}
},
"account": {
"data": {
"type": "depositAccount",
"id": "12345"
}
},
"org": {
"data": {
"type": "org",
"id": "1"
}
}
}
},
{
"type": "billpayLinkedAccount",
"id": "16",
"attributes": {
"name": "Secondary Business Account",
"createdAt": "2024-02-08T10:30:00.000Z",
"updatedAt": "2024-02-08T10:30:00.000Z",
"tags": {}
},
"relationships": {
"customer": {
"data": {
"type": "customer",
"id": "10006"
}
},
"account": {
"data": {
"type": "depositAccount",
"id": "12346"
}
},
"org": {
"data": {
"type": "org",
"id": "1"
}
}
}
}
]
}
Customer Activation and Deactivation
Control Bill Pay access by activating or deactivating customers via API. Use this to enforce paywalls or subscription requirements. Customers are active by default.
Deactivated customers see a read-only UI with their existing bill data. They cannot create new bills or pay bills.
When you deactivate a customer, we automatically refund any in-flight payments. This includes ACH payments not yet transmitted and checks mailed but not yet deposited. Funds return to the customer's deposit account Both activate and deactivate operations are idempotent - if the config is already in the target state, the operation returns the existing config without making changes.
Activate Bill Pay Customer
Activates a customer's Bill Pay configuration, enabling Bill Pay functionality for the customer.
| Verb | POST |
| URL | https://api.s.unit.sh/customers/:customerId/billpay/activate |
| Required Scope | billpay-customer-config-write |
| Data Type | billpayCustomerConfig |
| Timeout (Seconds) | 5 |
Attributes
curl -X POST 'https://api.s.unit.sh/customers/:customerId/billpay/activate'
-H 'Content-Type: application/vnd.api+json'
-H 'Authorization: Bearer ${TOKEN}'
--data-raw '{
"data": {
"type": "billpayCustomerConfig",
"attributes": {
"idempotencyKey": "activate-billpay-12345-2026-02-01"
}
}
}'
Response
Response is a JSON:API document.
200 OK
Attributes
Active after successful activation.Relationships
{
"data": {
"type": "billpayCustomerConfig",
"attributes": {
"passthroughAccountId": "10014",
"status": "Active"
},
"relationships": {
"org": {
"data": {
"type": "org",
"id": "5"
}
},
"billpayTerms": {
"data": {
"type": "billpayTerms",
"id": "1000"
}
},
"customer": {
"data": {
"type": "customer",
"id": "10008"
}
}
}
}
}
Deactivate Bill Pay Customer
Deactivates a BIll Pay Customer. Deactivated customers see a read-only UI with their existing bill data. They cannot create new bills or pay bills.
When you deactivate a customer, we automatically refund any in-flight payments. This includes ACH payments not yet transmitted and checks mailed but not yet deposited. Funds return to the customer's deposit account.
| Verb | POST |
| URL | https://api.s.unit.sh/customers/:customerId/billpay/deactivate |
| Required Scope | billpay-customer-config-write |
| Data Type | billpayCustomerConfig |
| Timeout (Seconds) | 5 |
Attributes
curl -X POST 'https://api.s.unit.sh/customers/:customerId/billpay/deactivate'
-H 'Content-Type: application/vnd.api+json'
-H 'Authorization: Bearer ${TOKEN}'
--data-raw '{
"data": {
"type": "billpayCustomerConfig",
"attributes": {
"idempotencyKey": "deactivate-billpay-12345-2026-02-01"
}
}
}'
Response
Response is a JSON:API document.
200 OK
Attributes
Inactive after successful deactivation.Relationships
{
"data": {
"type": "billpayCustomerConfig",
"attributes": {
"passthroughAccountId": "10014",
"status": "Inactive"
},
"relationships": {
"org": {
"data": {
"type": "org",
"id": "5"
}
},
"billpayTerms": {
"data": {
"type": "billpayTerms",
"id": "1000"
}
},
"customer": {
"data": {
"type": "customer",
"id": "10008"
}
}
}
}
}
Set Bill Pay Reactivation URL
Set the URL where customers land when they click to reactivate Bill Pay. This should be your platform's billing or plan selection page.
Dashboard Configuration
If you have access to the Unit Dashboard, you can configure this URL through the Ready to Launch Admin Settings in the Dashboard:
- Navigate to the Ready to Launch Settings page
- Click on the Callbacks tab
- Locate the Reactivation Bill Pay Page URL field
- Enter the URL where customers should be redirected for Bill Pay reactivation
- Click Save
API Configuration
You can also configure this URL programmatically using the White Label App Config API.
| Verb | PATCH |
| URL | https://api.s.unit.sh/white-label/app/configs |
| Required Scope | white-label-config-write |
| Timeout (Seconds) | 5 |
Attributes
Relationships
{
"data": {
"type": "whiteLabelAppConfig",
"attributes": {
"billpayReactivationPageURL": "https://example.com/billpay/reactivate"
},
"relationships": {
"org": {
"data": {
"type": "org",
"id": "5"
}
}
}
}
}