Payment Statuses

Payments in Routable, such as Payables and Receivables, have a lifecycle defined by the payment's status field.

Typical Payment Lifecycle

When you create a payment, it typically begins in one of three pre-send states: needs_approval, ready_to_send and scheduled.

If you have Approval Rules configured, a needs_approval step will happen before the payment enters the pending state.

If you specified a send_on date in the future, the payment will remain in a scheduled status until that date arrives and then send it. If you specified a null value for send_on, the payment will remain in the ready_to_send status until you update it to send the payment. If you omit the send_on entirely, the payment will be sent immediately.

Once the payment is sent, it will transition through pending while Routable sends the information to our banking partners, processing when the transaction is being processed in the banking system, and finally completed when the payment has arrived in the recipient's bank or a physical check has been mailed.

Unsuccessful payments will end in either an issue or failed state, and may require Routable Support to intervene to cancel or retry them.

Status Details

Changeable - Non-Processing

needs_approval

An Item in this state requires one or more TeamMembers to take action to release the Item in the Routable Dashboard per your account's approval settings.

ready_to_send

An Item in this state requires TeamMember action either via the Routable Dashboard or an API call to move the Item into the pending, canceled, or externally_paid status.

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, the Routable Support team may be able to help you transition a Item in this state to either canceled or externally_paid.

Unchangeable - Processing

processing

An Item in this state is actively being processed.

Note: An Item 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 Item. This can occur if, for example, an invalid bank account number has been provided or there are insufficient funds to complete a transfer.

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

initiated

An Item in this state has had the funds transfer initiated with Routable's banking partners.

failed

An Item in this state has failed after the funds transfer was initiated.

Please contact Routable Support and we can help restart the Item 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 rare cases, Items may fail after they have reached 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 transfer.

Webhook Notifications of Status Changes

When a payment's status changes, an item.status_change webhook is triggered. You can configure your system to listen for these webhook events to update your internal data or take action as needed when a payment reaches certain states.

Status Timeline of a Payable or Receivable

Both Payables and Receivables have a status_changes array when retrieved from the API. This array contains a list of all the statuses the payment has visited and the timestamp at which it transitioned into that state.