Download OpenAPI specification:Download
This API is for creating and managing billing accounts and is currently available exclusively for UK-based merchants. A billing account serves as a record of transactions and payments for a collection of orders. It helps track and manage the payments a customer owes for the services or products they have received. Billing accounts can be linked to specific businesses and are used to generate grouped payment statements.
To request access to the billing account service, please contact our team at support@two.inc.
The API enables you to:
Below is a typical flow of how the API endpoints are used to create a new billing account.
Use POST /billing/v1/account
to create a new billing account for a given company by passing their legal name and number and defining the billing account configuration for the payment terms,
schedule and any delay days. The request response will return a global id
which represents the billing_account_id
.
When building the request body for creating an order POST /order
you can specify the billing_account_id
when creating
an order. This will then attach the order to the specified billing account.
Schedule
Due in Days
due in days
setting specifies the payment terms for all orders assigned to the billing account.
The total repayment period is calculated based on the schedule and the "due in days" you set.
For example, if you choose a schedule
of DAILY
and set due_in_days
to 14, your buyer will have 14 days to pay their order from the time they receive their statement, which in this setup, starts the next day.
A common configuration we support is "End of Month plus 30 days." To achieve this, set the schedule to MONTHLY and the due_in_days to 30. This setup will allow billing account recipients to receive their grouped statement at the end of the month, with payment terms starting from that date.
As a rule, the payment term begins when the billing account recipients receive their statement.Generation Delay Days
Account Name
The endpoint POST /billing/v1/account
enables the merchant to create a new billing account for a specific buyer. A billing account is a record of financial transactions for goods or services that a customer or client has received and owes payment for. This endpoint allows you to configure the terms and configuration of the billing account through the request body. Key configurations include, the billing account schedule
, due_in_days
, currency
, invoice_email
, cc_email_addresses
, primary_email_addresses
, generation_delay_days
and the buyer_company
Create billing account
Error response
{- "primary_email_addresses": [
- "user@example.com"
], - "cc_email_addresses": [
- "user@example.com"
], - "schedule": "DAILY",
- "buyer_company": {
- "country_prefix": "GB",
- "organization_number": "string",
- "company_name": "string",
- "company_type": "string",
}, - "due_in_days": 5,
- "currency": "NOK",
- "generation_delay_days": 4,
- "account_name": "string",
- "phone_number": "string"
}
{- "primary_email_addresses": [
- "user@example.com"
], - "cc_email_addresses": [
- "user@example.com"
], - "schedule": "DAILY",
- "buyer_company": {
- "country_prefix": "GB",
- "organization_number": "string",
- "company_name": "string",
- "company_type": "string",
}, - "due_in_days": 0,
- "currency": "NOK",
- "generation_delay_days": 4,
- "account_name": "string",
- "phone_number": "string",
- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08"
}
Note: To update primary_email_addresses, cc_email_addresses, trade_names the request body must include all new values, including values that are not being updated. So if you are adding or removing even a single email to the emailing lists (primary_email_addresses
& cc_email_addresses
), the entire list must be provided with the updates you need to make.
Update billing account
The billing account with the given ID was not found
Error response
{- "due_in_days": 5,
- "generation_delay_days": 4,
- "primary_email_addresses": [
- "user@example.com"
], - "cc_email_addresses": [
- "user@example.com"
], - "account_name": "string",
- "phone_number": "string"
}
{- "primary_email_addresses": [
- "user@example.com"
], - "cc_email_addresses": [
- "user@example.com"
], - "schedule": "DAILY",
- "buyer_company": {
- "country_prefix": "GB",
- "organization_number": "string",
- "company_name": "string",
- "company_type": "string",
}, - "due_in_days": 0,
- "currency": "NOK",
- "generation_delay_days": 4,
- "account_name": "string",
- "phone_number": "string",
- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08"
}
The endpoint /billing/v1/account/{id}
allows you to fetch the details for a given billing account that has been specified by its id
OK
The billing account with the given ID was not found
Error response
{- "primary_email_addresses": [
- "user@example.com"
], - "cc_email_addresses": [
- "user@example.com"
], - "schedule": "DAILY",
- "buyer_company": {
- "country_prefix": "GB",
- "organization_number": "string",
- "company_name": "string",
- "company_type": "string",
}, - "due_in_days": 0,
- "currency": "NOK",
- "generation_delay_days": 4,
- "account_name": "string",
- "phone_number": "string",
- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08"
}
returns the statement as a file. Can choose period_status by status parameter. This will default to OPEN. Args: account_id (UUID): Billing account ID
OK
The billing account with the given ID was not found
Error response
{- "error_message": "string"
}
The list with all grouped payment statements for authenticated merchant.
Error response
{- "statements": [
- {
- "statement_id": "6fcc7115-8e6b-40cd-9754-72e975d1d953",
- "statement_number": 0,
- "statement_reference": "string",
- "buyer_company_name": "string",
- "start_date": "2019-08-24T14:15:22Z",
- "end_date": "2019-08-24T14:15:22Z",
- "payment_status": "NOT_PAID",
- "payment_reference": "string",
- "total_amount": "string",
- "last_downloaded": "2019-08-24T14:15:22Z",
- "statement_type": "string",
- "issue_date": "2019-08-24",
- "due_date": "2019-08-24",
- "currency": "NOK",
- "unreconciled_amount": "string",
- "statement_pis_link": "string",
- "trade_names": [
- "string"
], - "billing_account_id": "db2251e5-5308-40a7-9f48-3aed5a9ce736",
- "billing_period_id": "05a6ed6a-04eb-421a-9ac9-9a43b3353a4d",
- "creation_reason": "string"
}
], - "cursor_page_metadata": {
- "previous_page_cursor": "cursor to the previous page",
- "next_page_cursor": "cursor to the next page",
- "limit": 0
}
}
The download URL for the statement document.
Statement not found
Error response
{- "url": "string"
}
"Statements" object: Contains all statements issued by Two for this billing period, each statement object reflecting information displayed on the statements the moment they were issued. This section does not change unless a new statement is issued. "Totals" section: Shows the latest reconciliation status of the billing period, and gets updated real-time as each transaction (payments, refunds, etc.) related to invoices in the billing period are reconciled. It shows the current financial status of the billing period, including the currently outstanding balance, and the total payments, total refunds, etc. reconciled against these invoices. To get these details with more granularity, you should subscribe to our webhooks here. Args: billing_account_id (str): Billing account identifier period_id (str): Billing period identifier
Billing period summary
The billing period with the given attributes was not found
Error response
{- "id": "string",
- "billing_account_id": "string",
- "start_date": "2019-08-24",
- "end_date": "2019-08-24",
- "currency": "NOK",
- "totals": {
- "invoiced_amount": "string",
- "paid_amount": "string",
- "credited_amount": "string",
- "collected_amount": "string",
- "recoursed_amount": "string",
- "outstanding_amount": "string",
- "last_updated": "2019-08-24T14:15:22Z"
}, - "statements": [
- {
- "statement_id": "string",
- "statement_number": 0,
- "statement_suffix": "string",
- "statement_reference": "string",
- "statement_creation_reason": "string",
- "issue_date": "2019-08-24",
- "due_date": "2019-08-24",
- "buyer_company_name": "string",
- "payment_reference": "string",
- "total_amount": "string",
- "outstanding_amount": "string",
- "last_downloaded": "2019-08-24T14:15:22Z"
}
], - "bank_account": {
- "payment_reference": "string",
- "account_name": "string",
- "account_number": "string",
- "sort_code": "string",
- "iban": "string",
- "bban": "string",
- "bic": "string"
}
}