Clio Payments API

Third-party applications in Clio have the ability to leverage Clio Payments by generating links to our hosted payment pages and sharing them to their clients.

Access to Clio Payments API will require the authenticating user to accept the clio_payments scope during the OAuth authorization process.

Payments can only be collected for accounts that have enabled Clio Payments, can only be used for bank accounts that are connected to Clio Payments (see the clio_payments_enabled Bank Account field), and can only be made in the currency that the account is set up to use. The accepted currencies per account's country are:

United States: USD
Canada: CAD
United Kingdom: GBP

Creating a Payment Link

A payment link can be used to pay an existing invoice or trust request. Alternatively, a payment link can be used to collect an amount from a client which can either be later applied to an invoice or simply collected as a revenue payment.

To create a payment link, make a POST request to the /api/v4/clio_payments/links endpoint. The required fields depend on the type of payment link being created.

The following limitations exist for the creation of payment links in the API:

The maximum duration that a payment link can be active for is 90 days.
The maximum number of payment links that can active on the account at any given time is 50 times the number of users in the account.
The maximum number of payment links that can be created in a 24-hour period is 50 times the number of users in the account.

A payment link is single-use. Once a payment link has been used, it will immediately expire.

Paying off existing invoice(s) or a trust request

When creating a payment link for paying off existing invoice(s) or trust requests, the following fields are required:

Parameter	Type	Description
currency	string	The currency the payment will be processed in. The supported currency depends on the account's location (ie. "USD" for a US account). The currency must be a valid ISO 4217 currency code.
destination_account	object	The bank account that the payment will be deposited into.
duration	number	The amount of time, in seconds, that the payment link will be active for. The maximum allowed value is `7776000` (90 days in seconds).
subject	object	An object representing an associated record in Manage. This property determines the behaviour around the payment once it's received. The object must contain two properties: - `id`: the ID of the record associated with the payment link. - `type`: a string representing the type of record. This value should be set to `"Bill"` for payment links for an invoice or trust request to be paid, or `"Contact"` for payment links for a contact with outstanding invoices whose balance will be paid.

Additionally, the following fields are optional:

Parameter	Type	Description
amount	number	The amount to be paid. If not provided, the client will be able to specify an amount - up to the full amount of the invoice(s) or trust request.
email_address	string	Prefills the relevant field for the client when filling out their details in the payment link.
redirect_url	string	The URL to redirect the client to after the payment has been made.

A sample request body to create a payment link for paying off an existing invoice is:

{
  "data": {
    "amount": 100.00,
    "currency": "USD", 
    "destination_account": {
      "id": 123456
    },
    "duration": 86400,
    "email_address": "test@example.com",
    "redirect_url": "https://example.com",
    "subject": {
      "id": 123456,
      "type": "Bill"
    }
  }
}

Collecting a direct payment

Payments can be collected directly into a bank account as either revenue or as an unallocated balance that can be applied to future invoices. To collect a direct payment, the following fields are required:

Parameter	Type	Description
currency	string	The currency the payment will be processed in. The supported currency depends on the account's location (ie. "USD" for a US account). The currency must be a valid ISO 4217 currency code.
description	string	A short description of the purpose of the payment. Max 255 characters.
duration	number	The amount of time, in seconds, that the payment link will be active for. The maximum allowed value is `7776000` (90 days in seconds).
subject	object	An object representing an associated record in Manage. This property determines the behaviour around the payment once it's received. The object must contain two properties: - `id`: the ID of the record associated with the payment link. - `type`: a string representing the type of record. This value should be set to `"BankAccount"` for payment links for a direct payment.

Additionally, the following fields are optional:

Parameter	Type	Description
amount	number	The amount to be paid. If not provided, the client will be able to specify an amount.
destination_contact	object	The contact that the payment will be associated with. If not defined, and the payment is collecting an unallocated balance, then the payment can be associated with a contact manually within Manage after it has been made.
email_address	string	Prefills the relevant field for the client when filling out their details in the payment link.
is_allocated_as_revenue	boolean	If true, the payment will be allocated as revenue. If false, the payment will be collected as an unallocated balance. Defaults to false.
redirect_url	string	The URL to redirect the client to after the payment has been made. The URL must match one of the base URLS for payment links specified in your application settings in the developer portal.

A sample request body to create a payment link for collecting a direct payment is:

{
  "data": {
    "amount": 100.00,
    "currency": "USD",
    "description": "Reason XYZ",
    "destination_contact": {
      "id": 123456
    },
    "duration": 86400,
    "email_address": "test@example.com",
    "is_allocated_as_revenue": "true",
    "redirect_url": "https://example.com",
    "subject": {
      "id": 123456,
      "type": "BankAccount"
    }
  }
}

Retrieving Payment Links

To retrieve a list of payment links, make a GET request to the /api/v4/clio_payment_links endpoint. The response will contain an array of payment links.

Filtering Payment Links

Payment links can be filtered by the following parameters:

Parameter	Type	Description
active	boolean	If true, only active payment links will be returned. If false, only inactive payment links will be returned. If not provided, all payment links will be returned.

A sample request to retrieve all active payment links is:

GET /api/v4/clio_payment_links?active=true

Available Payment Link Fields

When retrieving payment links, the following fields are available:

Field	Type	Description
active	boolean	Whether the payment link is active.
amount	number	The defined amount of the payment link, if set.
bank_account	object	The payment link's subject if the payment link is a direct payment.
bill	object	The payment link's subject if the payment link is to pay off an invoice or trust request.
clio_payments_payment	object	The payment that was made through the payment link.
contact	object	The payment link's subject if the payment link is to pay off the outstanding balance of a contact.
created_at	string	The ISO 8601 date and time the payment link was created.
currency	string	The currency the payment link will collect.
description	string	The defined description of the payment link, if set.
destination_account	object	The bank account that the payment will be deposited into.
destination_contact	object	The contact that a direct payment will be associated with.
email_address	string	The email address to prefill the field on the the payment link, if set.
etag	string	The ETag of the payment link.
expires_at	string	The ISO 8601 date and time the payment link will expire.
id	number	The unique identifier of the payment link.
is_allocated_as_revenue	boolean	Whether the payment link is allocated as revenue.
redirect_url	string	The URL to redirect the client to after the payment has been made.
url	string	The URL of the payment link.

Retrieving Details of Payments Made

To retrieve the details of payments made, make a GET request to the /api/v4/clio_payments/payments endpoint. The endpoint will return only the details of the payments made via payment links that your application has created.

Filtering Payments

Payments can be filtered by the following parameters:

Parameter	Type	Description
bill_id	number	The ID of a bill that the payment is associated with.
contact_id	number	The ID of a contact that the payment is associated with.
ids	array	An array of payment IDs to retrieve.
state	string	The state of the payment (authorized, completed, failed, etc).

Available Payment Fields

When retrieving payments, the following fields are available:

Field	Type	Description
allocations	array	Any allocations associated with the payment. Refer to the allocations documentation for serializable fields.
amount	number	The amount of the payment.
bank_transaction	object	The bank transaction associated with the received payment. Refer to the bank transactions documentation for serializable fields. Note: A payment without an associated a contact or matter will not have a bank transaction until an association is created.
bills	array	Any bills that the payment amount is or will be allocated to. Refer to the bills documentation for serializable fields.
clio_payments_link	object	The payment link that the payment was made through.
confirmation_number	string	The confirmation number of the payment.
contact	object	The contact that the payment is associated with.
created_at	string	The ISO 8601 date and time the payment was created.
currency	string	The currency the payment was processed in.
deposit_as_revenue	boolean	Whether the payment was deposited as revenue.
description	string	The description of the payment.
destination_account	object	The bank account that the payment was deposited into. Refer to the bank accounts documentation for serializable fields.
email_address	string	The email address of the client.
id	number	The unique identifier of the payment.
matters	array	Any matters the payment amount is or will be allocated to. Refer to the matters documentation for serializable fields.
state	string	The state of the payment (authorized, completed, failed, etc).
updated_at	string	The ISO 8601 date and time the payment was last updated.
user	object	The user that created the payment link that resulted in the payment. Refer to the users documentation for serializable fields.

Using Webhooks

To receive notifications of changes to payments, you can use the Webhooks API. The clio_payments_payment event will be triggered when a payment is created or updated. Deleted events are not supported for payments as payments can not be deleted.

Creating a Payment Link​

Paying off existing invoice(s) or a trust request​

Collecting a direct payment​

Retrieving Payment Links​

Filtering Payment Links​

Available Payment Link Fields​

Retrieving Details of Payments Made​

Filtering Payments​

Available Payment Fields​

Using Webhooks​