Skip to main content

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

1-2 days

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

1-2 days

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.

VerbPOST
URLhttps://api.s.unit.sh/billpay/bills
Required Scopebillpay-bills-write
Timeout (Seconds)5

Headers

IndexValue
Content-TypeOne 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

VerbPOST
URLhttps://api.s.unit.sh/billpay/bills
Required Scopebillpay-bills-write
Data Typebill
Timeout (Seconds)5

Attributes

invoiceNumber
string
Invoice number.
amount
cents
Bill amount.
dueDate
RFC3339 Date string
Bill due date.
date
RFC3339 Date string
Bill date.
tax
percentage
Bill tax.
lineItems
object[]
Bill line items.
tagsOptional
object
Optional. See Tags.

Line Items

totalAmount
cents
Line item total amount.
description
string
Line item description.
quantity
integer
Line item quantity.
unitPrice
cents
Line item unit price.
category
identifier
Line item category id.

Relationships

customer
JSON:API Relationship
Customer to which the vendor belongs.
vendor
Optional, JSON:API Relationship
Bill Vendor
Example Request:
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

invoiceNumber
string
Invoice number.
amount
cents
Bill amount.
dueDate
RFC3339 Date string
Bill due date.
date
RFC3339 Date string
Bill date.
tax
percentage
Bill tax.
lineItems
object[]
Bill line items.
tagsOptional
object
Optional. See Tags.
createdAt
RFC3339 Date string
The date the resource was created.
updatedAtOptional
RFC3339 Date string
Optional. The date the resource was updated.

Relationships

customer
JSON:API Relationship
Customer to which the vendor belongs.
vendor
Optional, JSON:API Relationship
Bill Vendor
Example Response:
{
"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

1-2 days

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

VerbPOST
URLhttps://api.s.unit.sh/billpay/vendors
Required Scopebillpay-vendors-write
Data Typevendor
Timeout (Seconds)5

Attributes

idempotencyKeyOptional
string
Optional. See Idempotency.
legalName
string
Vendor legal name.
address
object
Vendor address.
email
string
Vendor email.
phone
object
Vendor phone.
website
string
Vendor website.
logoUrl
string
Vendor logo URL.
paymentMethods
object
Vendor payment methods.
tagsOptional
object
Optional. See Tags.

Relationships

customer
JSON:API Relationship
Customer to which the vendor belongs.
Example Request:
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

legalName
string
Vendor legal name.
address
object
Vendor address.
email
string
Vendor email.
phone
object
Vendor phone.
website
string
Vendor website.
logoUrl
string
Vendor logo URL.
paymentMethods
object
Vendor payment methods.
tagsOptional
object
Optional. See Tags.
createdAt
RFC3339 Date string
The date the resource was created.
updatedAtOptional
RFC3339 Date string
Optional. The date the resource was updated.

Relationships

customer
JSON:API Relationship
Customer to which the vendor belongs.
Example Response:
{
"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

1-2 days

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

VerbPOST
URLhttps://api.s.unit.sh/billpay/categories
Required Scopebillpay-categories-write
Data Typecategory
Timeout (Seconds)5

Attributes

idempotencyKeyOptional
string
Optional. See Idempotency.
name
string
Category name.
erpIdOptional
string
Optional. ERP identifier for the category.
tagsOptional
object
Optional. See Tags.
subcategoriesOptional
object[]
Optional. Array of subcategories. Mutually exclusive with parentId relationship.

Subcategories

name
string
Subcategory name.
erpIdOptional
string
Optional. ERP identifier for the subcategory.
tagsOptional
object
Optional. See Tags.

Relationships

org
JSON:API Relationship
Organization to which the category belongs.
customer
JSON:API Relationship
Customer to which the category belongs.
parentIdOptional
JSON:API Relationship
Optional. Parent category. Mutually exclusive with subcategories attribute.
Example Request:
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

1-2 days

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.

VerbPOST
URLhttps://api.s.unit.sh/billpay/linked-accounts
Required Scopebillpay-linked-accounts-write
Data TypebillpayLinkedAccount
Timeout (Seconds)5

Attributes

idempotencyKeyRequired
string
Required. See Idempotency. Length 1–255 characters.
tagsOptional
object
Optional. See Tags.

Relationships

accountRequired
JSON:API Relationship
Required. The Unit deposit account to link to Bill Pay. Type must be depositAccount or account.
customerOptional
JSON:API Relationship
Optional. Customer to which the linked account belongs.
Example Request:
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

name
string
The friendly name for the linked account.
createdAt
RFC3339 Date string
The date the resource was created.
updatedAtOptional
RFC3339 Date string
Optional. The date the resource was updated.
tagsOptional
object
Optional. See Tags.

Relationships

customer
JSON:API Relationship
Customer to which the linked account belongs.
account
JSON:API Relationship
The Unit deposit account linked to Bill Pay.
org
JSON:API Relationship
Organization to which the linked account belongs.
Example Response:
{
"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.

VerbGET
URLhttps://api.s.unit.sh/billpay/linked-accounts/{id}
Required Scopebillpay-linked-accounts
Timeout (Seconds)5

Response

Response is a JSON:API document.

200 OK

data
billpayLinkedAccount
The linked account resource.

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.

VerbPOST
URLhttps://api.s.unit.sh/billpay/linked-accounts/{id}/archive
Required Scopebillpay-linked-accounts-write
Data TypebillpayLinkedAccount
Timeout (Seconds)5

Attributes

idempotencyKeyRequired
string
Required. See Idempotency. Length 1–255 characters.
Example Request:
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.

VerbGET
URLhttps://api.s.unit.sh/billpay/linked-accounts
Required Scopebillpay-linked-accounts
Timeout (Seconds)5

Query Parameters

NameTypeDefaultDescription
page[limit]integer100Optional. Maximum number of resources that will be returned. Maximum is 1000 resources. See Pagination.
page[offset]integer0Optional. 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

data
Array of billpayLinkedAccount
Array of linked account resources. Each resource includes the linked Unit deposit account in the account relationship.
Example Response:
{
"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.

VerbPOST
URLhttps://api.s.unit.sh/customers/:customerId/billpay/activate
Required Scopebillpay-customer-config-write
Data TypebillpayCustomerConfig
Timeout (Seconds)5

Attributes

idempotencyKey
string
Example Request:
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

status
string
The status of the Bill Pay configuration. Will be Active after successful activation.

Relationships

org
JSON:API Relationship
Organization to which the configuration belongs.
billpayTerms
JSON:API Relationship
The Bill Pay terms associated with this configuration.
customer
JSON:API Relationship
Customer to which the configuration belongs.
Example Response:
{
"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.

VerbPOST
URLhttps://api.s.unit.sh/customers/:customerId/billpay/deactivate
Required Scopebillpay-customer-config-write
Data TypebillpayCustomerConfig
Timeout (Seconds)5

Attributes

idempotencyKey
string
Example Request:
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

status
string
The status of the Bill Pay configuration. Will be Inactive after successful deactivation.

Relationships

org
JSON:API Relationship
Organization to which the configuration belongs.
billpayTerms
JSON:API Relationship
The Bill Pay terms associated with this configuration.
customer
JSON:API Relationship
Customer to which the configuration belongs.
Example Response:
{
"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:

  1. Navigate to the Ready to Launch Settings page
  2. Click on the Callbacks tab
  3. Locate the Reactivation Bill Pay Page URL field
  4. Enter the URL where customers should be redirected for Bill Pay reactivation
  5. Click Save

API Configuration

You can also configure this URL programmatically using the White Label App Config API.

VerbPATCH
URLhttps://api.s.unit.sh/white-label/app/configs
Required Scopewhite-label-config-write
Timeout (Seconds)5

Attributes

billpayReactivationPageURLOptional
string
Optional. The URL where customers land when they click to reactivate Bill Pay.

Relationships

org
JSON:API Relationship
Organization to which the configuration belongs.
{
"data": {
"type": "whiteLabelAppConfig",
"attributes": {
"billpayReactivationPageURL": "https://example.com/billpay/reactivate"
},
"relationships": {
"org": {
"data": {
"type": "org",
"id": "5"
}
}
}
}
}