A Payable is a payment from you to another company.

With Routable, you can send a payment immediately via check or bank transfer, or schedule it to be sent on a future date.

You can specify the bank account or address to send to, or you can have your vendor go through your branded flow and submit it themselves. You can even mark a payment as paid externally, and use Routable as the bridge between you and your accounting software.

Types of Payables

Routable supports creating several different types of Payables.

Bank Transfer (type=ach)
- Create this Payable when you explicitly want to pay your vendor via bank transfer.
- Your vendor must have an existing PaymentMethod where type=bank.
- Expedited delivery_methods such as ach_next_day, ach_same_day and real_time_payment must be funded from your Routable balance Account.

Check (type=check)
- Create this Payable when you explicitly want to pay your vendor via a physically mailed check.
- Your vendor must have an existing PaymentMethod where type=address.

Cross-border (type=international)
- Create this Payable when paying a vendor in another country.
- Your vendor must have an existing PaymentMethod where type=international. They can create this in the Invite a Company or Accept Payment flows.
- You must have an existing Accounts where type=bank in order to process an international transaction.

External (type=external)
- Create this Payable when you want to track a payment that was made outside of Routable.

Vendor Choice (type=vendor_choice)
- Create this Payable when you want your vendor to be able to choose their preferred payment method.
- You may use this when your vendor has no existing payment methods and they will be prompted to submit a payment method via our onboarding flow.

Cross-border Payments

In addition to transfers within the United States, Routable supports payments to vendors in more than 200 other countries. We'll need just a little more information, but now you can pay your foreign vendors as easily as your domestic ones! See our Cross-border Payments guide for more details.

Payable Status

Payables can be in one of several statuses that indicate their state. Let's take a look.

👍

Typical Flow

Typically, Payables transition from Pending => Processing => Initiated => Completed.
Payables in a Completed state indicate that the payment has been successfully completed.

Unsuccessful payments will end in either an Issue or Failed state, and may require Routable Support to intervene.

Changeable - Non-Processing

needs_approval

An item in this state requires a user to take action on the item in the Routable dashboard per your account's approval settings.

ready_to_send

An item in this state requires either user action in the dashboard or an API call to move the item into pending, canceled, or externally_paid

scheduled

An item in this state will move to pending automatically on the date_scheduled

Unchangeable - Non-Processing

pending

An item in this state requires vendor or customer action and will be automatically transitioned to processing when the required action is completed.

Depending on the scenario, it is possible to transition an item in this state to either canceled or externally_paid by contacting [email protected]

Unchangeable - Processing

processing

An item in this state is actively being processed.

Note: A Payable only remains in the processing status for a few microseconds during Routable's backend processing. As a result, we do not fire status_changed Webhook events for the processing status. In your webhooks, listen for the the initiated status instead.

issue

An item in this state indicates that there was an issue when trying to initiate the payment.

Please contact Routable support and we can help restart the payment or move it into other final states (e.g. canceled or externally_paid).

initiated

An item in this state has had the payment initiated with our banking partners

failed

An item in this state has failed after initiating the payment.

Please contact [email protected] and our support team can help restart the payment or move it into other final states (e.g. canceled or externally_paid).

Final

canceled

An item in this state has been canceled.

externally_paid

An item in this state has been marked as externally paid.

completed

An item in this state has been paid.

Note: In some cases, payments may fail after they have Completed status. This happens when banks are late notifying us about an error with the bank account. When this happens you will receive an email notification alerting you about the failed payment.

Webhook Events for Payables

Routable supports three webhooks for monitoring changes made to Payables, whether through the API or the Routable Dashboard. They are:

• item.create when a Payable is first created
• item.status_change when a Payable transitions from one status to another
• item.approval_change when a Payable's approval status has been changed by one of your designated Approvers

Important: Use Idempotency Keys when Creating and Updating Payables

We highly recommend that you supply an idempotency key when creating payables to prevent duplicate requests. These keys are stored for a period of 24 hours.

If a request fails due to a network error, you can safely retry the same request with the same key and guarantee that your request had exactly one effect. When a request is sent with an idempotency key for an already created resource, the response object for the existing resource will be returned.

All requests with the same key will be considered attempts for the same request. It is therefore important that you use unique keys. We suggest using random values, such as UUIDs.

📘

A note on status codes

Please note that it is possible for this endpoint to return a 202 Accepted response that indicates that we are still processing the request. To ensure that the payment has been created, you may attempt to retrieve it using the returned ID or self link.

Adding Attachments to Payables

You may want to track file attachments alongside your Payables, for example, a CSV of the inventory received on a purchase order or a PDF of an invoice. You can attach one or more files, as long as the total size of your HTTP POST request, including attachments, does not exceed 25MB.

We support attaching most common formats, such as DOCX, XLSX, CSV, and PDF. To attach a file, generate a Data URL and place it in an object as follows:

{ 
    "data_uri": "data:application/pdf;base64,JVBERi0xLjMNJeLjz9...",
    "name": "filename_to_save_as_on_Routable.pdf"
}

These objects are then passed in the attachments array in the Create a Payable or Update a Payable calls.

Still have questions? No worries. See more about attachments in the Routable API.

Scheduling Payables

Routable supports 3 different ways of scheduling your payables based on the value supplied for send_on.

Sending a Payable Today
- To send a payable today, set it to today's date in Pacific time.
- Use this when you want to send a payable ASAP.

Sending a Payable in the Future
- To send a payable in the future, set send_on to a future date in Pacific time.
- Use this when you want to send a payable in the future.

Sending a Payable with no defined date
- To create a payable with no specified date, set send_on to null.
- Use this when you want to prepare a payable to be sent. This can be useful when testing out your integration.

Updating Payables

Payables can be updated while they are in any of the Changeable statuses listed above.

Versioning of Payables

Payables have a version number, which is an integer that starts with 1 when the Payable is first created. If you plan on editing your Payables, you should store the version number along with the Payable ID. When you submit a PATCH request to update a Payable, you must include the current version number. This is verified against Routable's data to ensure that you are editing the most recent version of the Payable and that you have not missed a change that has occurred elsewhere, such as by an automated process or on the Routable Dashboard. If you submitted a version number that does not match our current data, a 409 Conflict status will be returned. The returned Payable object will contain the new, incremented version number.

Line Items

When Payables are updated, you can make changes to the line items as well.

To make no changes to any of the Payable's line items, omit the line_items property entirely from the Update Payable request.

If you are adding, updating or deleting any line items, line items that are not changing should have just their id included in the Update Payable request.

// The line item with id "3b87b3d5-30d5-4bd0-a268-71f635ba973e" will remain unchanged
"line_items": [
  {
     "id": "3b87b3d5-30d5-4bd0-a268-71f635ba973e"
  }
],

To add a new line item, add a new line item data structure without an id to the line_items array.

Default Contacts

When sending Payables via our API, we will notify all contacts associated with the company based on the values specified for their default_contact_for_payable_and_receivable field.

// The line item with id "3b87b3d5-30d5-4bd0-a268-71f635ba973e" will remain unchanged
// The second line item will be added. In the following code samples, it will have
// id "9cf8f634-ba8d-4521-8ccf-523e2ba2d4ee".
"line_items": [
  {
     "id": "3b87b3d5-30d5-4bd0-a268-71f635ba973e"
  },
  { 
     "quantity": "2",
     "unit_price": "25.00",
     "amount": "50.00",
     "style": "item",
     "description": "This line item is being added."
  }
],

To update an existing line item, submit the line item data with updated fields, and include the line item's id.

// The line item with id "3b87b3d5-30d5-4bd0-a268-71f635ba973e" will remain unchanged.
// The line item with id "9cf8f634-ba8d-4521-8ccf-523e2ba2d4ee" will be updated.
"line_items": [
  {
     "id": "3b87b3d5-30d5-4bd0-a268-71f635ba973e"
  },
  { 
     "id": "9cf8f634-ba8d-4521-8ccf-523e2ba2d4ee",
     "quantity": "3",
     "unit_price": "25.00",
     "amount": "75.00",
     "style": "item",
     "description": "This line item is being edited."
  }
],

To delete a line item, submit an Update Payable request with that line item omitted entirely from the line_items array. Note that you cannot delete the last line item on a Payable.

// The line item with id "3b87b3d5-30d5-4bd0-a268-71f635ba973e" will remain unchanged.
// The line item with id "9cf8f634-ba8d-4521-8ccf-523e2ba2d4ee" will be deleted.
"line_items": [
{
"id": "3b87b3d5-30d5-4bd0-a268-71f635ba973e"
}
],

Default Approvals

When sending payables via our API and a payable requires approvals per your approval settings we will automatically fill the appropriate team members.

We do this by finding all applicable levels of approval and requesting approvals from all team members.

For example, you can set up your account so that:

• Any Payable over $1,000 requires a first level approval from either Angela or Oscar.
• Any Payable over $2,000 requires a second level approval from both Michael and Andy.

When creating a payable for $1,100, the API would request approval from both Angela and Oscar.

When creating a payable for $2,100, the API would request approval from both Michael and Andy for the second level as well as Angela and Oscar on the first level.

Accounting Software Integration

If you have an accounting application such as QuickBooks Online or Oracle NetSuite integrated with your Routable account, you will need to provide some extra data when creating a Payable. The ledger object is reserved for this purpose. Each application requires different fields on the Payable, and in some cases, the Payable's line items as well.

Visit the API Reference for a full listing of fields required for your accounting application. If you need to import configured and customized fields in Accounting Software from your accounting application, you'll need to contact the Routable Developer Experience team to assist.